Notice: Density API v1 has been deprecated. Density API v2 documentation can be found here.
The Density API provides access to real-time and historical foot traffic data for your Density-enabled spaces.
The Density API is built upon REST, returns JSON responses, and supports cross-origin resource sharing. Standard HTTP verbs are used to perform CRUD operations, and the API returns standard HTTP response codes to indicate errors. API versioning is implemented via namespaces. Token authentication is used to authenticate every API request.
https://api.density.io/v1
All API endpoints are authenticated using your API token, found in the dashboard.
Your token must be included in the Authorization HTTP header, prefixed by the string literal "Bearer" with a single space separating the two strings. Any API call made without the proper Authorization header will return a 403 error.
Authorization: Bearer YOUR_API_TOKEN
Density endpoints use standard HTTP error codes. The response includes any additional information about the error.
The request sent to the API is invalid. Additional information will be returned in the response body.
The client is not allowed to perform this request. Can be caused by a missing or invalid API token.
The requested resource does not exist.
The request conflicts with another request.
All timestamps sent to the API must be formatted as strings according to the ISO 8601 standard for UTC timestamps. The API will return all timestamps in the same UTC format.
Most programming platforms have built-in utilities to convert between local time and UTC.
2016-05-23T10:00:00.000Z
Density endpoints that return multiple results will be paginated to 200 items by default.
For these endpoints the root of the response object will contain the total count of results, the next and previous page URLs, and an array with the current page of results. If all results fit onto a single page, the next and previous page URLs will be null.
If included, the endpoint will return a particular page of data.
If included, the endpoint will return pages of this size. The maximum page size is 1000.
$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/spaces/?page=4&page_size=15
{
"count": 89,
"next": "https://api.density.io/v1/spaces/?page=5&page_size=15",
"previous": "https://api.density.io/v1/spaces/?page=3&page_size=15",
"results": [
…
]
}
The Density API provides real-time and historical traffic data. To query this data only a few endpoints are used.
Density uses the term space for a region where entrances and exits are being counted. Every space created in the Density Dashboard is assigned a unique ID, which you can use to query information for a single space. The current count of people in the space(s) will be included.
List all spaces. Each object returned includes the current count for the space. Note that doorways and daily reset times must be queried for each individual space.
GET /spaces/If included, return only spaces associated with this doorway.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/spaces/
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "spc_452554024357462439",
"name": "Office",
"timezone": "America/New_York",
"current_count": 5,
"tags": [
"tech_garden"
]
},
{
"id": "spc_439805443284402880",
"name": "Conference Room",
"timezone": "America/New_York",
"current_count": 2,
"tags": [
"tech_garden"
]
}
]
}
Get detailed information about a space. Includes the current count, the daily reset time, and the list of doorways linked to this space.
GET /spaces/:space_id/curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/spaces/spc_452554024357462439/
{
"id": "spc_452554024357462439",
"name": "Office",
"description": "The whole Office",
"timezone": "America/New_York",
"daily_reset": "13:00",
"current_count": 5,
"doorways": [
{
"doorway_id": "drw_452554070478029236",
"name": "Office Door",
"sensor_placement": 1
}
],
"tags": [
"tech_garden"
]
}
Query the real-time or historical count for a space.
GET /spaces/:space_id/count/If included, the endpoint will return the historical count at this time. Must be formatted as an ISO 8601 UTC timestamp.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/spaces/spc_452554024357462439/count/\
?time=2016-05-23T10:10:00.000Z
{
"count": 5
}
For more granular foot traffic data, use the /events/ endpoint to query traffic events within a given time period.
List foot traffic events for a time period. Each event object specifies a timestamp and direction, along with the count change and new count for any affected spaces.
GET /events/The start time for the historical traffic. Must be formatted as an ISO 8601 UTC timestamp.
The end time for the historical traffic. Must be formatted as an ISO 8601 UTC timestamp.
If present, only query traffic into or out of this space.
If present, only query traffic through this doorway.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/events/?start_time=2016-09-19&end_time=2016-09-20
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "evt_456547729913414419",
"sensor_id": "snr_457234837531526031",
"doorway_id": "drw_452554070478029236",
"timestamp": "2016-09-19T15:32:19.409Z",
"direction": -1,
"spaces": [
{
"space_id": "spc_452554024357462439",
"count_change": -1,
"count": 5
}
]
},
{
"id": "evt_456547726805435148",
"sensor_id": "snr_457234837531526031",
"doorway_id": "drw_452554070478029236",
"timestamp": "2016-09-19T15:32:10.148Z",
"direction": 1,
"spaces": [
{
"space_id": "spc_452554024357462439",
"count_change": 1,
"count": 6
}
]
}
]
}
Simulate a traffic event. Real sensors will automatically create their own events.
POST /events/The id of the sensor that registered the event.
The direction of the traffic event. If the sensor is mounted on the inside of your space, a direction of 1 means an entry and -1 means an exit.
The time the event was detected. Must be formatted as an ISO 8601 UTC timestamp.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"sensor_id": "snr_457234837531526031",
"timestamp": "2016-09-19T15:35:00Z",
"direction": 1
}' \
https://api.density.io/v1/events/
{
"id": "evt_456547715858301685",
"sensor_id": "snr_457234837531526031",
"doorway_id": "drw_452554070478029236",
"timestamp": "2016-09-19T15:35:00",
"direction": 1,
"spaces": [
{
"space_id": "spc_452554024357462439",
"count_change": 1,
"count": 6
}
]
}
To reset the current count for a space, or to view historical resets, use the /resets/ endpoint. In production, you can configure the daily_reset property on a space to automatically reset its count every day.
List resets for a time period. Each reset contains a timestamp, and the new count for the affected space.
GET /resets/The earliest timestamp to include. Should be formatted as an ISO 8601 UTC timestamp.
The latest timestamp to include. Should be formatted as an ISO 8601 UTC timestamp.
If present, only return resets for this space.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/resets/?start_time=2016-09-19&end_time=2016-09-20
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "rst_14907317516385010788",
"space_id": "spc_452554024357462439",
"timestamp": "2016-09-19T08:00:00",
"count": 0
}
]
}
Reset the count for a space. The count parameter can be used to reset the count to a number other than 0.
POST /resets/The id of the space that should have its count reset.
Reset the count to this value.
The time of the reset. Should be formatted as an ISO 8601 UTC timestamp.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"space_id": "spc_452554024357462439",
"timestamp": "2016-09-19T15:45:00.000Z",
"count": 7
}' \
https://api.density.io/v1/resets/
{
"id": "rst_456547733038170906",
"space_id": "spc_452554024357462439",
"timestamp": "2016-09-19T15:45:00",
"count": 7
}
The Density API can also be used to create and link spaces and doorways. Most integrations will not need to use these endpoints - spaces, doorways, and tags can be managed in the Density Dashboard (coming soon).
A space can be located within, adjacent to, or overlapping another space. For example, the interior of a conference room can be a space. The interior of the entire building can be a space as well. As long as you can put a name to an indoor region with foot traffic, it can be a space.
Spaces can be organized with tags (see below).
Add a space to your environment.
POST /spaces/The name of the space.
A description of the space.
The timezone of the space.
A 24-hour time in the local time zone. If present, the space's count will automatically reset to 0 at this time every day.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"name": "Kitchen",
"description": "Office Kitchen",
"daily_reset": "14:00"
}' \
https://api.density.io/v1/spaces/
{
"id": "spc_458687913710846960",
"name": "Kitchen",
"description": "Office Kitchen",
"timezone": "America/New_York",
"daily_reset": "14:00",
"current_count": 0,
"doorways": [],
"tags": []
}
Update a space.
PUT /spaces/:space_id/The name of the space.
A description of the space.
The timezone of the space. Should be formatted as an ISO 8601 UTC timestamp.
A 24-hour time in the local time zone. If present, the space's count will automatically reset to 0 at this time every day.
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"name": "Kitchen (Updated)",
"daily_reset": "13:00"
}' \
https://api.density.io/v1\
/spaces/spc_458687913710846960/
{
"id": "spc_458687913710846960",
"name": "Kitchen (Updated)",
"description": "Office Kitchen",
"timezone": "America/New_York",
"daily_reset": "13:00",
"current_count": 0,
"doorways": [],
"tags": []
}
Delete a space from your environment.
Warning: Deleting a space will destroy all historical counts for that space.
DELETE /spaces/:space_id/The current name of the space. Must be an exact match.
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"name": "Kitchen (Updated)"
}' \
https://api.density.io/v1\
/spaces/spc_458687913710846960/
Tag a space.
POST /spaces/:space_id/tags/The tag name. Alphanumeric characters, underscore or minus sign only.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"tag_name": "tech_garden"
}' \
https://api.density.io/v1/spaces/spc_458687913710846960/tags/
{
"tag_name": "tech_garden"
}
Untag a space.
DELETE /spaces/:space_id/tags/:tag_name/curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/spaces/spc_458687913710846960/tags/tech_garden/
Each space has one or more doorways associated with it. Each doorway is an entrance or exit where a Density sensor can be mounted to detect traffic events. A doorway can be associated with more than one space, if an interior doorway separates two spaces or if two spaces overlap.
Active doorways must have a sensor attached - this is done by setting the sensor_id value on the doorway. Every active doorway has exactly one sensor attached to it.
Doorways can be organized with tags (see below).
List all doorways for an account. Note that space associations must be queried for each individual doorway.
GET /doorways/If included, return only doorways associated with this space.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/doorways/
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "drw_437303389773103967",
"sensor_id": "snr_458467949888405826",
"name": "Conference Room Door",
"tags": [
"tech_garden"
]
},
{
"id": "drw_452554070478029236",
"sensor_id": "snr_457234837531526031",
"name": "Office Door",
"tags": [
"tech_garden"
]
}
]
}
Add a new doorway to your environment.
POST /doorways/A unique name for the doorway.
A description for the doorway.
The id of the sensor attached to this doorway, if any.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"name": "Kitchen Door",
"description": "The doorway to the Kitchen"
}' \
https://api.density.io/v1/doorways/
{
"id": "drw_456547716936237815",
"sensor_id": null,
"name": "Kitchen Door",
"description": "The doorway to the Kitchen",
"spaces": [],
"tags": []
}
Detailed information about a doorway. The spaces array is a summary of the spaces associated with this doorway. Each association in this array also has a sensor_placement used to configure complex environments. The sensor_placement will be 1 if the sensor is mounted on the inside of the space, and -1 if it is mounted on the outside. Note that a sensor should never be mounted outdoors.
GET /doorways/:doorway_id/curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/doorways/drw_437303389773103967/
{
"id": "drw_437303389773103967",
"sensor_id": "snr_458467949888405826",
"name": "Conference Room Door",
"description": "The doorway to the Conference Room (inside the Office)",
"spaces": [
{
"space_id": "spc_439805443284402880",
"name": "Conference Room",
"sensor_placement": 1
}
],
"tags": [
"tech_garden"
]
}
Update a doorway.
PUT /doorways/:doorway_id/A unique name for the doorway.
A description for the doorway.
The id of the sensor attached to this doorway, if any.
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"name": "Conference Room Door (Updated)"
}' \
https://api.density.io/v1\
/doorways/drw_437303389773103967/
{
"id": "drw_437303389773103967",
"sensor_id": "snr_458467949888405826",
"name": "Conference Room Door (Updated)",
"description": "The doorway to the Conference Room (inside the Office)",
"spaces": [
{
"space_id": "spc_439805443284402880",
"name": "Conference Room",
"sensor_placement": 1
}
],
"tags": [
"tech_garden"
]
}
Delete a doorway from your environment.
DELETE /doorways/:doorway_id/curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/doorways/drw_437303389773103967/
Tag a doorway.
POST /doorways/:doorway_id/tags/The tag name. Alphanumeric characters, underscore or minus sign only.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"tag_name": "tech_garden"
}' \
https://api.density.io/v1\
/doorways/drw_456547716936237815/tags/
{
"tag_name": "tech_garden"
}
Untag a doorway.
DELETE /doorways/:doorway_id/tags/:tag_name/curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/doorways/drw_456547716936237815/tags/tech_garden/
Before a space can be updated by real-time events, it must be associated with at least one doorway. A Density link is one association between a space and a doorway. A space can be linked to more than one doorway, and a doorway can be linked to more than one space. Each link has a sensor_placement value, set to 1 (if the sensor is mounted inside this space) or -1 (if the sensor is mounted outside this space).
Links cannot be updated. To reconfigure spaces and doorways, first delete the old links, then create new links with the updated configuration.
Index of all links between spaces and doorways in your environment.
GET /links/If present, only show links to this space.
If present, only show links to this doorway.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/links/
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "lnk_444756070888374551",
"space_id": "spc_439805443284402880",
"doorway_id": "drw_437303389773103967",
"space_name": "Conference Room",
"doorway_name": "Conference Room Door",
"sensor_placement": 1
},
{
"id": "lnk_444753388672909561",
"space_id": "spc_452554024357462439",
"doorway_id": "drw_452554070478029236",
"space_name": "Office",
"doorway_name": "Office Door",
"sensor_placement": 1
}
]
}
Link a space to a doorway.
POST /links/The id of the space.
The id of the doorway.
Must be 1 if the sensor is mounted inside this space, or -1 if the sensor is mounted outside this space.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"space_id": "spc_458687913710846960",
"doorway_id": "drw_456547716936237815",
"sensor_placement": 1
}' \
https://api.density.io/v1/links/
{
"id": "lnk_444756070888374551",
"space_id": "spc_458687913710846960",
"doorway_id": "drw_456547716936237815",
"space_name": "Kitchen (Updated)",
"doorway_name": "Kitchen Door",
"sensor_placement": 1
}
Un-link a doorway from a space. Note that a space must be linked to at least one doorway in order to be updated by real-time events.
DELETE /links/:link_id/curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/links/lnk_444756070888374551/
A tag is a text slug (alphanumeric, dash, or underscore only) that can be added to any space or doorway. Tags provide an easy mechanism for filtering and organizing spaces and doorways.
To tag or untag a space or doorway, use the endpoints in the space and doorway sections above.
Index of all tags for an account.
GET /tags/$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/tags/
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"name": "tech_garden"
}
]
}
List all spaces and doorways for a single tag. Note that additional details must be queried for each individual item.
GET /tags/:tag_name/$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/tags/tech_garden/
{
"name": "tech_garden",
"spaces": [
{
"space_id": "spc_439805443284402880",
"name": "Conference Room",
"current_count": 3
},
{
"space_id": "spc_452554024357462439",
"name": "Office",
"current_count": 7
},
{
"space_id": "spc_458687913710846960",
"name": "Kitchen (Updated)",
"current_count": 1
}
],
"doorways": [
{
"doorway_id": "drw_437303389773103967",
"name": "Conference Room Door (Updated)"
},
{
"doorway_id": "drw_452554070478029236",
"name": "Office Door"
},
{
"doorway_id": "drw_456547716936237815",
"name": "Kitchen Door"
}
]
}
A Density sensor is the physical hardware module that is mounted above a doorway. Each active doorway must have a sensor associated with it. Density sensors will be automatically updated with their current status.
List sensors in your environment.
GET /sensors/curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/sensors/
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "snr_458467949888405826",
"doorway_id": "drw_437303389773103967",
"sensor_type": "s5",
"status": "online"
},
{
"id": "snr_457234837531526031",
"doorway_id": "drw_452554070478029236",
"sensor_type": "s5",
"status": "online"
}
]
}
View the current status of a sensor.
GET /sensors/:sensor_id/curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/sensors/snr_444718732388860910/
{
"id": "snr_444718732388860910",
"doorway_id": "drw_456547716936237815",
"sensor_type": "s5",
"status": "online"
}
A webhook subscription allows you to receive a callback to a specified endpoint on your own server. Density webhooks will be triggered after every event we receive from one of your sensors.
List webhooks in your environment.
GET /webhooks/curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1/webhooks/
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "whk_444755132324774161",
"endpoint": "https://your-website.com/some-action"
}
]
}
Add a new webhook to your environment.
POST /webhooks/The URL to which Density will send event data.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"endpoint": "https://your-website.com/some-action"
}' \
https://api.density.io/v1/webhooks/
{
"id": "whk_444755132324774161",
"endpoint": "https://your-website.com/some-action"
}
Detailed information about a webhook.
GET /webhooks/:webhook_id/curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/webhooks/whk_444755132324774161/
{
"id": "whk_444755132324774161",
"endpoint": "https://your-website.com/some-action"
}
Update a webhook.
PUT /webhooks/:webhook_id/A new URL for the endpoint.
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"endpoint": "https://some-website.com/other-endpoint"
}' \
https://api.density.io/v1\
/webhooks/whk_444755132324774161/
{
"id": "whk_444755132324774161",
"endpoint": "https://some-website.com/other-endpoint"
}
Delete a webhook from your environment.
DELETE /webhooks/:webhook_id/curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v1\
/webhooks/whk_444755132324774161/
When you receive a webhook, the JSON data will resemble that of an event. See the events section for more information on the direction field.
N/A{
"space_id": "spc_14459326507202298682",
"doorway_id": "drw_437303389773103967",
"direction": 1,
"count": 32
}