Overview

The Occuspace API provides real-time and historical occupancy data for Occuspace-enabled locations.


Its RESTful interface returns JSON data for all endpoints. These endpoints provide information on the installed locations and occupancy data - both real-time and historical count estimations - for these locations.


All requests are authenticated using Authorization Bearer tokens. Tokens are provided directly by the Occuspace team.

Base URL
https://api.occuspace.io/v1

Authentication

All requests are authenticated using an API token in the Authorization header of the request.


API tokens are generated by the Occuspace team and are cycled upon request.

Authorization Header
Authorization: Bearer {YOUR_API_TOKEN}

Errors

User Request errors are 4XX status codes. Our API uses standard 400, 401 and 404 error codes.


400 Bad requests are caused by invalid arguments. If possible, the error sent back will specify how the provided argument is invalid.


401 Unauthorized requests occur when:

  1. Authorization header is missing from request
  2. No token provided in header
  3. Invalid token is used
  4. Inaccessible locations are requested

404 requests occur whenever a requested endpoint does not exist. It will send back the standard Node express server 404 HTML response.


Any Occuspace Server errors will comeback as 500 "Internal Server" errors.

Error Codes

400 - Bad Request

Invalid Arguments

401 - Unauthorized Request

Requesting unpermitted data OR providing invalid/no authorization token

404 - Resource Not Found

Requesting an endpoint that does not exist

500 Internal Server Error

Something went wrong on Occuspace’s part

Response Format

All successful responses have 2 Properties: message and data.


The message property will give information about the request and status of the response. If there is nothing out of the ordinary, the response will be: "message": "OK".


In the event that a successful response that may have a slight discrepancy from the user’s request, the message field will explain any unexpected results.


For example:

  1. Missing data (i.e. client network was down, Occuspace downtime, etc.).
  2. Request asks for data before location was activated.
  3. Portions of the location were closed and some were open.

Location List  

GET /locations

Flat list of user-accessible locations.

Parameters

No query parameters.

Attributes

Response is an array of location nodes. A location node has the following structure:

id

integer

ID of the location. Can be used on other endpoints for specific resources on the location in question.

name

string

Name of the location.

parentID

integer | null

ID of the parent location. Null if it is a customer’s root location.

capacity

integer

Capacity of the location. This is a sum of all child locations.

earliestCount

string | null

Date string to indicate the earliest accessible count. Null if no count has been recorded.

isActive

boolean

Boolean to indicate if location is currently returning valid data. If a node has children, it will return true as long as one of the children are active.

Example Request
$ curl "https://api.occuspace.io/v1/locations" \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{ 
  "message":"OK",
 
  "data": [
 
    {
 
      "id": 1,
 
      "name": "Sales",
 
      "parentID": null,
 
      "capacity": 1000,
 
      "earliestCount": "2020-01-15",
 
      "isActive": true
 
    },
 
    {
 
      "id": 2,
 
      "name": "Office Building",
 
      "parentID": 1,
 
      "capacity": 500,
 
      "earliestCount": "2020-01-15",
 
      "isActive": true
 
    }
 
    ...
 
  ]
 
}

Real-Time Data  

GET /locations/:id/now

Real-time occupancy estimation for the location.

Parameters

No query parameters.

Attributes

id

integer

ID of the location.

name

string

Name of the location.

count

integer

Most recent estimated count for requested location.

percentage

integer

(Count / Capacity) for location.

timestamp

string

UTC timestamp of the estimation.

isActive

boolean

Boolean to indicate if location is currently returning valid data. If a node has children, it will return true as long as one of the children are active.

childCounts

array | null

List of counts for child objects. Returns real-time count for all direct children of requested location. Null if leaf location.

Child Object

id

integer

ID of child location.

name

string

Name of child location.

count

integer

Most recent estimated count for child location.

percentage

integer

(Count / Capacity) for child location.

isActive

boolean

Boolean to indicate if location is currently returning valid data. If a node has children, it will return true as long as one of the children are active.

Example Request
$ curl "https://api.occuspace.io/v1/locations/2/now" \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{ 
  "message":"OK",
 
  "data": {
 
    "id": 2,
 
    "name": "Office Building",
 
    "count": 100,
 
    "percentage": 0.20,
 
    "timestamp": "2020-02-15T15:30:00.000Z",
 
    "isActive": true,
 
    "childCounts": [
 
      {
 
        "id": 3,
 
        "name": "Office 1st Floor",
 
        "count": 70,
 
        "percentage": 0.18,
 
        "isActive": true
 
      },
 
      {
 
        "id": 4,
 
        "name": "Office 2nd Floor",
 
        "count": 30,
 
        "percentage": 0.30,
 
        "isActive": true
 
      }
 
    ]
 
  }
 
}

