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
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 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 Violation policy within the requested time range	uint32
recent		An array of objects whose fields detail the recent distance violations by hour for the requested time range	[]DistanceViolationRollup
	interval	The rollup interval. Only HOURLY is available for now.	String
	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 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 Violations for the requested time range	[]DistanceViolationAggregation
	lat	The latitude of the location of the Distance Violation	double
	lng	The longitude of the location of the Distance Violation	double
	count	The amount of Distance Violations at this location	uint32
topViolatingBeacons		An array of objects detailing the amount of Distance Violations per each device for the requested time range, sorted by count, descending	[]DistanceViolationBeacon
	id	The device ID	String
	violationCount	The amount of Distance Violations	uint32
topViolatingAreas		An array of objects detailing the amount of Distance Violations per each location for the requested time range, sorted by count, descending	[]DistanceViolationLocation
	name	The location name	String
	id	The location ID	uint64
	violationCount	The amount of Distance 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	https://bluzone.io/portal/papis/dts/v1/api/deviceContactReport/{projectId}/{deviceId}
Response Content-Type	application/json
Header	bzid
Description	Get contact report for the specified device.

Parameters

Type	Name	Required	Description	Schema
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

Sample Response

{
  "violations": 6, //The number of Distance Tracking violations for this device
  "closeDevices": 2, //The number of unique devices that were associated with this device's Distance Trcking violations
  "recent": [
    //Each entry is an hourly report of the number Distance Tracking violations for this device
    {
      "interval": "HOURLY",
      "timestamp": "2020-07-17T12:00:00Z", //ISO8601 RFC3339Nano
      "violations": 1
    },
    {
      "interval": "HOURLY",
      "timestamp": "2020-07-17T11:00:00Z",
      "violations": 4
    },
    {
      "interval": "HOURLY",
      "timestamp": "2020-07-17T10:00:00Z",
      "violations": 1
    }
  ],
  "contacts": [
    //Each entry is a report of a Contact Event (either DISTANCE for Distance Violations or GEOFENCE for a shared geofence with another device at this time)
    {
      "deviceId": "8445671781542985407", //The Bluzone deviceId of the device associated with this contact event
      "deviceName": "My Device", //The name of the device in Bluzone
      "contactType": "DISTANCE", //Type of contact (DISTANCE or GEOFENCE)
      "locationName": "BluFi062", //The name of the Bluzone geofence
      "locationId": "125303", //The Bluzone locationId
      "floor": "1", //The configured floor value of the Bluzone location
      "lastContact": "2020-07-17T04:19:33.809Z", //Last contact time with the associated device (ISO8601)
      "durationMillis": 11873 //The total time of this contact event, in milliseconds
      "contactStart": "2020-07-17T04:19:21.936Z", //The start time of this contact event (ISO8601)
      "uuid": "d3a422b0-5db3-4189-62ed-45b6d858ecf1", //For DISTANCE events, the UUID of the close session. For GEOFENCE events, the UUID of the corresponding policy event
      "latitude": 15.139619643472987, //For DISTANCE events, the latitude of the last known RTLS location of the source beacon at the time this event was created
      "longitude": 57.13328996474993, //For DISTANCE events, the longitude of the last known RTLS location of the source beacon at the time this event was created
      "totalContactTime": 2097, //For DISTANCE events, the total accumulated close contact time across all sessions for the beacon and seen beacon, in seconds
      "backfill": true, //For DISTANCE events, whether or not this contact event happened outside of blufi coverage (offline)
    },
    {
      "deviceId": "17895940144574406572",
      "deviceName": "My Other Device", //The name of the device in Bluzone
      "contactType": "GEOFENCE",
      "locationName": "BluFi062",
      "locationId": "125303",
      "floor": "1",
      "lastContact": "2020-07-17T04:19:33.809Z",
      "durationMillis": 11873,
      "contactStart": "2020-07-17T04:19:21.936Z", //The start time of this geofence event (ISO8601)
      "uuid": "d3a422b0-5db3-4189-62ed-45b6d858ecf1", //For DISTANCE events, the UUID of the close session. For GEOFENCE events, the UUID of the corresponding policy event
      "latitude": 15.139619643472987, //The latitude of the last known RTLS location of the source beacon at the time this event was created
      "longitude": 57.13328996474993, //The longitude of the last known RTLS location of the source beacon at the time this event was created
      "geofenceId": 2, //The ID of the geofence in Bluzone
      "geofenceName": "My Geofence" //The Name of the geofence in Bluzone
    }
  ]
}

cURL Example

