Location APIs

Owned by Robert Dare
Last updated: Apr 01, 2020 by Sebastian Restrepo (Unlicensed)
8 min read

Introduction

Bluzone exposes a REST API that exposes the current location of the Beacon.  Bluzone Location Engine will render a new Beacon location at a period defined in your Project's RTLS Settings.  The location response will include a Latitude and Longitude value.  If your RTLS Engine Algorithm is set to "Best Blufi", then the LAT/LON values returned are the same as the Blufi identified as "Best Blufi".

Beacon Last Known Location

MethodGET
URL
https://bluzone.io/portal/papis/v1/search/locations/map/{projectId}/{beaconId}
Response Content-Typeapplication/json
Headerbzid
DescriptionGet the last known location for a single beacon

Parameters

TypeNameRequiredDescriptionSchemaDefault
PathprojectIdYESThe ID of the project, e.g. 111int
PathbeaconIdYESThe ID of the beacon, e.g. 111string
QuerythresholdMinutesNOHow far back in time to look, in minutesint5

Sample Response

Location Response
{
    "BLUZONE": {
        "altitude": 194.15300031378865,
        "beaconId": "<BEACON_ID>",
        "blufiPeriodStats": [
            {
                "blufiId": "REDACTED_BLUFI_DEVICE_ID",
                "meterToLocation": null,
                "name": "Blufi Behind Mikes Desk",
                "rssiAverage": -71.61700820922852,
                "rssiCount": 2,
                "sid64": "4061058898803384480",
                "blufiInsertMillis": 1550690229044,
                "rssiHistorical": null,
                "minTimestamp": 25703544832,
                "maxTimestamp": 25703545839,
                "enhanceDropped": null,
                "globalThresholdViolated": null,
                "minimumSampleCountViolated": null,
                "remainingInBucket": null,
                "newInBucket": 2,
                "behindTrigger": -25703545839,
                "averageLatencyMillis": null,
                "maxLatencyMillis": null
            },
            {
                "blufiId": "REDACTED_BLUFI_DEVICE_ID",
                "meterToLocation": null,
                "name": "Blufi Rick's Desk area",
                "rssiAverage": -72.7808952331543,
                "rssiCount": 2,
                "sid64": "600881077478007212",
                "blufiInsertMillis": 1550690229044,
                "rssiHistorical": null,
                "minTimestamp": 25703544832,
                "maxTimestamp": 25703545839,
                "enhanceDropped": null,
                "globalThresholdViolated": null,
                "minimumSampleCountViolated": null,
                "remainingInBucket": null,
                "newInBucket": 2,
                "behindTrigger": -25703545839,
                "averageLatencyMillis": null,
                "maxLatencyMillis": null
            },
            {
                "blufiId": "REDACTED_BLUFI_DEVICE_ID",
                "meterToLocation": null,
                "name": "Training room back outside wall",
                "rssiAverage": -77.3737907409668,
                "rssiCount": 2,
                "sid64": "12507011242568423825",
                "blufiInsertMillis": 1550690229044,
                "rssiHistorical": null,
                "minTimestamp": 25703544832,
                "maxTimestamp": 25703545839,
                "enhanceDropped": null,
                "globalThresholdViolated": null,
                "minimumSampleCountViolated": null,
                "remainingInBucket": null,
                "newInBucket": 2,
                "behindTrigger": -25703545839,
                "averageLatencyMillis": null,
                "maxLatencyMillis": null
            }
        ],
        "boundaryCorrected": null,
        "boundaryExclusionCorrected": null,
        "deviceName": "Beacon - John Doe",
        "direction": null,
        "displayRadius": 1.5767331526708015,
        "error": "OK",
        "errorDescription": null,
        "fingerprintEstimate": null,
        "fingerprintLocations": [],
        "floorNumber": 1,
        "generatorType": "BLUZONE",
        "geoJsonMap": null,
        "intersectionGroup": [],
        "latitude": 32.95644162009803,
        "longitude": -96.70910070111486,
        "mac": "01:e7:d6:70:b1:83:48",
        "meterChangeEstimate": 0.49330667230736464,
        "motionStatic": null,
        "projectId": REDACTED_PROJECT_ID,
        "thresholdCorrected": null,
        "timestamp": 1550690182364,
        "type": "location",
        "varianceX": 1.1049277487694245,
        "varianceY": 1.0627229400558122,
        "varianceZ": null,
        "windowCalculationRange": 4000,
        "locationId": REDACTED_LOCATION_ID,
        "cellId": -8769600164440266311,
        "battery": null,
        "gt": null,
        "jobModeBlufis": [],
        "averageSourceDelayMillis": 5987,
        "sunstoneDelayMillis": 2815,
        "windowCount": 26,
        "maxTimestamp": 1550690227150
    }
}