Daily Occupancy  

GET /locations/:id/daily_occupancy

List of daily occupancy values with average and peak data points for a defined date range.

Parameters

start

string -

Date range start in YYYY-MM-DD format.

end

string -

Date range end in YYYY-MM-DD format.

Attributes

Response is an array of daily occupancy objects.

dailyOccupancy

array

List of dailyOccupancy objects.

Daily Occupancy Object

avgOccupancy

integer

The average number of people that were in the space over the day.

avgPercentageOccupied

float

The average percentage occupied the space was over the day, based on the defined capacity of the space.

peakOccupancy

integer

The peak number of people that were in the space over the day.

peakPercentageOccupied

float

The percentage occupied the space was at the peak level of occupancy over the day, based on the defined capacity of the space.

timestamp

string

UTC ISO timestamp of the estimation.

normalizedDate

string

YYYY-MM-DD formatted date, adjusted for timezone of the customer location.

Example Request
$ curl "https://api.occuspace.io/v1/locations/1560/daily_occupancy?start=2024-01-01&end=2024-01-02" \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{ 
  "message": "OK",
 
  "data": {
 
    "dailyOccupancy": [
 
      {
 
        "avgOccupancy": 19,
 
        "avgPercentageOccupied": 0.07,
 
        "peakOccupancy": 52,
 
        "peakPercentageOccupied": 0.18,
 
        "timestamp": "2024-01-01 00:00:00",
 
        "normalizedDate": "2024-01-01",
 
      },
 
      {
 
        "avgOccupancy": 36,
 
        "avgPercentageOccupied": 0.12,
 
        "peakOccupancy": 102,
 
        "peakPercentageOccupied": 0.35,
 
        "timestamp": "2024-01-02 00:00:00",
 
        "normalizedDate": "2024-01-02",
 
      }
 
    ]
 
  }
 
}

Hourly Occupancy  

GET /locations/:id/hourly_occupancy

List of hourly occupancy values for the hours of the day with average and peak data points for a defined date range.

Parameters

start

string -

Date range start in YYYY-MM-DD format.

end

string -

Date range end in YYYY-MM-DD format.

Attributes

Response is an array of hourly occupancy objects.

hourlyOccupancy

array

List of hourlyOccupancy objects.

Hourly Occupancy Object

avgOccupancy

integer

The average number of people that were in the space over the hour of the day across the date range defined.

avgPercentageOccupied

float

The average percentage occupied the space was over the hour of the day across the date range defined, and based on the defined capacity of the space.

peakOccupancy

integer

The peak number of people that were in the space over the hour of the day across the date range defined.

peakPercentageOccupied

float

The percentage occupied the space was at the peak level of occupancy over the hour of the day across the date range defined, and based on the defined capacity of the space.

normalizedTime

string

HH-MM-SS formatted timestamp representing the hour of the day for the prediction, adjusted for timezone of the customer location.

Example Request
$ curl "https://api.occuspace.io/v1/locations/1560/hourly_occupancy?start=2024-01-01&end=2024-01-02" \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{ 
  "message": "OK",
 
  "data": {
 
    "hourlyOccupancy": [
 
      {
 
        "avgOccupancy": 6,
 
        "avgPercentageOccupied": 0.02,
 
        "peakOccupancy": 10,
 
        "peakPercentageOccupied": 0.03,
 
        "normalizedTime": "00:00:00",
 
      },
 
      {
 
        "avgOccupancy": 6,
 
        "avgPercentageOccupied": 0.02,
 
        "peakOccupancy": 8,
 
        "peakPercentageOccupied": 0.03,
 
        "normalizedTime": "01:00:00",
 
      },
 
      ...
 
    ]
 
  }
 
}

Daily Traffic (Visitors)  

GET /locations/:id/daily_visitors

List of daily traffic (visitors) values for a defined date range.

Parameters

start

string -

Date range start in YYYY-MM-DD format.

end

string -

Date range end in YYYY-MM-DD format.

Attributes

Response is an array of daily traffic (visitors) objects.

dailyVisitors

