Location Stream API v1
- Robert Dare
- robfreund (Unlicensed)
- Editor (Unlicensed)
- Joseph Wonesh (Unlicensed)
Introduction
This document describes the format of the JSON data returned from the Location Stream Service API, including the details of each field. It is assumed that the reader is familiar with developing systems that connect to web socket streaming apis and processing JSON messages.
Overview
The Location Stream API exposes raw JSON messages that are derived the Bluvision Cloud through the indoor location services algorithms. The Indoor Location Services uses beacon data captured by the Bluzone Cloud to derive the location of a bluetooth device. That data is rendered in near real-time and can be accessed in its raw form through the Location Stream API. The Bluzone Cloud exposes this streaming API and additional REST APIs to enable consumers to plot movement of the device on a map in near real-time.
Anatomy of a Packet
Messages in the Streaming API are "flattened" for easier processing. Consumers of the location stream should check the "type" first as these may change in a future release.
| Property Name | Value Type | Description | Always Present |
|---|---|---|---|
| type | String | Defines packet type (e.g.: location) | Yes |
| projectId | Number | The project identifier this location was generated for | Yes |
| id | String | The unique identifier for the device (beacon) being tracked | Yes |
| mac | String | The mac address of the device being tracked | Yes |
| locationId | Number | The locationId of the Bluzone location this was generated for | Yes |
| floorNumber | Number | The floor number this location is determined to be on. | Yes |
| deviceName | String | The name of the device | Yes |
| latitude | Number | Latitude value (example: 25.774489) | Yes |
| longitude | Number | Longitude value (example: -80.195160) | Yes |
| altitude | Number | Altitude value in (tbd) | Yes |
| varianceX | Number | The uncertainty in square meters of the X axis | Yes |
| varianceY | Number | The uncertainty in square meters of the Y axis | Yes |
| varianceZ | Number | The uncertainty in square meters of the Z axis. | Yes |
| variance | Number | The uncertainty distance of the location. Example.. Use this for map display of variance circle. | Yes |
| location | String | Combined latitude, longitude values | Yes |
| battery | Number | The battery level of from the latest scan data. If we have not received a battery yet sample the value will be zero. | Yes |
| timestamp | String | The ISO 8601 format of the timestamp of when the packet output from the Cloud in UTC | Yes |
| calculatedTimestamp | String | The ISO 8601 format of the first packet received at server used to produce location | Yes |
| maxTimestamp | String | The ISO 8601 format of the last packet received at server used to produce location | Yes |
| windowCount | Number | The number of packets included in the location calculation | Yes |
| error | String | The error code output from processing new locations
| No |
| errorDescription | String | The free text error description used to further describe the error | No |
Understanding Error
The error field can be inspected to understand if an error case has happened. Currently the ErrData will be output when we cannot process a location for a data reason. When an ErrData is output the last known location will also be output. New locations will not be output after ErrData until the data quality has changed such that a new location can now be calculated.
Example Packets
Note: Properties not supported by the example packet type are omitted. Fields defined above as "Always Present" should never be null, other fields may be null.
Sample Location Packet
{
"altitude": 2.3687698831781745,
"battery": 3630,
"calculatedTimestamp": "2017-12-15T17:06:13.793Z",
"maxTimestamp": "2017-12-15T17:06:16.793Z",
"windowCount": 10,
"deviceName": "bvTiTag",
"locationId": 1,
"floorNumber": 1,
"id": "6253758190942573046",
"latitude": 26.205612363949143,
"location": "26.205612,-80.138235",
"longitude": -80.13823502660985,
"mac": "01:fa:b5:26:24:cf:b2",
"projectId": 8,
"timestamp": "2017-12-15T17:06:16.555687791Z",
"type": "location",
"variance": 0,
"varianceX": 0,
"varianceY": 0,
"varianceZ": 0,
"error":"OK",
"errorDescription":""
}
Using The Service
Note: Support for WebSocket connections to Bluzone has been deprecated. Please use the RemoteConsumer service and bring your own Kinesis or EventHub stream to consume this data. See Data Stream Integrations
The following section assumes familiarity with working with WebSockets. Bluvision has made a sample client available on Github (https://github.com/bluzone/consumer-service). The sample client will connect to a WebSocket at the provided URL and dump contents to the console.
Prerequisites
WebSocket Client: A reference implementation can be found here: https://github.com/bluzone/consumer-serviceA project on the Bluzone Portal: https://bluzone.ioThe Web API Token from the project.The URL to the Location Stream endpoint: wss://bluzone.io/portal/consumer/location