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 |
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 |
location | String | Combined latitude, longitude values | Yes |
timestamp | String | The ISO 8601 format of the timestamp of when the packet was received by the Cloud in UTC | Yes |
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": 6.642117096111178, "id": "10371225096882957496", "mac": "01:df:03:1b:ff:d3:2a", "latitude": 26.51778797917912, "location": "26.51778797917912, -80.07805554864944", "longitude": -80.07805554864944, "timestamp": 2015-07-06T20:03:33.909Z, "type": "location", "varianceX": 13.57224970823627, "varianceY": 13.511330222965865, "varianceZ": 0.0 }
Using The Service
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-service
- A project on the Bluzone Portal: https://bluzone.io
- The Web API Token from the project.
- The URL to the Location Stream endpoint: https://bluzone.io/portal/consumer/location