API Docs

Density API

The Density API hosts real-time and historical people count 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.

Base URL

https://api.density.io/v2

Authentication

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.

HTTP Authorization Header

Authorization: Bearer YOUR_API_TOKEN

Errors

Density endpoints use standard HTTP error codes. The response includes any additional information about the error.

Error Codes

400 Bad Request

The request sent to the API is invalid. Additional information will be returned in the response body.

403 Forbidden

The client is not allowed to perform this request. Can be caused by a missing or invalid API token.

404 Not Found

The requested resource does not exist.

409 Conflict

The request conflicts with another request.

Timestamps

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.

ISO 8601 UTC Timestamp

2016-05-23T10:00:00.000Z

Pagination

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

Query String Parameters

page
integer
default: 1

If included, the endpoint will return a particular page of data.

page_size
integer
default: 200

If included, the endpoint will return pages of this size. The maximum page size is 1000.

Example Request

$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.density.io/v2/spaces/?page=4&page_size=15

Paginated Response

{
  "total": 89,
  "next": "https://api.density.io/v2/spaces/?page=5&page_size=15",
  "previous": "https://api.density.io/v2/spaces/?page=3&page_size=15",
  "results": [
    …
  ]
}

CSV Export

The Density API can return data in CSV format for convenience. To request CSV, set the Accept header to the value text/csv.

In CSV format, nested fields will be flattened, with the nested field names in order separated by a dot character (.).

CSV responses are not paged, all results will be returned. Large responses may take longer to prepare, and no more than 31 days of traffic data can be queried at a time.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: text/csv" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/events/\
?start_time=2017-09-19T08:00:00.000Z\
&end_time=2017-09-20T08:00:00.000Z

CSV Response

direction,doorway_id,id,sensor_serial_number,timestamp
1,drw_452554070478029236,evt_463842287353331919,Z444944692392493397,2017-09-19T12:23:45.405Z
-1,drw_452554070478029236,evt_463533857086374803,Z444944692392493397,2017-09-19T12:38:03.575Z
...

Counts and Events

The Density API provides real-time and historical people count for logical spaces. A "space" can be a room, a floor, a building, or a campus. Each space has a unique id for querying its data.

People count is represented by two concepts: counts and events. A "count" is the number of people in a space at a particular time. An "event" is an entrance or exit to or from a space at a particular time.

Space "counts" are sampled at regular intervals, and analytics for each interval are included in the API response. See Space Counts for details.

List Spaces

Each space includes a list of doorways linked to the space, the current_count of people in the space, the total capacity of the space, a daily_reset time, the space type (see list in Spaces section), and an optional parent space's ID. There are also optional address fields to be used to locate campuses and buildings.

There is validation on space types and parent associations. For example, you can have a floor that has a building as parent, but not the other way around.

To query foot traffic data for a space, use an id returned by this endpoint with the other two endpoints in this section. To manage the spaces and doorways in your environment with the Density API, see these sections: Spaces, Doorways, and Links.

GET /spaces/

Query String Parameters

doorway_id

If included, return only spaces associated with this doorway.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2/spaces/

Example Response

{
  "total": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "spc_452554024357462439",
      "name": "Office",
      "description": "The Office",
      "parent_id": null,
      "space_type": "space",
      "timezone": "America/New_York",
      "daily_reset": "05:00",
      "current_count": 5,
      "doorways": [
        {
          "id": "drw_452554070478029236",
          "name": "Office Door",
          "sensor_placement": 1
        }
      ],
      "tags": [
        "tech_garden"
      ]
    },
    {
      "id": "spc_439805443284402880",
      "name": "Conference Room",
      "description": "The Conference Room",
      "parent_id": null,
      "space_type": "space",
      "timezone": "America/New_York",
      "daily_reset": "05:00",
      "current_count": 2,
      "doorways": [
        {
          "id": "drw_437303389773103967",
          "name": "Conference Room Door",
          "sensor_placement": 1
        }
      ],
      "tags": [
        "tech_garden"
      ]
    }
  ]
}

Space Counts

List counts for a space over a period of time, sampled at regular intervals. Each sample contains a timestamp and the count at that time. Each sample also includes an interval object with start and end times, and a nested analytics object containing the min count, max count, total events, total entrances, and total exits for the interval.

GET /spaces/:space_id/counts/

Query String Parameters