array

List of dailyVisitors objects.

Daily Traffic (Visitors) Object

visitors

integer

The total number of people that visited the space over the day.

timestamp

string

UTC ISO timestamp of the estimation.

normalizedDate

string

YYYY-MM-DD formatted date representing the day of the prediction, adjusted for timezone of the customer location.

normalizedTime

string

HH-MM-SS formatted timestamp representing the hour of the day for the prediction, adjusted for timezone of the customer location.

Example Request
$ curl "https://api.occuspace.io/v1/locations/1560/daily_visitors?start=2024-01-01&end=2024-01-02" \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{ 
  "message": "OK",
 
  "data": {
 
    "dailyVisitors": [
 
      {
 
        "visitors": 61,
 
        "timestamp": "2024-01-01 00:00:00",
 
        "normalizedDate": "2024-01-01",
 
        "normalizedTime": "00:00:00",
 
      },
 
      {
 
        "visitors": 145,
 
        "timestamp": "2024-01-02 00:00:00",
 
        "normalizedDate": "2024-01-02",
 
        "normalizedTime": "00:00:00",
 
      }
 
    ]
 
  }
 
}

Hourly Traffic (Visitors)  

GET /locations/:id/hourly_visitors

List of hourly traffic (visitors) values for a defined date range.

Parameters

start

string -

Date range start in YYYY-MM-DD format.

end

string -

Date range end in YYYY-MM-DD format.

Attributes

Response is an array of hourly traffic (visitors) objects.

hourlyVisitors

array

List of hourlyVisitors objects.

Hourly Traffic (Visitors) Object

visitors

integer

The total number of people that visited the space over each hour of each day of the date range defined.

timestamp

string

UTC ISO timestamp of the estimation.

normalizedDate

string

YYYY-MM-DD formatted date representing the day of the prediction, adjusted for timezone of the customer location.

normalizedTime

string

HH-MM-SS formatted timestamp representing the hour of the day for the prediction, adjusted for timezone of the customer location.

Example Request
$ curl "https://api.occuspace.io/v1/locations/1560/hourly_visitors?start=2024-01-01&end=2024-01-02" \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{ 
  "message": "OK",
 
  "data": {
 
    "hourlyVisitors": [
 
      {
 
        "visitors": 0,
 
        "timestamp": "2024-01-01 00:00:00",
 
        "normalizedDate": "2024-01-01",
 
        "normalizedTime": "00:00:00",
 
      },
 
      {
 
        "visitors": 2,
 
        "timestamp": "2024-01-01 01:00:00",
 
        "normalizedDate": "2024-01-01",
 
        "normalizedTime": "01:00:00",
 
      },
 
      ...
 
    ]
 
  }
 
}

Daily Dwell Time  

GET /locations/:id/daily_dwell_time

List of daily dwell time values with average and peak data points for a defined date range.

Parameters

start

string -

Date range start in YYYY-MM-DD format.

end

string -

Date range end in YYYY-MM-DD format.

Attributes

Response is an array of daily dwell time objects.

dailyDwellTimes

array

List of dailyDwellTimes objects.

Daily Dwell Time Object

avgDwellTime

integer

The average dwell time (in miuntes) of people that were in the space over the day.

peakDwellTime

integer

The peak dwell time (in minutes) of people that were in the space over the day.

timestamp

string

UTC ISO timestamp of the estimation.

normalizedDate

string

YYYY-MM-DD formatted date, adjusted for timezone of the customer location.

normalizedTime

string

HH-MM-SS formatted timestamp representing the hour of the day for the prediction, adjusted for timezone of the customer location.

Example Request
$ curl "https://api.occuspace.io/v1/locations/1560/daily_dwell_time?start=2024-01-01&end=2024-01-02" \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{ 
  "message": "OK",
 
  "data": {
 
    "dailyDwellTimes": [
 
      {
 
        "avgDwellTime": 241,
 
        "peakDwellTime": 312,
 
        "timestamp": "2024-01-01 00:00:00",
 
        "normalizedDate": "2024-01-01",
 
        "normalizedTime": "00:00:00",
 
      },
 
      {
 
        "avgDwellTime": 211,
 
        "peakDwellTime": 301,
 
        "timestamp": "2024-01-02 00:00:00",
 
        "normalizedDate": "2024-01-02",
 
        "normalizedTime": "00:00:00",
 
      }
 
    ]
 
  }
 
}