curl -X POST -H "BZID: ABCDEFGHJILKMNOP" -H "Content-Type: application/json" -d '{
	"start": "2020-06-29T22:08:18.095Z",
	"end": "2020-06-30T22:08:18.095Z"
}' "https://bluzone.io/portal/papis/dts/v1/api/deviceContactReport/111/14458689340104137112"

Distance Violation History

Method	POST
URL	https://bluzone.io/portal/papis/dts/v1/api/deviceContactReport/{projectId}/{locationId}
Response Content-Type	application/json
Header	bzid
Description	Get the distance violation history of a Bluzone location.

Parameters

Type	Name	Required	Description	Schema
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

Sample Response

{
  "locationId": "62", //Bluzone locationId
  "locationName": "Auto-generated", //Bluzone locationName
  "violations": 1101, //The number of Distance Tracking violations at the requested location during the requested period
  "uniqueDevices": 29, //The unique number of devices which had a Distance Tracking violation
  "recent": [
    //Each entry is an hourly report of the number Distance Tracking violations and unique number of devices for this location
    {
      "interval": "HOURLY",
      "timestamp": "2020-07-08T02:00:00Z",
      "violations": 3,
      "uniqueViolations": 3
    },
    {
      "interval": "HOURLY",
      "timestamp": "2020-07-08T00:00:00Z",
      "violations": 1,
      "uniqueViolations": 1
    },
    {
      "interval": "HOURLY",
      "timestamp": "2020-07-09T19:00:00Z",
      "violations": 2,
      "uniqueViolations": 2
    }
  ],
  "violationsMap": [
    //Each entry is a unique latitude/longitude tuple and the number of associated Distance Tracking violations at that location
    {
      "lat": 26.205577,
      "lng": -80.138385,
      "count": 470
    },
    {
      "lat": 26.205629,
      "lng": -80.138518,
      "count": 1
    }
  ],
  "devicesSummary": [
    //Each entry is a unique device id and the number of associated Distance Tracking packet violations for this device (i.e. the number of times a beaon reported it was too close to another beacon)
    {
      "deviceId": "200042",
      "violations": 1
    },
    {
      "deviceId": "200049",
      "violations": 1
    },
    {
      "deviceId": "200036",
      "violations": 53
    }
  ],
  "violationsResult": [
    //Each entry is a report of a Distance Violation event within the requested location
    {
      "totalDevices": 1, //The number of devices that were in violation with the reporting beacon
      "sourceDeviceId": "14744340248622994841", //The ID of the beacon the reported the violation
      "locationId": "14712", //The ID of the Bluzone location where the violation occured
      "locationName": "Austin Facility", //The name of the Bluzone location
      "floor": 1, //The floor of the Bluzone location
      "blufId": "106709", //The ID of the Blufi which reported the violation
      "blufiName": "BluFi015", //The name of the Blufi
      "durationMillis": "25115", //The total time of the violation
      "dateViolated": "2020-07-22T16:10:16Z", //The ISO8601 RFC339Nano Date of the violation
      "dateCleared": "2020-07-22T16:10:41Z" //The ISO8601 RFC339Nano Date of the clear, if applicable
    },
    {
      "totalDevices": 1,
      "sourceDeviceId": "9834777888017481246",
      "locationId": "14712",
      "locationName": "Austin Facility",
      "floor": 1,
      "blufId": "106738",
      "blufiName": "BluFi044",
      "durationMillis": "75373",
      "dateViolated": "2020-07-22T16:09:20Z",
      "dateCleared": "2020-07-22T16:10:35Z"
    },
    {
      "totalDevices": 1,
      "sourceDeviceId": "1376582239814772076",
      "locationId": "14712",
      "locationName": "Austin Facility",
      "floor": 1,
      "blufId": "106748",
      "blufiName": "BluFi054",
      "durationMillis": "72208",
      "dateViolated": "2020-07-22T15:49:10Z",
      "dateCleared": "2020-07-22T15:50:22Z"
    }
  ]
}

cURL Example

curl -X POST -H "BZID: ABCDEFGHIJKLNOP" -H "Content-Type: application/json" -d '{
	"start": "2020-06-20T14:26:26.462Z",
	"end": "2020-07-11T14:26:26.462Z"
}' "https://bluzone.io/portal/papis/dts/v1/api/distanceViolationHistory/111/62"

Distance Tracking APIs

Introduction

Distance Tracking Dashboard

Parameters

Response

Sample Response

cURL Example

Device Contact Report

Parameters

Sample Response

cURL Example

Distance Violation History

Parameters

Sample Response

cURL Example