* start_time
required | string

Sample counts starting at this timestamp. Must be formatted as an ISO 8601 UTC timestamp.

end_time
string
default: now

Sample counts until just before this timestamp. Must be formatted as an ISO 8601 UTC timestamp.

interval
interval
default: 1h

If present, sample counts at this interval. Must be an integer followed by s (seconds), m (minutes), h (hours), d (days), or w (weeks)

order
ASC or DESC
default: ASC

Order the count samples in ascending or descending chronological order.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/counts/\
?start_time=2017-09-19T15:00:00Z\
&end_time=2017-09-19T17:00:00Z

Example Response

{
  "total": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "timestamp": "2017-09-19T15:00:00.000Z",
      "count": 10,
      "interval": {
        "start": "2017-09-19T15:00:00.000Z",
        "end": "2017-09-19T15:59:59.999Z",
        "analytics": {
          "min": 9,
          "max": 32,
          "events": 130,
          "entrances": 72,
          "exits": 58
        }
      }
    },
    {
      "timestamp": "2017-09-19T16:00:00.000Z",
      "count": 24,
      "interval": {
        "start": "2017-09-19T16:00:00.000Z",
        "end": "2017-09-19T16:59:59.999Z",
        "analytics": {
          "min": 21,
          "max": 38,
          "events": 95,
          "entrances": 62,
          "exits": 33
        }
      }
    }
  ]
}

Space Events

List individual entrances and exits into or out of a space over a period of time. Each event contains a timestamp and direction (1 for entrance, -1 for exit).

GET /spaces/:space_id/events/

Query String Parameters

* start_time
required | string

Query traffic starting at this time. Must be formatted as an ISO 8601 UTC timestamp.

end_time
string
default: now

Query traffic until this time. Must be formatted as an ISO 8601 UTC timestamp.

doorway_id
string

Query only traffic through this doorway.

direction
1 or -1

Query only traffic matching this direction.

order
ASC or DESC
default: ASC

Order the traffic events in ascending or descending chronological order.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/events/\
?start_time=2017-09-19T15:00:00Z\
&end_time=2017-09-19T17:00:00Z

Example Response

{
  "total": 138,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "evt_459087893936210613",
      "sensor_serial_number": "Z457234837531526031",
      "doorway_id": "drw_452554070478029236",
      "timestamp": "2016-09-19T15:32:10.409Z",
      "direction": -1
    },
    {
      "id": "evt_459087875221226161",
      "sensor_serial_number": "Z457234837531526031",
      "doorway_id": "drw_452554070478029236",
      "timestamp": "2016-09-19T15:32:19.148Z",
      "direction": 1
    },
    ...
  ]
}

Use Cases

This section describes common use cases and the API calls used to query the appropriate data.

Count Samples

Sample the count every five minutes for 24 hours. The count field in each result is the number of people who were in the space at the corresponding timestamp.

Use this call to find out how your space is used throughout one day.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/counts/\
?start_time=2017-09-19T08:00:00Z\
&end_time=2017-09-20T08:00:00Z\
&interval=5m\
&page_size=288

Example Response

{
  "total": 288,
  "next": null,
  "previous": null,
  "results": [
    {
      "timestamp": "2017-09-19T08:00:00.000Z",
      "count": 0,
      "interval": {
        "start": "2017-09-19T08:00:00.000Z",
        "end": "2017-09-19T08:04:59.999Z",
        "analytics": {
          "min": 0,
          "max": 2,
          "events": 4,
          "entrances": 3,
          "exits": 1
        }
      }
    },
    ...
  ]
}

Total Entrances

Get the total number of entrances into a space every day for one week. Each result's interval object has a nested analytics object with data for that interval, including the total number of entrances.

Use this call to find out how many people are visiting your space on different days of the week.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/counts/\
?start_time=2017-09-17T08:00:00Z\
&end_time=2017-09-24T08:00:00Z\
&interval=1d\
&page_size=7

Example Response

{
  "total": 7,
  "next": null,
  "previous": null,
  "results": [
    {
      "timestamp": "2017-09-17T08:00:00.000Z",
      "count": 0,
      "interval": {
        "start": "2017-09-17T08:00:00.000Z",
        "end": "2017-09-18T07:59:59.999Z",
        "analytics": {
          "min": 0,
          "max": 43,
          "events": 468,
          "entrances": 234,
          "exits": 234
        }
      }
    },
    ...
  ]
}

