Overview

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

It's RESTful interface returns JSON data for all endpoints. These endpoints provide information on the installed locations and occupancy data - both realtime and historical count estimations - in these locations.

All requests are authenticated using Authorization Bearer tokens - the token will be provided to you 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 will be cycled upon user request.

HTTP Authorization Header

Authorization: Bearer {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.

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

Endpoints

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 message will be "OK".

In the event that a successful response that may have a slight discrepencancy from the user's request, the message field will try and explain any unexpected results.

For example:
  1. Missing data (ie: 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

GET /locations

Flat list of user-accessible locations
No URL / Query parameters

GET /locations Response

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 root.
capacity {integer}: Capacity of the location. This is a sum of all child locations.

GET /location/:id/now

Realtime occupancy estimation for the location.

GET /location/:id/now Response

count {integer}: Most recent estimated count
percentage {integer}: Rounded count * 100 / capacity of the location
timestamp {string}: UTC timestamp of the estimation

GET /location/:id/counts

List of counts along with aggregated summary data within a start/end datetime range.

GET /location/:id/counts Query Parameters

start {string}: UTC ISO timestamp of start date and time
end {string}: UTC ISO timestamp of end date and time


GET /location/:id/counts Response

Array of count objects, along with summary data of the occupancy data over the time range. In order from start -> end time.

counts {array}: List of count objects
average {number}: 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 format
count {integer}: Estimated count at a time within the range
percentage {integer}: count * 100 / capacity
timestamp {string}: UTC ISO timestamp of the time the estimation was made
normalizedDate {string}: YYYY-MM-DD formatted date, adjusted for the timezone of the location
normalizedTime {string}: 24 hour HH:mmr formatted time, adjusted for the timezone of the location