Ingests data for a device and receives a shadow

post

https://tracking.hereapi.com/v3/

Devices can use this end point to ingest data into HERE Tracking.

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.

Also device owners use this end point to ingest data on behalf of a device.

The device can be either a real or a virtual device. A real device is identified by a trackingId assigned to it when the device was claimed. A virtual device is identified by an external device ID and the owner's project appId.

In case the ingestion is done by a device owner, the owner should first authenticate himself with HERE Tracking and obtain a user access token via the /users/v2/login endpoint. The user access token will then be used in this API call.

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
}]

appId

string

The user's project appId. Used together with an external ID to identify the virtual device.

string

length between 1 and 50

Tracking ID or application specific external ID, needed only if ingesting on behalf of another device.

data

array of objects

required

data*

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.