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:
- Authorization header is missing from request
- No token provided in header
- Invalid token is used
- 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:
- Missing data (i.e. client network was down, Occuspace downtime, etc.).
- Request asks for data before location was activated.
- 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
integerID of the location. Can be used on other endpoints for specific resources on the location in question.
name
stringName of the location.
parentID
integer | nullID of the parent location. Null if it is a customer’s root location.
capacity
integerCapacity of the location. This is a sum of all child locations.
earliestCount
string | nullDate string to indicate the earliest accessible count. Null if no count has been recorded.
isActive
booleanBoolean 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
integerID of the location.
name
stringName of the location.
count
integerMost recent estimated count for requested location.
percentage
integer(Count / Capacity) for location.
timestamp
stringUTC timestamp of the estimation.
isActive
booleanBoolean 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 | nullList of counts for child objects. Returns real-time count for all direct children of requested location. Null if leaf location.
Child Object
id
integerID of child location.
name
stringName of child location.
count
integerMost recent estimated count for child location.
percentage
integer(Count / Capacity) for child location.
isActive
booleanBoolean 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
}
]
}
}
Historical Data
GET /locations/:id/counts
List of counts along with aggregated summary data for a date range.
Parameters
start
string -Localized date time string of the estimation. If location spans timezones, locations are aggregated relative to their local time and timestamp is agnostic of timezone (9:00am Pacific is aggregated with 9:00am Eastern).
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
arrayList of count objects.
average
integerThe average count value over the period.
maximum
objectCount object of the highest count over the period.
minimum
objectCount object of the lowest count over the period.
Count Object
count
integerEstimated count at a timestamp within requested range.
percentage
integerCount / Capacity of a location.
timestamp
stringUTC ISO timestamp of the estimation.
normalizedDate
stringYYYY-MM-DD formatted date, adjusted for timezone of customer location.
normalizedTime
string24 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"
}
}
}