Density Public API (beta)

Download OpenAPI specification:Download

This service provides a layer of abstraction on top of the Density data API's.

It is intended for use by the general public.

Metrics

Occupancy

Calculates the occupancy for a set of spaces or for all spaces in a portfolio.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

end_date required	string end of the query date range, inclusive
space_ids	Array of strings specific spaces to query
start_date required	string start of the query date range
time_resolution	string Default: "total" time resolution for the query results Enum: "total" "hour" "day" "week" "month" "year" "weekday" "hour_of_day" "minute" "10minute"

Responses

200

success

400

request data was missing or invalid

401

unable to authorize the given bearer token

403

access to this api is not allowed

404

resource not found

500

unexpected error

post/v3/analytics/occupancy

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"end_date": "2024-02-28T23:59:59Z",
"space_ids": ["spc_12345678901",
"spc_10987654321"
],
"start_date": "2024-02-28T00:00:00Z",
"time_resolution": "total"
}

Response samples

application/json

{"spc_10987654321": {"avg": 1.5,
"max": 2,
"min": 1
},
"spc_12345678901": {"avg": 1.5,
"max": 2,
"min": 1
}
}

Time Used

Calculates the time used for a set of spaces or for all spaces in a portfolio.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

end_date required	string end of the query date range, inclusive
space_ids	Array of strings specific spaces to query
start_date required	string start of the query date range
time_resolution	string Default: "total" time resolution for the query results Enum: "total" "hour" "day" "week" "month" "year" "weekday" "hour_of_day" "minute" "10minute"

Responses

200

success

400

request data was missing or invalid

401

unable to authorize the given bearer token

403

access to this api is not allowed

404

resource not found

500

unexpected error

post/v3/analytics/time-used

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"end_date": "2024-02-28T23:59:59Z",
"space_ids": ["spc_12345678901",
"spc_10987654321"
],
"start_date": "2024-02-28T00:00:00Z",
"time_resolution": "total"
}

Response samples

application/json

{"spc_10987654321": {"percentage": 0.5,
"raw": 450000
},
"spc_12345678901": {"percentage": 0.5,
"raw": 450000
}
}

Utilization

Calculates the utilization for a set of spaces or for all spaces in a portfolio.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

end_date required	string end of the query date range, inclusive
space_ids	Array of strings specific spaces to query
start_date required	string start of the query date range
time_resolution	string Default: "total" time resolution for the query results Enum: "total" "hour" "day" "week" "month" "year" "weekday" "hour_of_day" "minute" "10minute"

Responses

200

success

400

request data was missing or invalid

401

unable to authorize the given bearer token

403

access to this api is not allowed

404

resource not found

500

unexpected error

post/v3/analytics/utilization

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"end_date": "2024-02-28T23:59:59Z",
"space_ids": ["spc_12345678901",
"spc_10987654321"
],
"start_date": "2024-02-28T00:00:00Z",
"time_resolution": "total"
}

Response samples

application/json

{"spc_10987654321": {"avg": 0.5,
"max": 1
},
"spc_12345678901": {"avg": 0.5,
"max": 1
}
}

Live

Current Occupancy

Returns the most current occupancy for a set of spaces or for all spaces in a portfolio. Only entry spaces are supported.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

space_ids

Array of strings

specific spaces to query

Responses

200

success

401

unable to authorize the given bearer token

403

access to this api is not allowed

500

unexpected error

post/v3/analytics/occupancy/current

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"space_ids": ["spc_12345678901",
"spc_10987654321"
]
}

Response samples

application/json

{"spc_10987654321": {"count": 5,
"space_health_status": "healthy"
},
"spc_12345678901": {"count": 5,
"space_health_status": "healthy"
}
}

Presence

Returns the current occupied status for a set of spaces or for all spaces in a portfolio.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

space_ids

Array of strings

specific spaces to query

Responses

200

success

401

unable to authorize the given bearer token

403

access to this api is not allowed

500

unexpected error

post/v3/analytics/presence

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"space_ids": ["spc_12345678901",
"spc_10987654321"
]
}

Response samples

application/json

{"spc_10987654321": false,
"spc_12345678901": true
}

Health Aware Presence

Returns the current occupied and space health status for a set of spaces or for all spaces in a portfolio.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

space_ids

Array of strings

specific spaces to query

Responses

200

success

401

unable to authorize the given bearer token

403

access to this api is not allowed

500

unexpected error

post/v3/analytics/presence-health

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"space_ids": ["spc_12345678901",
"spc_10987654321"
]
}

Response samples

application/json

{"spc_10987654321": {"presence": true,
"space_health_status": "healthy"
},
"spc_12345678901": {"presence": true,
"space_health_status": "healthy"
}
}

Short-Term Analytics

Determines short-term Presence for a set of spaces or for all spaces in an organization. Only OA spaces and floors are supported.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