Individual Exits

List individual exits from a space over a 24-hour period. Each result has a timestamp and a direction (which in this example will always be -1).

Use this call to find out exactly when people are leaving your space.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/events/\
?start_time=2017-09-19T08:00:00Z\
&end_time=2017-09-20T08:00:00Z\
&direction=-1\
&page_size=1000

Example Response

{
  "total": 234,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "evt_459087848717419179",
      "sensor_serial_number": "Z457234837531526031",
      "doorway_id": "drw_452554070478029236",
      "timestamp": "2016-09-19T08:03:19.148Z",
      "direction": -1
    },
    ...
  ]
}

Sensor Events

The Density API also provides a low-level stream of "sensor events". These events are not necessarily one-to-one with traffic events at any space, because sensors can be mounted on either side of a doorway.

This endpoint should only be used for testing configured sensors and environments.

List Sensor Events

List low-level "sensor events" for a sensor and a period of time. Each sensor event contains a timestamp and a trajectory relative to the sensor. The trajectory is not necessarily equal to any direction relative to a space (i.e. an entrance or exit).

This call should only be used for testing sensor performance.

GET /sensors/:serial_number/events/

Query String Parameters

* start_time
required | string

The earliest timestamp to include. Should be formatted as an ISO 8601 UTC timestamp.

end_time
string
default: now

The latest timestamp to include. Should be formatted as an ISO 8601 UTC timestamp.

trajectory
1 or -1

Query only sensor events matching this trajectory (relative to the sensor). If the sensor is mounted on the inside of your space, 1 means an entry and -1 means an exit.

order
ASC or DESC
default: ASC

Order the sensor events in ascending or descending chronological order.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/sensors/Z444944692392493397/events/\
?start_time=2017-09-19T15:00:00Z
&end_time=2017-09-19T15:01:00Z

Example Response

{
  "total": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "evt_459087875221226161",
      "doorway_id": "drw_452554070478029236",
      "sensor_serial_number": "Z444944692392493397",
      "timestamp": "2017-09-19T15:00:10.436Z",
      "trajectory": 1
    },
    {
      "id": "evt_459087822347829922",
      "doorway_id": "drw_452554070478029236",
      "sensor_serial_number": "Z444944692392493397",
      "timestamp": "2017-09-19T15:00:19.003Z",
      "trajectory": -1
    }
  ]
}

Simulate Event

Simulate a low-level sensor event. Real sensors will automatically create their own events.

This call should only be used for testing sensor and doorway placement.

POST /sensors/:serial_number/events/

Request Body

* trajectory
required | 1 or -1

The trajectory of the traffic event, relative to the sensor. If the sensor is mounted on the inside of your space, 1 means an entry and -1 means an exit.

timestamp
string
default: now

The time the event was detected. Must be formatted as an ISO 8601 UTC timestamp.

Example Request

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "timestamp": "2016-09-19T15:45:00.000Z",
    "trajectory": 1
}' \
https://api.density.io/v2\
/sensors/Z444944692392493397/events/

Example Response

{
    "id": "evt_459087817750872736",
    "doorway_id": "drw_452554070478029236",
    "sensor_serial_number": "Z444944692392493397",
    "timestamp": "2016-09-19T15:45:00.000Z",
    "trajectory": 1
}

Resets

To reset the current count or to view historical resets at a space, use the /spaces/:space_id/resets/ endpoint. In production, you can configure the daily_reset property on a space to automatically reset its count at that (UTC) time every day.

List Resets

List resets for a space and a period of time. Each reset contains a timestamp and the new count.

GET /spaces/:space_id/resets/

Query String Parameters

* start_time
required | string

The earliest timestamp to include. Should be formatted as an ISO 8601 UTC timestamp.

end_time
string
default: now

The latest timestamp to include. Should be formatted as an ISO 8601 UTC timestamp.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/resets/\
?start_time=2017-09-19&end_time=2017-09-20

Example Response

{
  "total": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "rst_458961873618862211",
      "space_id": "spc_452554024357462439",
      "timestamp": "2016-09-19T08:00:00",
      "count": 0
    }
  ]
}

Reset Count

Reset the count for a space. The count parameter can be used to reset the count to a number other than 0.

POST /spaces/:space_id/resets/

Request Body

