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 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 exists. 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

Date string to indicate the earliest accessible count.

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

Real-Time Data  

GET /locations/:id/now

Real-time occupancy estimation for the location.

Parameters

No query parameters.

Attributes

name

string

Name of the location.

id

integer

ID 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

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.

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

Historical Data  

GET /locations/:id/counts

List of counts along with aggregated summary data for a date range.

Parameters

start

string -

UTC ISO timestamp of start date.

end

string -

UTC ISO timestamp of end date.

Attributes

Response is an array of count objects, along with summary data of the occupancy data over the time range.

counts

array

List of count objects.

average

integer

The average count value over the period.

maximum

object

Count object of the highest count over the period.

minimum

object

Count object of the lowest count over the period.

Count Object

count

integer

Estimated count at a timestamp within requested range.

percentage

integer

Count / Capacity of a location.

timestamp

string

UTC ISO timestamp of the estimation.

normalizedDate

string

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

normalizedTime

string

24 hour HH:mm formatted time, adjusted for timezone of customer location.

Example Request
$ curl https://api.occuspace.io/v1/locations/2/counts?start=2020-03-01&end=2020-03-02 \ -H “Authorization: Bearer YOUR_API_TOKEN”
Example Response
{
  "message":"OK",
  "data": {
    "counts": [
      {
        "percentage": 0.25,
        "count": 50,
        "timestamp": "2020-03-01 17:00:00",
        "normalizedDate": "2020-03-01",
        "normalizedTime": "09:00:00"
      },
      ...
    ],
    "average": 120,
    "maxiumum": {
      "percentage": 0.90,
      "count": 180,
      "timestamp": "2020-03-01 21:00:00",
      "normalizedDate": "2020-03-01",
      "normalizedTime": "13:00:00"
    },
    "minumum": {
      "percentage": 0.05,
      "count": 10,
      "timestamp": "2020-03-02 07:00:00",
      "normalizedDate": "2020-03-01",
      "normalizedTime": "23:00:00"
    }
  }
}