minutes_lookback	integer <uint32> Default: 0 the length of time in minutes for which historical presence information will be fetched. 0 value will return the current minute. 5 will return the current minute, plus 5 mins before. Max value is 240 minutes.
space_ids	Array of strings specific spaces to query. Only areas and floors will be processed.

Responses

200

success

400

request data was missing or invalid

401

unable to authorize the given bearer token

403

access to this api is not allowed

404

resource not found

500

unexpected error

post/v3/analytics/short-term

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"minutes_lookback": 60,
"space_ids": ["spc_12345678901",
"spc_10987654321"
]
}

Response samples

application/json

{"data": [{"metrics": [{"presence": true,
"timestamp": "2023-05-17T00:00:00Z"
}
],
"space_id": "spc_1234567890"
}
]
}

Create Presence WebSocket

Returns a WebSocket endpoint to receive presence messages for spaces on a floor.

SecurityapiKey or application

Request

path Parameters

floor_id

required

string

space id for a floor.

Responses

200

success

400

BadRequestError is an error returned when the request is malformed or invalid.

401

UnauthorizedError is an error returned when the request is unauthorized.

403

ForbiddenError is an error returned when the request is forbidden.

404

NotFoundError is an error returned when the requested resource is not found.

500

InternalServerError is an error returned when the server encounters an error.

post/v3/analytics/ws/floor/{floor_id}/presence

Request samples

curl
Go
Python
JavaScript

Response samples

application/json

{"ws_url": "string"
}

Info

Hello World

Validate your access to the Density public API.

Responses

200

success

401

unable to authorize the given bearer token

403

access to this api is not allowed

get/v3/hello-world

Request samples

curl
Go
Python
JavaScript

Response samples

text/plain

Do… or do not. There is no try. - Yoda

API Version

API version.

Responses

200

success

401

unable to authorize the given bearer token

403

access to this api is not allowed

get/version

Request samples

curl
Go
Python
JavaScript

Response samples

text/plain

1.0.2

Auth

Density Access Token

OAuth token flow for machine-to-machine users. Generate an access token using client credentials.

Request

Request Body schema: application/json
required

request body input

client_id required	string
client_secret required	string
grant_type required	string Value: "client_credentials"

Responses

200

success

400

bad request

401

unable to authorize client

500

unexpected error

post/v3/oauth/token

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"client_id": "string",
"client_secret": "string",
"grant_type": "client_credentials"
}

Response samples

application/json

{"access_token": "string",
"expires_in": "string",
"token_type": "string"
}

Sensors

Lists sensors

Request

Request Body schema: application/json
required

Request body input. Can filter by either serial numbers or space ids.

serial_numbers	Array of strings
space_ids	Array of strings

Responses

200

success

400

BadRequestError is an error returned when the request is malformed or invalid.

401

UnauthorizedError is an error returned when the request is unauthorized.

403

ForbiddenError is an error returned when the request is forbidden.

404

NotFoundError is an error returned when the requested resource is not found.

500

InternalServerError is an error returned when the server encounters an error.

post/v3/sensors

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"serial_numbers": ["string"
],
"space_ids": ["spc_12345678901",
"spc_10987654321"
]
}

Response samples

application/json

[{"created_at": "2019-08-24T14:15:22Z",
"firmware_version": "string",
"hardware_type": "ob1",
"location": {"building_ids": ["spc_12345678901"
],
"floor_ids": ["spc_10987654321"
],
"space_ids": ["spc_50985556621"
]
},
"network_addresses": [{"address": "string",
"family": "string",
"if": "string",
"mac": "string"
}
],
"sensor_type": "oa",
"serial_number": "A1B6Z10",
"updated_at": "2019-08-24T14:15:22Z"
}
]

Historical Sensor Health

Lists sensor health changes over the requested period of time.

Request

Request Body schema: application/json
required

Request body input. Can filter by either serial numbers or space ids.

end_date required	string end of the query date range, inclusive
serial_numbers	Array of strings
space_ids	Array of strings
start_date required	string start of the query date range, max range is 10 days

Responses

200

success

post/v3/sensors/health

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"end_date": "2024-02-28T23:59:59Z",
"serial_numbers": ["string"
],
"space_ids": ["spc_12345678901",
"spc_10987654321"
],
"start_date": "2024-02-28T00:00:00Z"
}

Response samples

application/json

{"A1B6Z10": [{"health_status": "healthy",
"timestamp": "2024-01-01T00:00:00Z"
},
{"health_status": "healthy",
"timestamp": "2024-01-01T00:00:00Z"
}
]
}

Current Sensor Health

Lists sensor current health

Request

Request Body schema: application/json
required

Request body input. Can filter by either serial numbers or space ids.

serial_numbers	Array of strings
space_ids	Array of strings

Responses

200

success

400

BadRequestError is an error returned when the request is malformed or invalid.

401

UnauthorizedError is an error returned when the request is unauthorized.

403

ForbiddenError is an error returned when the request is forbidden.

404

NotFoundError is an error returned when the requested resource is not found.

500

InternalServerError is an error returned when the server encounters an error.

