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 OK - there is no error ErrData - there is an error with the quality of data resulting in no new location	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

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-service~~
~~A project on the Bluzone Portal: https://bluzone.io~~
~~The Web API Token from the project.~~
~~The URL to the Location Stream endpoint: wss://bluzone.io/portal/consumer/location~~

Public Developer Portal

Location Stream API v1