Ingests data and receives a shadow

post

https://tracking.hereapi.com/v2/

Devices can use this end point to ingest data into HERE Tracking, in the same way as via the /v3 endpoint.

A device uses its access token obtained via the the /v2/token endpoint to send telemetry – GPS position, sensor readings, WLAN or Bluetooth scans - to HERE Tracking.

By default the request is synchronous and the response will be the device desired shadow. If the request is set to be asynchronous, the response will be empty.

The device position gets resolved based on the position and scan objects provided in the request body (see the objects definitions for details). If only position is provided, it will be used as the device position. If only scan is provided, the position will be resolved asynchronously via the HERE Positioning API after returning a response. If both are provided, scan is resolved to a position via the HERE Positioning API, and the better of the two positions (provided vs. resolved) will be selected. If neither position nor scan is provided, or if the HERE Positioning API is not able to resolve the position, the device position will be left empty.

The reported shadow will be updated with the device latest position information, sensor readings and settings ingested by the device. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in the system.computed property of the shadow. The device shadow can be queried via the shadows/v2/{trackingId} endpoint.

The data ingested by the device will be available as a device trace via the traces/v2/{trackingId} endpoint.

Query Params

async

boolean

Defaults to false

If set to true, ingests the device data and responds immediately with an empty response body.

Body Params

A device telemetry data.

The timestamp specifies the time in milliseconds at which the device telemetry measurements were taken. This must be within 10 seconds of the timestamp returned by the /v2/timestamp endpoint.

Example of a GSM telemetry

[{
    "scan": {
        "gsm": [{
            "mcc": 262,
            "mnc": 1,
            "lac": 5126,
            "cid": 16504,
            "nmr": [
                { "bsic": 6, "bcch": 82 },
                { "bsic": 7, "bcch": 85 },
                { "bsic": 12, "bcch": 93 },
                { "bsic": 13, "bcch": 88 },
                { "bsic": 19, "bcch": 88 }
            ]
        }]
    },
    "payload": {
        "sensor": "data"
    },
    "timestamp": 1515169948976
}]

Example of a WLAN telemetry

[{
    "scan": {
        "wlan": [
            { "mac": "1c:1d:86:07:01:0f", "powrx": -45 },
            { "mac": "e4:f4:c6:d9:85:59", "powrx": -39 },
            { "mac": "1c:1d:86:07:01:0d", "powrx": -43 },
            { "mac": "1c:1d:86:07:01:0b", "powrx": -44 },
            { "mac": "1c:1d:86:07:01:04", "powrx": -58 },
            { "mac": "1c:1d:86:07:01:03", "powrx": -59 }
        ]
    },
    "payload": {
        "sensor": "data"
    },
    "timestamp": 1515169948976
}]

Headers

X-Request-Id

uuid

ID used for correlating requests within HERE Tracking. Used for logging and error reporting.

Must be a valid UUIDv4.

authorization

string

required

Responses

204

Successful (no content).

The device data was ingested successfully and the response is empty. This response is returned if the async query parameter was set to true.

Example of a GSM telemetry

Example of a WLAN telemetry

200Successful The device data was ingested and processed successfully and the desired shadow was returned. This response is returned if the async query parameter was not set to true.

400Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body.

401Unauthorized The request did not provide correct authentication details

403Forbidden The account does not have the correct privileges

404Not Found The specified resource was not found

413Payload Too Large The request size exceeds the maximum size limit for payloads.

429Too Many Requests User has sent too many requests in a given amount of time.