cURL Example

Bash Example
curl -X GET \
  https://bluzone.io/portal/papis/v1/search/locations/map/{PROJECT_ID}/{BEACON_ID} \
  -H 'bzid: <API_TOKEN>'

Available Beacons With Location History

MethodPOST
URL
https://bluzone.io/portal/papis/v1/search/locations/history/beacons/{projectId}/available
Response Content-Typeapplication/json
Header

bzid

DescriptionGet a list of beacons that have location history data, for a given location, within a range of time. NOTE: contact Bluzone admin to enable location history

Parameters

TypeNameRequiredDescriptionSchemaDefault
PathprojectIdYESThe ID of the project, e.g. 111int
BodylocationIdYESThe ID of the location, e.g. 111int
BodyendTimeNO

The end time of the range, in milliseconds. Currently, this field is not honored and always uses the default value

intnow (current time)
BodystartTimeYESThe start time of the range, in milliseconds.int

Sample Response

Available Beacon Sample Response
[
    {
        "deviceId": "<BEACON_ID>",
        "name": "Beacon 1"
    },
    {
        "deviceId": "<BEACON_ID>",
        "name": "Beacon 2"
    }
]

cURL Example

Available Beacon Example cURL
curl --location --request POST 'https://bluzone.io/portal/papis/v1/search/locations/history/beacons/{PROJECT_ID}/available' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'bzid: <API_TOKEN>' \
--data-raw '{"locationId":<LOCATION_ID>,"startTime":1585752643840}'

Beacons Location History Heatmap

MethodPOST
URL
https://bluzone.io/portal/papis/v1/gateway/bezel/v1/api/projects/{projectId}/beacon/heatmap
Response Content-Typeapplication/json
Header

bzid

DescriptionGet heatmap data for a set of beacons at single location. NOTE: contact Bluzone admin to enable location history

Parameters

TypeNameRequiredDescriptionSchemaDefault
PathprojectIdYESThe ID of the project, e.g. 111int
BodylocationIdYESThe ID of the location, e.g. 111int
BodyendTimeYES

The end time of the range, in milliseconds. Currently, this field is not honored and always uses the default value

int
BodystartTimeYESThe start time of the range, in milliseconds.int
BodybeaconIdsYESA list of beacon ids, e.g. ["1234",  "5432"]String array

Sample Response

Available Beacon Sample Response
{
    "response": [
        {
            "beaconId": "<BEACON_ID>",
            "coordinates": [
                {
                    "Latitude": 26.013184,
                    "Longitude": -80.14389,
                    "count": 195
                }
            ],
            "locationId": <LOCATION_ID>,
            "projectId": <PROJECT_ID>
        }
    ]
}

cURL Example

Available Beacon Example cURL
curl --location --request POST 'https://bluzone.io/portal/papis/v1/gateway/bezel/v1/api/projects/{PROJECT_ID}/beacon/heatmap' \
--header 'Content-Type: application/json' \
--header 'bzid: <API_TOKEN>' \
--data-raw '{"beaconIds":["<BEACON_ID>"],"locationId":<LOCATION_ID>,"startTime":1585755310951,"endTime":1585758910951}'