count
integer
default: 0

Reset the count to this value.

timestamp
string
default: now

The time of the reset. Should be formatted as an ISO 8601 UTC timestamp.

Example Request

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "timestamp": "2016-09-19T15:45:00.000Z",
    "count": 7
}' \
https://api.density.io/v2\
/spaces/spc_452554024357462439/resets/

Example Response

{
  "id": "rst_458961873618862211",
  "space_id": "spc_452554024357462439",
  "timestamp": "2016-09-19T15:45:00",
  "count": 7
}

Spaces

The Density API can also be used to create and link spaces and doorways. Most integrations will not need to use these endpoints, as interactive tools to do so will be provided.

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.

Possible values for space_type:

  • space (default)
  • floor
  • building
  • campus

A space hierarchy is created by the (optional) parent field. These connections are validated so that campuses contain buildings, floors are within buildings, and so on.

Spaces can be further organized with tags.

Get Space

Get detailed information about a space. Includes the current count, the daily reset time, the list of doorways linked to this space, space type, and address information, and its parent in the space hierarchy.

GET /spaces/:space_id/

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/

Example Response

{
  "id": "spc_452554024357462439",
  "name": "1st St Office",
  "description": "The Whole Office Building",
  "parent_id": null,
  "space_type": "building",
  "timezone": "America/New_York",
  "daily_reset": "13:00",
  "current_count": 5,
  "doorways": [
    {
      "id": "drw_452554070478029236",
      "name": "Front Door",
      "sensor_placement": 1
    }
  ],
  "tags": [
    "tech_garden"
  ],
  "address_line1": "1516 1st St",
  "address_line2": "Suite 902",
  "city": "New York",
  "state_province": "NY",
  "postal_code": "10001",
  "country_code": "US",
  "latitude": null,
  "longitude": null
}

Create Space

Add a space to your environment.

POST /spaces/

Request Body

* name
required | string

The name of the space.

description
string

A description of the space.

timezone
string

The timezone of the space.

daily_reset
string

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.

space_type
string

The space type: space (default), floor, building, or campus.

parent
string

The ID of the parent space if in a hierarchy.

address_line1
string

First line of address.

address_line2
string

Second line of address.

city
string

City or town.

state_province
string

State or province.

postal_code
string

Postal or ZIP code.

country_code
string

ISO 3166-1 alpha-2 country code.

latitude
float

Latitude for precision mapping.

longitude
float

Longitude for precision mapping.

Example Request

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/v2/spaces/

Example Response

{
  "id": "spc_458687913710846960",
  "name": "Kitchen",
  "description": "Office Kitchen",
  "timezone": "America/New_York",
  "daily_reset": "14:00",
  "current_count": 0,
  "doorways": [],
  "tags": [],
  "address_line1": null,
  "address_line2": null,
  "city": null,
  "state_province": null,
  "postal_code": null,
  "country_code": null,
  "latitude": null,
  "longitude": null
}

Update Space

Update a space.

PUT /spaces/:space_id/

Request Body

name
string

The name of the space.

description
string

A description of the space.

timezone
string

The timezone of the space. Should be formatted as an ISO 8601 UTC timestamp.

daily_reset
string

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.

capacity
integer

Maximum occupancy of the space. Used to calculate utilization metrics.

space_type
string

The space type: space (default), floor, building, or campus.

parent
string

The ID of the parent space if in a hierarchy.

address_line1
string

First line of address.

address_line2
string

Second line of address.

city
string

City or town.

state_province
string

State or province.

postal_code
string

Postal or ZIP code.

country_code
string

ISO 3166-1 alpha-2 country code.

latitude
float

Latitude for precision mapping.

longitude
float

Longitude for precision mapping.

Example Request

curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "name": "Big Kitchen",
    "daily_reset": "13:00",
    "capacity": 20
}' \
https://api.density.io/v2\
/spaces/spc_458687913710846960/

Example Response

{
  "id": "spc_458687913710846960",
  "name": "Big Kitchen",
  "description": "The Larger Office Kitchen",
  "parent_id": "spc_538733757872472111",
  "space_type": "space",
  "timezone": "America/New_York",
  "daily_reset": "13:00",
  "current_count": 0,
  "capacity": 20,
  "doorways": [],
  "tags": [],
  "address_line1": null,
  "address_line2": null,
  "city": null,
  "state_province": null,
  "postal_code": null,
  "country_code": null,
  "latitude": null,
  "longitude": null
}

