Introduction
The Sighthound Data API is a REST API that is used to extract meta-data from Sighthound devices. The API is separated into several different namespaces, which provide access to different datasets. Those sections are the following:
Data - This is a legacy namespace that provides access to raw data and ad-hoc aggregations of raw data. Sighthound Analytics output will not be available via this namespace.
Stream - This is the next generation of the data namespace. This namespace provides access to both row level data and ad-hoc aggregations of data. The row level data available in the stream namespace provides a detailed view of the event in the meta field of the response. The meta field provides the entire Sighthound analytics output, which can be found here
Roll Up - Provides access to streaming data aggregations & the ability to configure streaming aggregations. Roll-ups allow you to pre-configure aggregations amongst multiple streams, devices, and sensors. For example if you want to know the count of vehicles in a parking lot via sensors drawn on two different streams, you can create a roll-up that will calculate the number of vehicles in the parking lot via sensors at each of the entrance and exit points.
Device Status - Provides access to device status data.
Service Account - Provides access to configure service accounts for access to data APIs.
Alerts (Beta) - Provides access to configure alerts.
Authentication
Sighthound uses API keys to allow access to the API. You can register a new Sighthound API Key at our Integrations Portal.
Sighthound expects for the API key to be included in all API requests to the server in a header that looks like the following:
X-API-KEY: 38ed7729792c48489945c8060255fa45
Event Values
Event values & direction differ depending on the sensor type. The following details provide information as to what you can expect from the value and direction field of the common sensor types.
Sensor Type | Value | Direction |
---|---|---|
COUNT | The # of objects that crossed a given line | NORTH/SOUTH - based on the direction of the crossing. |
SPEED | The estimated speed of an object between two lines. | NORTH/SOUTH - based on the direction of the crossing of the two lines. |
FISH | The estimated length of a fish. | NORTH/SOUTH - based on the exit direction of the fish. |
PRESENCE | The amount of time (in seconds) that an object spent in a region of interest. If the value is reported as 0for a presence sensor, there is currently an object in the region of interest. | N/A |
COLLISION | The amount of time (in seconds) that the objects spent in a region of interest at the same time | N/A |
Datatypes
Timestamps
All data APIs utilize ISO DateTimeFormat. This allows you to specify the timezone in the request of the API. The following are examples of valid timestamp formats for the API
- "2021-06-01T00:00.000Z"
- "2021-06-01T00:00.000+06:00"
- "2021-06-01T00:00.000-06:00"
- "2021-03-08T20:00.000+1100"
Sensor Data / Meta
Presence Sensor
The presence sensor is used to determine the number of objects within a give region of interest.
Presence Sensor Entry
{
"active" : true,
"numObjectsInRegion" : 2,
"object" : {
"enteredOn" : 1624247455819,
"objectType" : "person",
"uniqueId" : 7953144757666971748
},
"startOn" : 1624247455553
}
Presence Sensor Exit
{
"active" : false,
"numObjectsInRegion" : 0,
"object" : {
"enteredOn" : 1624247516781,
"exitOn" : 1624247522937,
"objectType" : "person",
"uniqueId" : 6472069442200142026
},
"startOn" : 1624247516781,
"stopOn" : 1624247522937,
"timeOn" : 6.1558170318603516
}
Field | Description | Type | Default Value | Examples |
---|---|---|---|---|
active | Whether or not there is currently an object actively in the region of interest. | boolean | false | true false |
numObjectsInRegion | The number of objects that are in the region of interest at the time of the associated event. | integer | 2 | 2 5 |
object | The object which triggered the presence sensor. | object | {"enteredOn":1624247455819,"objectType":"person","uniqueId":7953144757666971748} |
|
startOn | The time for which the presence sensor was first active. Measured in number of milliseconds from epoch. | integer | 1624247455553 | |
stopOn | The time for which the presence sensor became inactive. Measured in number of milliseconds from epoch. | integer | 1624247522937 | |
timeOn | The amount of time, in seconds that the region of interest was occupied. This field is only populated once the region of interest is no longer active. | double | 6.155817031860352 |
Data
Query Aggregated Sensor Data
api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"
curl "https://data-api.boulderai.com/data/query?startTime=${startTime}&endTime=${endTime}" \
-d '{"deviceId":"BAI_0000111","streamId":null,"sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","interval":"1 hour","functions":["COUNT","SUM","AVERAGE","MIN","MAX","MEDIAN","QUARTILE_1","QUARTILE_2","QUARTILE_3"],"fillEmptyWindows":true,"order":"ASCENDING"}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"deviceId" : "BAI_0000111",
"sensorName" : "COUNT_PERSON_1",
"direction" : "NORTH",
"windowStart" : "2021-01-15T00:00:00.000Z",
"windowEnd" : "2021-01-15T01:00:00.000Z",
"values" : [
{
"function" : "COUNT",
"value" : 10.0
},
{
"function" : "SUM",
"value" : 10.0
},
{
"function" : "AVERAGE",
"value" : 10.0
},
{
"function" : "MIN",
"value" : 10.0
},
{
"function" : "MAX",
"value" : 10.0
},
{
"function" : "MEDIAN",
"value" : 10.0
},
{
"function" : "QUARTILE_1",
"value" : 10.0
},
{
"function" : "QUARTILE_2",
"value" : 10.0
},
{
"function" : "QUARTILE_3",
"value" : 10.0
}
]
}
]
This endpoint is used to query sensor data over a specific time period with aggregation methods.
Function | Description |
---|---|
COUNT | Count of occurrences |
SUM | Sum of all values |
AVERAGE | Average of all values |
MIN | Minimum value |
MAX | Maximum value |
MEDIAN | Median value |
QUARTILE_1 | Value at the 1st quartile |
QUARTILE_2 | Value at the 2nd quartile |
QUARTILE_3 | Value at the 3rd quartile |
HTTP Request
POST /data/query?startTime={startTime}&endTime={endTime}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
startTime | true | The startTime of the report to generate. | 2021-01-15T00:00:00.000Z |
endTime | true | The endTime of the report to generate. | 2021-01-15T04:00:00.000Z |
Query Flattened Sensor Data
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/data/sensor/query" \
-d '{"deviceId":"BAI_0000111","sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","withImages":true,"withTracks":false,"limit":10,"order":"DESCENDING"}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"id" : "27903698-80a3-488a-a403-f5783b22a320",
"deviceId" : "BAI_0000111",
"objectType" : "person",
"sensorName" : "COUNT_PERSON_1",
"direction" : "SOUTH",
"timeCollected" : "2021-01-15T00:01:00.000Z",
"value" : 1.0,
"boundingBoxImage" : null,
"frameImage" : null,
"track" : null
},
{
"id" : "f2659be9-7d77-4ed3-8f95-eacc8a8d8e90",
"deviceId" : "BAI_0000111",
"objectType" : "car",
"sensorName" : "SPEED_CAR_1",
"direction" : "NORTH",
"timeCollected" : "2021-01-15T00:02:00.000Z",
"value" : 45.0,
"boundingBoxImage" : null,
"frameImage" : null,
"track" : null
}
]
This endpoint is used to query sensor data over a specific time period.
HTTP Request
POST /data/sensor/query
Get Sensor Data by Id
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/data/id/${workspaceId}/${eventId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"deviceId" : "BAI_0000111",
"objectType" : "person",
"timeCollected" : "2021-01-15T00:00:00.000Z",
"uniqueId" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
"confidence" : 0,
"model" : "peoplecounter_V0.1",
"length" : null,
"speed" : null,
"sensorData" : {
"sensorName" : "COUNT_PERSON_3",
"objectClass" : "person",
"direction" : 1
},
"track" : null,
"bboxImg" : null,
"frameImg" : null
}
]
This endpoint is used to retrieve a specific event on a device.
HTTP Request
GET /data/id/{workspaceId}/{eventId}
Get Sensors by Device
api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"
curl "https://data-api.boulderai.com/device/${deviceId}/sensors?startTime=${startTime}&endTime=${endTime}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"deviceId" : "BAI_0000111",
"streamId" : null,
"sensorName" : "COUNT_PERSON_1",
"direction" : "NORTH",
"objectType" : "person",
"count" : 10,
"lastTimeCollected" : "2021-01-15T04:00:00.000Z"
},
{
"deviceId" : "BAI_0000111",
"streamId" : null,
"sensorName" : "SPEED_CAR_1",
"direction" : "SOUTH",
"objectType" : "car",
"count" : 10,
"lastTimeCollected" : "2021-01-15T04:00:00.000Z"
}
]
This endpoint is used to get a list of sensors that exist over a specific time period.
HTTP Request
GET /device/{deviceId}/sensors?startTime={startTime}&endTime={endTime}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
startTime | true | The startTime of the report to generate. | 2021-01-15T00:00:00.000Z |
endTime | true | The endTime of the report to generate. | 2021-01-15T04:00:00.000Z |
Get Sensors by Workspace
api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"
curl "https://data-api.boulderai.com/workspace/${workspaceId}/sensors?startTime=${startTime}&endTime=${endTime}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"deviceId" : "BAI_0000111",
"streamId" : null,
"sensorName" : "COUNT_PERSON_1",
"direction" : "NORTH",
"objectType" : "person",
"count" : 10,
"lastTimeCollected" : "2021-01-15T04:00:00.000Z"
},
{
"deviceId" : "BAI_0000111",
"streamId" : null,
"sensorName" : "SPEED_CAR_1",
"direction" : "SOUTH",
"objectType" : "car",
"count" : 10,
"lastTimeCollected" : "2021-01-15T04:00:00.000Z"
}
]
This endpoint is used to get all of the sensors that have reported data for a given workspace over a period of time.
HTTP Request
GET /workspace/{workspaceId}/sensors?startTime={startTime}&endTime={endTime}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
startTime | true | The startTime of the report to generate. | 2021-01-15T00:00:00.000Z |
endTime | true | The endTime of the report to generate. | 2021-01-15T04:00:00.000Z |
Media
The media endpoints are used to query media data that is extracted from sensors. The response will reference a url which is reference to a storage location (Google Cloud Storage, Amazon S3, etc.). In order to request permissions to access the given media for your workspace please reach out to Sighthound support.
Get Latest Media Data
api_key="38ed7729792c48489945c8060255fa45"
mediaType="IMAGE"
curl "https://data-api.boulderai.com/media/${streamId}/latest?mediaType=${mediaType}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
"deviceId" : "BAI_0000111",
"timeCollected" : "2021-01-15T00:00:00.000Z",
"mediaType" : "IMAGE",
"url" : "gs://**/**/7fe553c8-cc34-11ea-9439-0242ac120002-bb-frame.jpg",
"captureType" : "RAW",
"startTime" : null,
"durationMs" : null,
"objects" : [
],
"events" : [
]
}
]
This endpoint is used to retrieve the latest media from a stream.
HTTP Request
GET /media/{streamId}/latest?mediaType={mediaType}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
mediaType | false | The mediaType which you want to query | IMAGE |
Query Media Data
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/media/query" \
-d '{"streamId":"11c33a12-5098-450a-9fc3-cf9d97b958a7","mediaType":"IMAGE_AND_VIDEO","startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z"}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
"deviceId" : "BAI_0000111",
"timeCollected" : "2021-01-15T00:00:00.000Z",
"mediaType" : "VIDEO",
"url" : "gs://**/**/7fe553c8-cc34-11ea-9439-0242ac120002-input-video.mp4",
"captureType" : "RAW",
"startTime" : "2021-01-15T00:00:00.000Z",
"durationMs" : 10000,
"objects" : [
{
"objectId" : 7953144757666971748
}
],
"events" : [
{
"eventId" : "aeb624a3-7a47-48d9-8530-72b233f5ad96"
}
]
},
{
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
"deviceId" : "BAI_0000111",
"timeCollected" : "2021-01-15T00:00:00.000Z",
"mediaType" : "IMAGE",
"url" : "gs://**/**/7fe553c8-cc34-11ea-9439-0242ac120002-bb-frame.jpg",
"captureType" : "RAW",
"startTime" : null,
"durationMs" : null,
"objects" : [
],
"events" : [
]
}
]
This endpoint is used to query media from streams. Currently the API supports both image and video types.
HTTP Request
POST /media/query
Get Media Image or Video
api_key="38ed7729792c48489945c8060255fa45"
mediaId="aeb624a3-7a47-48d9-8530-72b233f5ad96"
curl "https://data-api.boulderai.com/media/${streamId}?mediaId=${mediaId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
"No example provided."
This endpoint is used to retrieve a given media object.
HTTP Request
GET /media/{streamId}?mediaId={mediaId}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
mediaId | false | The mediaId which you want to query | aeb624a3-7a47-48d9-8530-72b233f5ad96 |
Stream
Get Latest Stream Data
api_key="38ed7729792c48489945c8060255fa45"
sensorId="185fda6c-f1a7-4149-9057-b8751a23be1b"
curl "https://data-api.boulderai.com/data/stream/${streamId}/latest?sensorId=${sensorId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
"sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
"deviceId" : null,
"direction" : "NORTH",
"objectType" : "CAR",
"timeCollected" : "2021-01-15T00:00:00.000Z",
"value" : 10.0,
"meta" : {
"frameImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-frame.jpg",
"boundingBoxImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-object.jpg"
}
}
This endpoint is used to retrieve the latest data from a given stream.
HTTP Request
GET /data/stream/{streamId}/latest?sensorId={sensorId}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
sensorId | false | The sensor ID for which you want to query | 185fda6c-f1a7-4149-9057-b8751a23be1b |
Query Aggregated Stream Data
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/data/stream/aggregate/query" \
-d '{"streamId":"11c33a12-5098-450a-9fc3-cf9d97b958a7","deviceId":null,"sensors":["185fda6c-f1a7-4149-9057-b8751a23be1b"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","interval":"1 hour","functions":["COUNT","SUM","AVERAGE","MIN","MAX","MEDIAN","QUARTILE_1","QUARTILE_2","QUARTILE_3"],"fillEmptyWindows":true,"order":"DESCENDING"}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"deviceId" : null,
"sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
"direction" : "NORTH",
"windowStart" : "2021-01-15T00:00:00.000Z",
"windowEnd" : "2021-01-15T04:00:00.000Z",
"values" : [
{
"function" : "COUNT",
"value" : 5.0
},
{
"function" : "SUM",
"value" : 5.0
},
{
"function" : "AVERAGE",
"value" : 5.0
},
{
"function" : "MIN",
"value" : 5.0
},
{
"function" : "MAX",
"value" : 5.0
},
{
"function" : "MEDIAN",
"value" : 5.0
},
{
"function" : "QUARTILE_1",
"value" : 5.0
},
{
"function" : "QUARTILE_2",
"value" : 5.0
},
{
"function" : "QUARTILE_3",
"value" : 5.0
}
]
}
]
This endpoint is used to query aggregated data by stream.
startTime & endTime are optional. If endTime is not defined, it will default to the current timestamp. If startTime is not defined, it will default to a single window aggregation between the endTime with a length of interval.
Function | Description |
---|---|
COUNT | Count of occurrences |
SUM | Sum of all values |
AVERAGE | Average of all values |
MIN | Minimum value |
MAX | Maximum value |
MEDIAN | Median value |
QUARTILE_1 | Value at the 1st quartile |
QUARTILE_2 | Value at the 2nd quartile |
QUARTILE_3 | Value at the 3rd quartile |
HTTP Request
POST /data/stream/aggregate/query
Query Flattened Sensor Data
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/data/sensor/query" \
-d '{"deviceId":"BAI_0000111","sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","withImages":true,"withTracks":false,"limit":10,"order":"DESCENDING"}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"id" : "27903698-80a3-488a-a403-f5783b22a320",
"deviceId" : "BAI_0000111",
"objectType" : "person",
"sensorName" : "COUNT_PERSON_1",
"direction" : "SOUTH",
"timeCollected" : "2021-01-15T00:01:00.000Z",
"value" : 1.0,
"boundingBoxImage" : null,
"frameImage" : null,
"track" : null
},
{
"id" : "f2659be9-7d77-4ed3-8f95-eacc8a8d8e90",
"deviceId" : "BAI_0000111",
"objectType" : "car",
"sensorName" : "SPEED_CAR_1",
"direction" : "NORTH",
"timeCollected" : "2021-01-15T00:02:00.000Z",
"value" : 45.0,
"boundingBoxImage" : null,
"frameImage" : null,
"track" : null
}
]
This endpoint is used to query sensor data over a specific time period.
HTTP Request
POST /data/sensor/query
Get Sensors by Workspace
api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"
curl "https://data-api.boulderai.com/workspace/${workspaceId}/stream/sensor?startTime=${startTime}&endTime=${endTime}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"deviceId" : "BAI_0000111",
"sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
"sensorName" : "SPEED_CAR_1",
"direction" : "NORTH"
}
]
This endpoint is used to get all of the sensors that have reported data for a given workspace over a period of time.
HTTP Request
GET /workspace/{workspaceId}/stream/sensor?startTime={startTime}&endTime={endTime}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
startTime | true | The startTime of the report to generate. | 2021-01-15T00:00:00.000Z |
endTime | true | The endTime of the report to generate. | 2021-01-15T04:00:00.000Z |
Get Stream Data by Id
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/data/stream/${streamId}/event/${eventId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
"sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
"deviceId" : null,
"direction" : "NORTH",
"objectType" : "CAR",
"timeCollected" : "2021-01-15T00:00:00.000Z",
"value" : 10.0,
"meta" : {
"frameImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-frame.jpg",
"boundingBoxImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-object.jpg"
}
}
This endpoint is used to query individual events by event id.
HTTP Request
GET /data/stream/{streamId}/event/{eventId}
Get Latest Stream Data
api_key="38ed7729792c48489945c8060255fa45"
sensorId="185fda6c-f1a7-4149-9057-b8751a23be1b"
curl "https://data-api.boulderai.com/data/stream/${streamId}/latest?sensorId=${sensorId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
"id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
"sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
"deviceId" : null,
"direction" : "NORTH",
"objectType" : "CAR",
"timeCollected" : "2021-01-15T00:00:00.000Z",
"value" : 10.0,
"meta" : {
"frameImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-frame.jpg",
"boundingBoxImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-object.jpg"
}
}
This endpoint is used to retrieve the latest data from a given stream.
HTTP Request
GET /data/stream/{streamId}/latest?sensorId={sensorId}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
sensorId | false | The sensor ID for which you want to query | 185fda6c-f1a7-4149-9057-b8751a23be1b |
Query Flattened Sensor Data
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/data/sensor/query" \
-d '{"deviceId":"BAI_0000111","sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","withImages":true,"withTracks":false,"limit":10,"order":"DESCENDING"}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"id" : "27903698-80a3-488a-a403-f5783b22a320",
"deviceId" : "BAI_0000111",
"objectType" : "person",
"sensorName" : "COUNT_PERSON_1",
"direction" : "SOUTH",
"timeCollected" : "2021-01-15T00:01:00.000Z",
"value" : 1.0,
"boundingBoxImage" : null,
"frameImage" : null,
"track" : null
},
{
"id" : "f2659be9-7d77-4ed3-8f95-eacc8a8d8e90",
"deviceId" : "BAI_0000111",
"objectType" : "car",
"sensorName" : "SPEED_CAR_1",
"direction" : "NORTH",
"timeCollected" : "2021-01-15T00:02:00.000Z",
"value" : 45.0,
"boundingBoxImage" : null,
"frameImage" : null,
"track" : null
}
]
This endpoint is used to query sensor data over a specific time period.
HTTP Request
POST /data/sensor/query
Roll Up
Configure RollUp
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/aggregations/rollups" \
-d '{"name":"My Roll-up","workspace":"04605210-c349-49ef-8c59-c1b986cddde3","ingress":[{"deviceId":"BAI_0000111","sensorName":"COUNT_PERSON_1","direction":"NORTH"}],"egress":[{"deviceId":"BAI_0000111","sensorName":"COUNT_PERSON_1","direction":"SOUTH"}],"parent":null,"initialValue":100,"minimumValue":10,"maximumValue":1000,"scheduledAdjustments":[{"expression":"0 15 10 ? * MON-FRI","adjustmentType":"SET_TO_VALUE","adjustmentValue":100},{"expression":"0 30 11 ? * *","adjustmentType":"STANDARD","adjustmentValue":10}],"meta":{"key":"value"}}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"id" : "91729333-5e01-4fe3-9a87-f43048a660ba",
"name" : "My Roll-up",
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"ingress" : [
],
"egress" : [
],
"parent" : null,
"initialValue" : 100,
"minimumValue" : 10,
"maximumValue" : 100,
"scheduledAdjustments" : [
],
"meta" : {
"key" : "value"
},
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"createdAt" : "2022-04-14T20:05:45.480Z",
"updatedBy" : null,
"updatedAt" : null
}
This endpoint is used to configure roll-ups. Roll-ups are used in the occupancy management application.
HTTP Request
POST /aggregations/rollups
Get Roll Up Config
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/aggregations/rollups/config/${rollUpId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"id" : "91729333-5e01-4fe3-9a87-f43048a660ba",
"name" : "My Roll-up",
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"ingress" : [
],
"egress" : [
],
"parent" : null,
"initialValue" : 100,
"minimumValue" : 10,
"maximumValue" : 100,
"scheduledAdjustments" : [
],
"meta" : {
"key" : "value"
},
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"createdAt" : "2022-04-14T20:05:45.480Z",
"updatedBy" : null,
"updatedAt" : null
}
Get the configuration for a specific roll up.
HTTP Request
GET /aggregations/rollups/config/{rollUpId}
Query Roll Up
api_key="38ed7729792c48489945c8060255fa45"
rollUpId="91729333-5e01-4fe3-9a87-f43048a660ba"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"
curl "https://data-api.boulderai.com/aggregations/rollup-query?rollUpId=${rollUpId}&startTime=${startTime}&endTime=${endTime}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"data" : [
{
"rollUpId" : "91729333-5e01-4fe3-9a87-f43048a660ba",
"startTime" : "2021-01-15T00:00:00.000Z",
"endTime" : "2021-01-15T01:00:00.000Z",
"value" : 100.0,
"meta" : {
"ingress" : 10.0,
"egress" : 50.0,
"adjustments" : 0.0
}
}
]
}
Query historical roll-up values for a given time range.
HTTP Request
GET /aggregations/rollup-query?rollUpId={rollUpId}&startTime={startTime}&endTime={endTime}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
rollUpId | true | The roll up ID for which you want to query | 91729333-5e01-4fe3-9a87-f43048a660ba |
startTime | true | The startTime of the report to generate. | 2021-01-15T00:00:00.000Z |
endTime | true | The endTime of the report to generate. | 2021-01-15T04:00:00.000Z |
Get Roll-Up Configurations
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/aggregations/rollups/workspace/${workspaceId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"rollups" : [
{
"id" : "91729333-5e01-4fe3-9a87-f43048a660ba",
"name" : "My Roll-up",
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"currentValue" : 150,
"lastUpdated" : "2021-01-15T04:00:00.000Z"
}
]
}
This endpoint is used to retrieve the configured roll-ups for a given workspace.
HTTP Request
GET /aggregations/rollups/workspace/{workspaceId}
Delete a Roll-Up
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/aggregations/rollup/${rollUpId}" \
-X DELETE \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"success" : true
}
This endpoint is used to delete a specific roll-up.
HTTP Request
DELETE /aggregations/rollup/{rollUpId}
Get Roll-Up Details
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/aggregations/rollup/${rollUpId}/details" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"currentValue" : 100,
"lastUpdated" : "2021-01-15T04:00:00.000Z",
"specs" : [
{
"description" : "ingress",
"value" : 50.0
},
{
"description" : "egress",
"value" : 100.0
}
]
}
This endpoint is used to retrieve the details for a specific roll-up.
HTTP Request
GET /aggregations/rollup/{rollUpId}/details
Adjust Roll-Up Value
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/aggregations/rollup/${rollUpId}/value" \
-d '{"workspaceId":"04605210-c349-49ef-8c59-c1b986cddde3","rollUpId":"91729333-5e01-4fe3-9a87-f43048a660ba","value":150}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"rollUpId" : "91729333-5e01-4fe3-9a87-f43048a660ba",
"startTime" : "2021-01-15T00:00:00.000Z",
"endTime" : "2021-01-15T01:00:00.000Z",
"value" : 250.0,
"meta" : {
"ingress" : 10.0,
"egress" : 20.0,
"adjustments" : 250.0
}
}
This endpoint is used to adjust a roll-up’s current value. This adjustment will add to the existing value.
HTTP Request
POST /aggregations/rollup/{rollUpId}/value
Service Account
Create Service Account
api_key="38ed7729792c48489945c8060255fa45"
workspaceId="04605210-c349-49ef-8c59-c1b986cddde3"
curl "https://data-api.boulderai.com/integrations/serviceAccount?workspaceId=${workspaceId}" \
-d '{"workspace":"04605210-c349-49ef-8c59-c1b986cddde3","label":"My API Key","allowedOrigins":["https://platform.boulderai.com"],"isActive":true,"expiredAt":null}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"label" : "My API Key",
"apiKey" : "38ed7729792c48489945c8060255fa45",
"isActive" : true,
"allowedOrigins" : [
"https://platform.boulderai.com"
],
"createdAt" : "2021-01-15T00:00:00.000Z",
"lastUpdatedAt" : "2021-01-15T00:00:00.000Z",
"expiredAt" : null,
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"updatedBy" : null
}
This endpoint is used to create service accounts in a given workspace.
HTTP Request
POST /integrations/serviceAccount?workspaceId={workspaceId}
Query Parameters
Parameter | Required | Description | Example |
---|---|---|---|
workspaceId | true | The workspaceId which you want to query | 04605210-c349-49ef-8c59-c1b986cddde3 |
Get Service Accounts
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/integrations/serviceAccount" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"serviceAccounts" : [
{
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"label" : "My API Key",
"apiKey" : "38ed7729792c48489945c8060255fa45",
"isActive" : true,
"allowedOrigins" : [
"https://platform.boulderai.com"
],
"createdAt" : "2021-01-15T00:00:00.000Z",
"lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
"expiredAt" : null,
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}
]
}
This endpoint is used to retrieve all of the service accounts for a given workspace.
HTTP Request
GET /integrations/serviceAccount
Delete Service Account
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/integrations/serviceAccount/${serviceAccountKey}" \
-X DELETE \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"success" : true
}
This endpoint is used to delete a service account.
HTTP Request
DELETE /integrations/serviceAccount/{serviceAccountKey}
Update Service Account
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/integrations/serviceAccount/${serviceAccountKey}" \
-d '{"allowedOrigins":["https://google.com","https://amazon.com","https://microsoft.com"],"isActive":true,"expiredAt":"2021-01-15T04:00:00.000Z","label":"This is a new label."}' \
-X PATCH \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"label" : "This is a new label.",
"apiKey" : "38ed7729792c48489945c8060255fa45",
"isActive" : true,
"allowedOrigins" : [
"https://google.com",
"https://amazon.com",
"https://microsoft.com"
],
"createdAt" : "2021-01-15T00:00:00.000Z",
"lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
"expiredAt" : "2021-01-15T04:00:00.000Z",
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}
This endpoint is used to update a service account.
HTTP Request
PATCH /integrations/serviceAccount/{serviceAccountKey}
Alerts (Beta)
Alert Types
There are currently three different alert types are supported in the Sighthound platform:
- Device Down - Triggered when a device has not transmitted a status in more than 5 minutes.
- Device Restart - Triggered when a device is restarted. This is not necessarily a problem, unless a device is continuously restarting which could cause loss of data.
- Lack of Data - This is an alert that is triggered when a given device or stream has not transmitted an event in a configured period of time.
Create Alert Configuration
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/alerts/config" \
-d '{"workspaceId":"04605210-c349-49ef-8c59-c1b986cddde3","devices":["BAI_0000111"],"emails":["john.denver@boulderai.com"],"webhooks":null}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"id" : "b184dca3-e146-4453-9830-45bdad8ed410",
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"devices" : [
"BAI_0000111"
],
"emails" : [
"john.denver@boulderai.com"
],
"isActive" : true,
"createdAt" : "2021-01-15T00:00:00.000Z",
"lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}
Configure device alerts for a list of devices.
HTTP Request
POST /alerts/config
Get Alert Configurations
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/alerts/config/${workspaceId}" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"id" : "b184dca3-e146-4453-9830-45bdad8ed410",
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"devices" : [
"BAI_0000111"
],
"emails" : [
"john.denver@boulderai.com"
],
"isActive" : true,
"createdAt" : "2021-01-15T00:00:00.000Z",
"lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}
]
Get all of the alert configs for a specific workspace
HTTP Request
GET /alerts/config/{workspaceId}
Delete a configured alert from the system.
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/alerts/config/${alertConfigId}" \
-X DELETE \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"success" : true
}
Delete Alert Configuration
HTTP Request
DELETE /alerts/config/{alertConfigId}
Update Alert Configuration
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/alerts/config/${alertConfigId}" \
-d '{"devices":["BAI_0000111"],"emails":["john.denver@boulderai.com"],"isActive":true}' \
-X PATCH \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"id" : "b184dca3-e146-4453-9830-45bdad8ed410",
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"devices" : [
"BAI_0000111"
],
"emails" : [
"john.denver@boulderai.com"
],
"isActive" : true,
"createdAt" : "2021-01-15T00:00:00.000Z",
"lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
"createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
"updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}
Update a specific alert configuration
HTTP Request
PATCH /alerts/config/{alertConfigId}
Create Alert Specification
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/alerts/specification" \
-d '{"workspaceId":"04605210-c349-49ef-8c59-c1b986cddde3","alertType":"LackOfData","configuration":{"deviceId":"BAI_0000111","duration":"1 hour"}}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"id" : "77dab471-f5d1-4c85-92ad-e8d7a6981e48",
"workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
"alertType" : "LackOfData",
"configuration" : {
"deviceId" : "BAI_0000111",
"duration" : "1 hour"
}
}
Create an alert specification
HTTP Request
POST /alerts/specification
Device Status
Get Latest Status
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/device/${deviceId}/status/latest" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"deviceId" : "BAI_0000111",
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"localIp" : "68.9.240.254",
"externalIp" : "241.201.188.52",
"supervisorVersion" : "2.0.0",
"sshRunning" : "False",
"cpuUsage" : 50.0,
"gpuUsage" : 75.0,
"gpuTemp" : 37.5,
"uptime" : {
"days" : 10.0,
"hours" : 12.0,
"minutes" : 30.0,
"seconds" : 5.0
},
"mainMemoryStorage" : {
"totalSize" : 4.0,
"inUse" : 3.0,
"freeSpace" : 1.0,
"percentageUse" : 75.0
},
"dataMemoryStorage" : {
"totalSize" : 20.0,
"inUse" : 10.0,
"freeSpace" : 10.0,
"percentageUse" : 50.0
},
"networkStatus" : [
{
"interface" : "eth0",
"status" : "up",
"dataRate" : {
"daily" : {
"upload" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
},
"download" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
}
},
"monthly" : {
"upload" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
},
"download" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
}
}
}
}
],
"services" : [
{
"name" : "BAI_DataAcq_StandAlone_V4.0",
"status" : {
"bai_data_acq4" : "ADDED",
"status" : "ADDED"
}
}
],
"streams" : [
],
"buildInfo" : {
"assemblyVersion" : "0",
"buildEnvironment" : {
"basename" : "core-image-production",
"machine" : "dnncam-v1-imx334",
"l4tVersion" : "32.4.3",
"distroVersion" : "2.10.0",
"buildName" : "2.10.0-c3f4033-adam"
},
"assembly" : {
"lens_motor_driver_use_sincere_imx334" : false,
"node" : false,
"4G" : false,
"lens-resets-on-power-cycle" : false
}
},
"lastSeen" : "2021-01-15T04:00:00.000Z"
}
This endpoint is used to retrieve the latest for a specific device.
HTTP Request
GET /device/{deviceId}/status/latest
Query Device Status
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/device/status/query" \
-d '{"deviceId":"BAI_0000111","metrics":["cpuUsage","gpuUsage","gpuTemp"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","interval":"1 hour","order":"ASCENDING"}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
{
"data" : [
{
"windowStart" : "2021-01-15T00:00:00.000Z",
"metrics" : {
"cpuUsage" : 50.0,
"gpuUsage" : 50.0,
"gpuTemp" : 50.0
}
}
]
}
This endpoint is used to query device status over a specified period of time.
The following are possible values for metrics:
Metric | Description |
---|---|
gpuUsage | Percentage of GPU Usage. |
cpuUsage | Percentage of CPU Usage. |
gpuTemp | Temperature of the GPU, in Celsius. |
* | All possible metrics. |
HTTP Request
POST /device/status/query
Get Latest Status by Workspace
api_key="38ed7729792c48489945c8060255fa45"
curl "https://data-api.boulderai.com/workspace/${workspaceId}/devices/status" \
-X GET \
-H "X-API-KEY: $api_key"
The above command returns JSON structured like this:
[
{
"deviceId" : "BAI_0000111",
"workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
"localIp" : "68.9.240.254",
"externalIp" : "241.201.188.52",
"supervisorVersion" : "2.0.0",
"sshRunning" : "False",
"cpuUsage" : 50.0,
"gpuUsage" : 75.0,
"gpuTemp" : 37.5,
"uptime" : {
"days" : 10.0,
"hours" : 12.0,
"minutes" : 30.0,
"seconds" : 5.0
},
"mainMemoryStorage" : {
"totalSize" : 4.0,
"inUse" : 3.0,
"freeSpace" : 1.0,
"percentageUse" : 75.0
},
"dataMemoryStorage" : {
"totalSize" : 20.0,
"inUse" : 10.0,
"freeSpace" : 10.0,
"percentageUse" : 50.0
},
"networkStatus" : [
{
"interface" : "eth0",
"status" : "up",
"dataRate" : {
"daily" : {
"upload" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
},
"download" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
}
},
"monthly" : {
"upload" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
},
"download" : {
"bytes" : 10000,
"errors" : 0,
"dropped" : 0
}
}
}
}
],
"services" : [
{
"name" : "BAI_DataAcq_StandAlone_V4.0",
"status" : {
"bai_data_acq4" : "ADDED",
"status" : "ADDED"
}
}
],
"streams" : [
],
"buildInfo" : {
"assemblyVersion" : "0",
"buildEnvironment" : {
"basename" : "core-image-production",
"machine" : "dnncam-v1-imx334",
"l4tVersion" : "32.4.3",
"distroVersion" : "2.10.0",
"buildName" : "2.10.0-c3f4033-adam"
},
"assembly" : {
"lens_motor_driver_use_sincere_imx334" : false,
"node" : false,
"4G" : false,
"lens-resets-on-power-cycle" : false
}
},
"lastSeen" : "2021-01-15T04:00:00.000Z"
}
]
This endpoint is used to retrieve the latest for all devices in a given workspace.
HTTP Request
GET /workspace/{workspaceId}/devices/status