Distance Tracking APIs
- Joseph Wonesh (Unlicensed)
- Dennis Breland (Unlicensed)
Introduction
Bluzone exposes a REST API that provides a user with the Distance Tracking and Contact Tracing data of their applicable devices. The Distance Tracking data is provided by beacons that are configured to emit Distance Tracking packets, while the Contact Tracing data can be provided by these same beacons as well as by the geofence history of a specific beacon. The various APIs for obtaining this data are provided below.
Distance Tracking Dashboard
Method | POST |
|---|---|
URL | https://bluzone.io/portal/papis/dts/v1/api/dashboard/{projectId} |
Response Content-Type | application/json |
Header | bzid |
Description | Get the distance tracking dashboard view for your project. |
Parameters
Type | Name | Required | Description | Schema | Default |
|---|---|---|---|---|---|
Path | projectId | YES | The ID of the project, e.g. 111 | int | |
Body | start | YES | The start date of the desired time range, in ISO8601 RFC339Nano format | string |
|
Body | end | YES | The end date of the desired time range, in ISO8601 RFC339Nano format | string |
|
Response
Field Name | Nested Field Name | Description | Schema |
|---|---|---|---|
population |
| The number of unique beacons observed within the requested time range | uint32 |
compliant |
| The percentage of unique beacon without any Distance Tracking Violations within the requested time range | float |
violations |
| The number of Distance Tracking Violations observed within the requested time range | uint32 |
uniqueDevices |
| The number of unique devices that have violated a Distance Tracking Violation within the requested time range | uint32 |
recent |
| An array of objects whose fields detail the recent Distance Tracking Violations by hour for the requested time range | []DistanceViolationRollup |
| interval | The rollup interval. Only HOURLY is available for now. | enum { |
| timestamp | The timestamp of the rollup, formatted according to RFC3339 | String |
| population | The number of unique devices observed within this rollup | uint32 |
| violations | The number of Distance Tracking Violations within this rollup | uint32 |
| uniqueViolations | The number of unique devices which had at least one violation within this rollup | uint32 |
todaysViolations |
| An array of objects whose fields detail the location and corresponding count of Distance Tracking Violations for the requested time range | []DistanceViolationAggregation |
| lat | If RTLS is enabled for the project which the requested beacon belongs to, it is the latitude of the location of the last-known location at time of write. Otherwise, it is the latitude of the first Blufi to report this event at time of write. | double |
| lng | If RTLS is enabled for the project which the requested beacon belongs to, it is the longitude of the location of the last-known location at time of write. Otherwise, it is the longitude of the first Blufi to report this event at time of write. | double |
| count | The amount of Distance Tracking Violations at this location | uint32 |
topViolatingBeacons |
| An array of objects detailing the amount of Distance Tracking Violations per each device for the requested time range, sorted by count, descending | []DistanceViolationBeacon |
| id | The device ID | String |
| violationCount | The amount of Distance Tracking Violations | uint32 |
topViolatingAreas |
| An array of objects detailing the amount of Distance Tracking Violations per each location for the requested time range, sorted by count, descending | []DistanceViolationLocation |
| name | The location name | String |
| id | If RTLS is enabled for the project which the requested beacon belongs to, it is the ID of the location of the last-known location at time of write. Otherwise, it is the ID of the location of the first Blufi to report this event at time of write. | uint64 |
| violationCount | The amount of Distance Tracking Violations | uint32 |
Sample Response
{
"population": 46, //The number of unique devices observed by Bluzone
"compliant": 71.73913, //The percent of unique devices that do not have an associated Distance Tracking violation
"violations": 26, //The number of Distance Tracking violations observed
"uniqueDevices": 13, //The number of unique devices for which Bluzone observed a Distance Tracking violation
"recent": [
//Each entry is an hourly report of the observed population, violations, and unique devices with violations
{
"interval": "HOURLY",
"timestamp": "2020-07-16T18:00:00Z",
"population": 41,
"violations": 2,
"uniqueViolations": 2
},
{
"interval": "HOURLY",
"timestamp": "2020-07-16T19:00:00Z",
"population": 40,
"violations": 1,
"uniqueViolations": 1
},
{
"interval": "HOURLY",
"timestamp": "2020-07-17T17:00:00Z",
"population": 26,
"violations": 2,
"uniqueViolations": 2
}
],
"todaysViolations": [
//Each entry is a unique latitude/longitude tuple and the number of associated Distance Tracking violations at that location
{
"lat": 30.413098,
"lng": -97.666902,
"count": 1
},
{
"lat": 30.412875,
"lng": -97.666004,
"count": 1
},
{
"lat": 30.412972,
"lng": -97.666179,
"count": 1
}
],
"topViolatingBeacons": [
//Each entry is a unique device id and the number of associated Distance Tracking violations for this device
{
"id": "1376582239814772076",
"violationCount": 1
},
{
"id": "8195029735132899180",
"violationCount": 1
},
{
"id": "14147864550494974530",
"violationCount": 1
},
],
"topViolatingAreas": [
//Each entry is a unique Bluzone locationId, it's name, and the number of associated Distance Tracking violations for this location
{
"name": "My Location",
"locationId": "111",
"violationCount": 26
}
]
} |
cURL Example
curl -X POST -H "Content-Type: application/json" -H "BZID: ABCDEFGHJILKMNOP" -d '{
"start": "2020-05-10T14:26:26.462Z",
"end": "2020-06-10T14:26:26.462Z"
}' "https://bluzone.io/portal/papis/dts/v1/api/dashboard/111" |
Device Contact Report
Method | POST |
|---|---|
URL | |
Response Content-Type | application/json |
Header | bzid |
Description | Get contact report for the specified device. |
Parameters
Type | Name | Required | Description | Schema | Default |
|---|---|---|---|---|---|
Path | projectId | YES | The ID of the project, e.g. 111 | int | |
Path | deviceId | YES | The ID of the device, e.g. 14458689340104137112 | string |
|
Body | start | YES | The start date of the desired time range, in ISO8601 RFC339Nano format | string |
|
Body | end | YES | The end date of the desired time range, in ISO8601 RFC339Nano format | string |
|
Response
Field Name | Nested Field Name | Description | Schema |
|---|---|---|---|
violations |
| The number of Distance Tracking Violations for the requested device within the requested time range | uint32 |
closeDevices |
| The number of unique devices that were associated with the requested device for the requested time range | uint32 |
recent |
| An array of objects detailing an hourly report of the number of Distance Tracking Violations for the requested device for the requested time range | []DeviceContactReportRollup |
| interval | The rollup interval. Only HOURLY is available for now. | enum { |
| timestamp | The timestamp of the rollup, formatted according to RFC3339 | String |
| violations | The number of Distance Tracking Violations within this rollup | uint32 |
|
| An array of objects detailing the contact events for the requested device for the requested time range | []DeviceContactReportEvent |
| devceId | The device ID of the participating beacon (the “seen” beacon by the requested beacon) | String |
| contactType | The Contact Type of the event; either DISTANCE or GEOFENCE | enum { |
| locationName | The name of the location at which this contact event occurred at time of write. If this is a DISTANCE event: | String |
| locationId | The ID of the location at which this contact event occurred at time of write. If this is a DISTANCE event: | uint64 |
| floor | The floor number of the location at which this contact event occurred at time of write. | uint64 |
| lastContact | The timestamp of the last contact between the requested device and the participating device, formatted according to RFC3339 | String |
| durationMillis | The duration of this contact event, in milliseconds | uint64 |
| contactStart | The timestamp of the beginning of contact between the requested device and the participating device, formatted according to RFC3339 | String |
| uuid | The UUID of this contact event | String (UUID) |
| deviceName | The name of the participating device at time of write | String |
| geofenceId | If this is a GEOFENCE event, this is the geofence ID in which this event occurred. Otherwise, it is null. | uint64 |
| geofenceName | If this is a GEOFENCE event, this is the name of the geofence in which this event occurred. Otherwise, it is null. | String |
| latitude | If this is a DISTANCE event: If RTLS is enabled for the project which the requested beacon belongs to, it is the latitude of the last-known location at time of write. Otherwise, it is the latitude of the first Blufi to report this event at time of write. If this is a GEOFENCE event, this field is null. | double |
| longitude | If this is a DISTANCE event: If RTLS is enabled for the project which the requested beacon belongs to, it is the longitude of the last-known location at time of write. Otherwise, it is the latitude of the first Blufi to report this event at time of write. If this is a GEOFENCE event, this field is null. | double |
| totalContactTime | DEPRECATED, ignore | uint64 |
| backfill | If this is a DISTANCE event: This flag is set to true when this contact event for the requested device and participating device was received by Bluzone at least one minute after any previous contact event was received for the requested and participating devices. When this flag is true, the “offlineContactTimeSeconds” field is populated with the total accumulated contact time between the requested device and participating device while outside of Blufi coverage. If the requested device and participating device are still in contact within this same contact event when they return to Blufi coverage, the “offlineContactTime” field will continue to increase until this contact event ends. If this is a GEOFENCE event, this field is null. | boolean |
| offlineContactTimeSeconds | For DISTANCE events: This field is populated when the “backfill” flag is true, otherwise, it is null. This field is the total accumulated contact time between the requested device and participating device for this contact event while outside of Blufi coverage. If the requested device and participating device are still in contact within this same contact event when they return to Blufi coverage, this field will continue to increase until this contact event ends. | uint64 |
| reportingBlufiId | Unimplemented, reserved for future use | uint64 |
| reportingBlufiName | Unimplemented, reserved for future use | String |
| reportingBlufiLocationId | Unimplemented, reserved for future use | uint64 |
| reportingBlufiLocationName | Unimplemented, reserved for future use | String |
Sample Response
cURL Example
Distance Violation History
Method | POST |
|---|---|
URL | |
Response Content-Type | application/json |
Header | bzid |
Description | Get the distance violation history of a Bluzone location. |
Parameters
Type | Name | Required | Description | Schema | Default |
|---|---|---|---|---|---|
Path | projectId | YES | The ID of the project, e.g. 111 | int | |
Path | locationId | YES | The ID of the location, e.g. 1443 | int |
|
Body | start | YES | The start date of the desired time range, in ISO8601 RFC339Nano format | string |
|
Body | end | YES | The end date of the desired time range, in ISO8601 RFC339Nano format | string |
|
Response
Field Name | Nested Field Name | Description | Schema |
|---|---|---|---|
locationId |
| The location ID of the requested location | uint64 |
locationName |
| The name of the requested location | String |
violations |
| The number of Distance Tracking Violations for the requested location within the requested time range | uint32 |
uniqueDevices |
| The number of unique participating beacons across all of the Distance Tracking Violations for the requested location within the requested time range | uint32 |
recent |
| An array of objects whose fields detail the recent Distance Tracking Violations by hour for the requested location within the requested time range | []DistanceViolationHistoryRollup |
| interval | The rollup interval. Only HOURLY is available for now. | enum { |
| timestamp | The timestamp of the rollup, formatted according to RFC3339 | String |
| violations | The number of Distance Tracking Violations within this rollup | uint32 |
| uniqueViolations | The number of unique devices which had at least one violation within this rollup | uint32 |
violationsMap |
| An array of objects whose fields detail the location and corresponding count of Distance Tracking Violations for the requested location within the requested time range | []DistanceViolationHistoryLocation |
| lat | If RTLS is enabled for the project which the requested location belongs to, it is the latitude of the location of the last-known location at time of write. Otherwise, it is the latitude of the first Blufi to report this event at time of write. Note that only events belonging to the requested location ID are included. | double |
| lng | If RTLS is enabled for the project which the requested location belongs to, it is the longitude of the location of the last-known location at time of write. Otherwise, it is the longitude of the first Blufi to report this event at time of write. Note that only events belonging to the requested location ID are included. | double |
| count | The amount of Distance Tracking Violations at this location. Note that only events belonging to the requested location ID are included. | uint32 |
devicesSummary |
| An array of objects detailing the amount of Distance Tracking Violations for each device participating in a contact event for the requested location within the requested time range, sorted by count, descending | []DistanceViolationHistoryAggregation |
| id | The device ID | String |
| violationCount | The amount of Distance Tracking Violations | uint32 |
violationsResult |
| An array of objects detailing the Distance Tracking Violations for each device participating with the requested device within the requested time range | []DistanceViolationHistoryViolation |
| totalDevices | The number of unique devices participating in this Distance Tracking Violation | uint32 |
| sourceDeviceId | The ID of the device which triggered this Distance Tracking Violation | String |
| locationId | The ID of the location for this Distance Tracking Violation. This will always match the requested location ID | uint64 |
| locationName | The name of the location of this Distance Tracking Violation at time of write | String |
| floor | The floor number of the location of this Distance Tracking Violation at time of write | uint32 |
| blufiId | If RTLS is enabled for the project which the requested location belongs to, it is the ID of the blufi of the last-known location at time of write, if available (projects which don’t use the Best Blufi RTLS setting will not have a blufi ID in their last-known location information). Otherwise, it is the ID of the first Blufi to report this event at time of write. | uint64 |
| blufiName | If RTLS is enabled for the project which the requested location belongs to, it is the name of the blufi of the last-known location at time of write, if available (projects which don’t use the Best Blufi RTLS setting will not have a blufi name in their last-known location information). Otherwise, it is the name of the first Blufi to report this event at time of write. | String |
| durationMillis | The duration of this Distance Tracking Violation, in milliseconds | uint64 |
| dateViolated | The timestamp of the beginning of this Distance Tracking Violation, formatted according to RFC3339 | String |
| dateCleared | The timestamp of the end of this Distance Tracking Violation, formatted according to RFC3339 | String |