Delete Space

Delete a space from your environment.

Warning: Deleting a space will destroy all historical counts for that space.

DELETE /spaces/:space_id/

Request Body

* name
required | string

The current name of the space. Must be an exact match.

Example Request

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "name": "Kitchen (Updated)"
}' \
https://api.density.io/v2\
/spaces/spc_458687913710846960/

Tag Space

Tag a space.

POST /spaces/:space_id/tags/

Request Body

* tag_name
required | string

The tag name. Alphanumeric characters, underscore or minus sign only.

Example Request

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "tag_name": "tech_garden"
}' \
https://api.density.io/v2/spaces/spc_452554024357462439/tags/

Example Response

{
  "tag_name": "tech_garden"
}

Untag Space

Untag a space.

DELETE /spaces/:space_id/tags/:tag_name/

Example Request

curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/spaces/spc_452554024357462439/tags/tech_garden/

Doorways

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_serial_number value on the doorway. Every active doorway has exactly one sensor attached to it.

Doorways can be organized with tags (see below).

List Doorways

List all doorways for an account. Note that space associations must be queried for each individual doorway.

GET /doorways/

Query String Parameters

space_id

If included, return only doorways associated with this space.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2/doorways/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "drw_437303389773103967",
      "sensor_serial_number": "Z458467949888405826",
      "name": "Conference Room Door",
      "tags": [
        "tech_garden"
      ]
    },
    {
      "id": "drw_452554070478029236",
      "sensor_serial_number": "Z457234837531526031",
      "name": "Office Door",
      "tags": [
        "tech_garden"
      ]
    }
  ]
}

Create Doorway

Add a new doorway to your environment.

POST /doorways/

Request Body

* name
required | string

A unique name for the doorway.

description
string

A description for the doorway.

sensor_serial_number
string

The serial_number of the sensor attached to this doorway, if any.

Example Request

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/v2/doorways/

Example Response

{
  "id": "drw_458687903724209131",
  "sensor_serial_number": null,
  "name": "Kitchen Door",
  "description": "The doorway to the Kitchen",
  "spaces": [],
  "tags": []
}

Get Doorway

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/

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/doorways/drw_437303389773103967/

Example Response

{
  "id": "drw_437303389773103967",
  "sensor_serial_number": "Z458467949888405826",
  "name": "Conference Room Door",
  "description": "The doorway to the Conference Room (inside the Office)",
  "spaces": [
    {
      "id": "spc_439805443284402880",
      "name": "Conference Room",
      "sensor_placement": 1
    }
  ],
  "tags": [
    "tech_garden"
  ]
}

Update Doorway

Update a doorway.

PUT /doorways/:doorway_id/

Request Body

name
string

A unique name for the doorway.

description
string

A description for the doorway.

sensor_serial_number
string

The serial_number of the sensor attached to this doorway, if any.

Example Request

curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "name": "Conference Room Door (Updated)"
}' \
https://api.density.io/v2\
/doorways/drw_437303389773103967/

Example Response

{
  "id": "drw_437303389773103967",
  "sensor_serial_number": "Z458467949888405826",
  "name": "Conference Room Door (Updated)",
  "description": "The doorway to the Conference Room (inside the Office)",
  "spaces": [
    {
      "id": "spc_439805443284402880",
      "name": "Conference Room",
      "sensor_placement": 1
    }
  ],
  "tags": [
    "tech_garden"
  ]
}

Delete Doorway

Delete a doorway from your environment.

DELETE /doorways/:doorway_id/

Example Request

curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/doorways/drw_458687903724209131/

Tag Doorway

Tag a doorway.

POST /doorways/:doorway_id/tags/

Request Body

* tag_name
required | string

The tag name. Alphanumeric characters, underscore or minus sign only.

Example Request

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "tag_name": "tech_garden"
}' \
https://api.density.io/v2\
/doorways/drw_437303389773103967/tags/

Example Response

{
  "tag_name": "tech_garden"
}

Untag Doorway

Untag a doorway.

DELETE /doorways/:doorway_id/tags/:tag_name/

Example Request

curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/doorways/drw_437303389773103967/tags/tech_garden/

Tags

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.

List Tags

Index of all tags for an account.

GET /tags/

Example Request