post/v3/sensors/health/current

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"serial_numbers": ["string"
],
"space_ids": ["spc_12345678901",
"spc_10987654321"
]
}

Response samples

application/json

{"data": [{"health_status": "healthy",
"last_status_change": "2019-08-24T14:15:22Z",
"serial_number": "string"
}
]
}

Spaces

Get all spaces for an organization.

SecurityapiKey or application

Responses

200

success

401

unable to authorize the given bearer token

403

access to this api is not allowed

500

unexpected error

get/v3/spaces

Request samples

curl
Go
Python
JavaScript

Response samples

application/json

[{"address": "string",
"capacity": 0,
"children": [{ }
],
"children_ids": ["string"
],
"cost_per_sqft": 0,
"counting_mode": "string",
"daily_reset": "string",
"function": null,
"go_live_date_utc": "string",
"id": "string",
"iwms_id": "string",
"labels": [{"group": {"id": "string",
"name": "string"
},
"id": "string",
"name": "string",
"spaces": [{"current_count": 0,
"id": "string",
"name": "string"
}
]
}
],
"name": "string",
"size_area": 0,
"space_type": "portfolio",
"status": "string",
"time_zone": "string"
}
]

Users

Read Users

Read a list of users in your organization. Only available for Machine to Machine tokens with correct permissions.

SecurityapiKey or application

Responses

200

success

400

bad request

401

unable to authorize client

403

forbidden

500

unexpected error

get/v3/users

Request samples

curl
Go
Python
JavaScript

Response samples

application/json

[{"created_at": "2019-08-24T14:15:22Z",
"email": "string",
"full_name": "string",
"id": "string",
"role": "owner",
"spaces": ["string"
]
}
]

Create User

Create a user. Only available for Machine to Machine tokens with correct permissions.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

email	string
full_name	string
role	string role for the user Enum: "owner" "admin" "editor" "readonly"
spaces	Array of strings

Responses

201

success

400

bad request

401

unable to authorize client

403

forbidden

500

unexpected error

post/v3/users

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"email": "string",
"full_name": "string",
"role": "owner",
"spaces": ["string"
]
}

Response samples

application/json

{"created_at": "2019-08-24T14:15:22Z",
"email": "string",
"full_name": "string",
"id": "string",
"role": "owner",
"spaces": ["string"
]
}

Delete User

Delete user. Only available for Machine to Machine tokens with correct permissions.

SecurityapiKey or application

Responses

204

success

400

bad request

401

unable to authorize client

403

forbidden

500

unexpected error

delete/v3/users/:user_id

Request samples

curl
Go
Python
JavaScript

Response samples

application/json

{"code": 0,
"message": "string"
}

Read User

Read a user in your organization. Only available for Machine to Machine tokens with correct permissions.

SecurityapiKey or application

Responses

200

success

400

bad request

401

unable to authorize client

403

forbidden

500

unexpected error

get/v3/users/:user_id

Request samples

curl
Go
Python
JavaScript

Response samples

application/json

{"created_at": "2019-08-24T14:15:22Z",
"email": "string",
"full_name": "string",
"id": "string",
"role": "owner",
"spaces": ["string"
]
}

Update User

Update user role, name, or spaces. Only available for Machine to Machine tokens with correct permissions.

SecurityapiKey or application

Request

Request Body schema: application/json
required

request body input

full_name	string
role	string role for the user Enum: "owner" "admin" "editor" "readonly"
spaces	Array of strings

Responses

200

success

400

bad request

401

unable to authorize client

403

forbidden

500

unexpected error

put/v3/users/:user_id

Request samples

Payload
curl
Go
Python
JavaScript

application/json

{"full_name": "string",
"role": "owner",
"spaces": ["string"
]
}

Response samples

application/json

{"created_at": "2019-08-24T14:15:22Z",
"email": "string",
"full_name": "string",
"id": "string",
"role": "owner",
"spaces": ["string"
]
}

Density Public API (beta)

Metrics

Occupancy

Request Body schema: application/jsonrequired

Time Used

Request Body schema: application/jsonrequired

Utilization

Request Body schema: application/jsonrequired

Live

Current Occupancy

Request Body schema: application/jsonrequired

Presence

Request Body schema: application/jsonrequired

Health Aware Presence

Request Body schema: application/jsonrequired

Short-Term Analytics

Request Body schema: application/jsonrequired

Create Presence WebSocket

path Parameters

Info

Hello World

API Version

Auth

Density Access Token

Request Body schema: application/jsonrequired

Sensors

Sensors

Lists sensors

Request Body schema: application/jsonrequired

Historical Sensor Health

Lists sensor health changes over the requested period of time.

Request Body schema: application/jsonrequired

Current Sensor Health

Lists sensor current health

Request Body schema: application/jsonrequired

Spaces

Spaces

Users

Read Users

Create User

Request Body schema: application/jsonrequired

Delete User

Read User

Update User

Request Body schema: application/jsonrequired

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required