$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \ 
  https://api.density.io/v2/tags/

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "tech_garden"
    }
  ]
}

Get Tag

List all spaces and doorways for a single tag. Note that additional details must be queried for each individual item.

GET /tags/:tag_name/

Example Request

$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.density.io/v2/tags/tech_garden/

Example Response

{
  "name": "tech_garden",
  "spaces": [
    {
      "id": "spc_439805443284402880",
      "name": "Conference Room",
      "current_count": 3
    },
    {
      "id": "spc_452554024357462439",
      "name": "Office",
      "current_count": 7
    },
    {
      "id": "spc_458687913710846960",
      "name": "Kitchen (Updated)",
      "current_count": 1
    }
  ],
  "doorways": [
    {
      "id": "drw_437303389773103967",
      "name": "Conference Room Door (Updated)"
    },
    {
      "id": "drw_452554070478029236",
      "name": "Office Door"
    },
    {
      "id": "drw_458687903724209131",
      "name": "Kitchen Door"
    }
  ]
}

Sensors

A Density sensor is the physical hardware module that is mounted above a doorway. Each active doorway must have a sensor associated with it. In production, real Density sensors will be automatically updated with their current status.

List Sensors

List sensors in your environment.

GET /sensors/

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2/sensors/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "serial_number": "Z458467949888405826",
      "doorway_id": "drw_437303389773103967",
      "doorway_name": "Conference Room Door",
      "sensor_type": "virtual",
      "status": "ok"
    },
    {
      "serial_number": "Z458914847325684272",
      "doorway_id": "drw_452554070478029236",
      "doorway_name": "Office Door",
      "sensor_type": "virtual",
      "status": "ok"
    }
  ]
}

Create Sensor

Create a virtual sensor. The returned id can be used to create virtual events in your environment.

POST /sensors/

Request Body

doorway_id
string

The id of the doorway that this virtual sensor is attached to.

status
string

The status of the sensor. Defaults to "ok".

Example Request

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
    "doorway_id": "drw_458687903724209131",
    "status": "ok"
}' \
https://api.density.io/v2/sensors/

Example Response

{
  "id": "Z458914847325684272",
  "doorway_id": "drw_458687903724209131",
  "doorway_name": "Kitchen Door",
  "sensor_type": "virtual",
  "status": "ok"
}

Get Sensor

View the current status of a sensor.

GET /sensors/:serial_number/

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/sensors/Z458914847325684272/

Example Response

{
  "id": "Z458914847325684272",
  "doorway_id": "drw_458687903724209131",
  "doorway_name": "Kitchen Door",
  "sensor_type": "virtual",
  "status": "ok",
  "last_heartbeat": "2016-09-19T15:45:00"
}

Delete Sensor

Delete a virtual sensor from your environment.

DELETE /sensors/:serial_number/

Example Request

curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2/sensors/Z458914847325684272/

Webhooks

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

List webhooks in your environment.

GET /webhooks/

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2/webhooks/

Example Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": "whk_458914869530329656",
        "endpoint": "https://your-website.com/some-action"
      }
    ]
}

Create Webhook

Add a new webhook to your environment.

POST /webhooks/

Request Body

* endpoint
required | string

The URL to which Density will send event data.

Example Request

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/v2/webhooks/

Example Response

{
    "id": "whk_458914869530329656",
    "endpoint": "https://your-website.com/some-action"
}

Get Webhook

Detailed information about a webhook.

GET /webhooks/:webhook_id/

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/webhooks/whk_458914869530329656/

Example Response

{
  "id": "whk_458914869530329656",
  "endpoint": "https://your-website.com/some-action"
}

Update Webhook

Update a webhook.

PUT /webhooks/:webhook_id/

Request Body

* endpoint
required | string

A new URL for the endpoint.

Example Request

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/v2\
/webhooks/whk_458914869530329656/

Example Response

{
  "id": "whk_458914869530329656",
  "endpoint": "https://some-website.com/other-endpoint"
}

Delete Webhook

Delete a webhook from your environment.

DELETE /webhooks/:webhook_id/

Example Request

curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.density.io/v2\
/webhooks/whk_458914869530329656/

Receiving Webhook

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

Example Webhook Data

{
  "space_id": "spc_439805443284402880",
  "doorway_id": "drw_437303389773103967",
  "direction": 1,
  "count": 32
}