Location History

GetLocationHistory

Get location history for one, all, or a group of devices specified by tags parameter.

Notes:

Location history data expires after ~6 months (27 weeks)
The serviceType field is intentionally empty for location data before December 10th 2021

Basic Request for device history:

curl -G $API_HOST/v1/location/history -d "deviceId=$DEVICE_ID&start=2022-10-15T06:00:00.000Z&end=2022-10-16T18:30:00.000Z" -H "Authorization: Bearer $API_KEY"

Paginated Request:

export PAGE_NEXT_TOKEN=$(curl -G $API_HOST/v1/location/history -d "deviceId=$DEVICE_ID&start=2022-10-15T06:00:00.000Z&end=2022-10-16T18:30:00.000Z" -H "Authorization: Bearer $API_KEY" | jq .pageNextToken)

curl -G $API_HOST/v1/location/history -d "deviceId=$DEVICE_ID" --data-urlencode "pageNextToken=$PAGE_NEXT_TOKEN" -H "Authorization: Bearer $API_KEY"

Request all devices location history†:

curl -G $API_HOST/v1/location/history -H "Authorization: Bearer $API_KEY"

Request all devices last known location†:

curl -G $API_HOST/v1/location/history -d "latest=true" -H "Authorization: Bearer $API_KEY"

† Requires admin privileges

get/location/history

Query parameters

deviceIdstring

This is the canonical device id used in the device certificate, and as the MQTT client id.

Example:nrf-1234567890123456789000

This is the canonical device id that is an optional parameter. Specify a device id to get its location history. If a device id is not provided, location history for all devices are returned. You must have admin privileges to perform this operation.

latestboolean

Get the last known location for all devices or a single device (if deviceId is supplied). You must have admin privileges.

pageSort'asc' | 'desc'

Sorting order for the paginated results => desc (descending; default) or asc (ascending).

Example:desc

startstring date-time

HTML-encoded ISO-8601 date-time string denoting the start or end of a date range. If the string includes only a date, the time is the beginning of the day (00:00:00).

Example:2020-06-25T21:05:12.830Z

endstring date-time

HTML-encoded ISO-8601 date-time string denoting the start or end of a date range. If the string includes only a date, the time is the beginning of the day (00:00:00).

Example:2020-06-25T21:05:12.830Z

pageLimitinteger

Maximum number of items you want returned in the response (<=100).

pageNextTokenstring

If available in the initial response, use this token to retrieve the next page of items in the list. When supplying as a request parameter, use URL-encoding.

Example:4bb1f9ab35bd

deviceIdentifierstring

This is the canonical device id used in the device certificate, and as the MQTT client id.

Example:nrf-1234567890123456789000

inclusiveStartstring date-time

HTML-encoded ISO-8601 date-time string denoting the start or end of a date range. If the string includes only a date, the time is the beginning of the day (00:00:00).

Example:2020-06-25T21:05:12.830Z

inclusiveEndstring date-time

HTML-encoded ISO-8601 date-time string denoting the start or end of a date range. If the string includes only a date, the time is the beginning of the day (00:00:00).

Example:2020-06-25T21:05:12.830Z

tagsDeviceTag[]

If specified, only return location history for devices that have one of these Device Groups (tags). You must have admin privileges.

Response

Contains JSON response

totalinteger

Reflects the total results returned by the query, which may be less than the total number of items available. If the response contains a pageNextToken value, you can supply the pageNextToken in the next request to get more results. The maximum value of total is the page limit of the request, or ten pages if no page limit is provided.

pageNextTokenstring

Token used to retrieve the next page of items in the list. Present in a response only if the total available results exceeds the specified limit on a page. This token does not change between requests. When supplying as a request parameter, use URL-encoding.

Example response

{
  "items": [
    {
      "id": "bc631093-7f7c-4c1b-aa63-a68c759bcd5c",
      "deviceId": "nrf-1234567890123456789000",
      "insertedAt": "2020-06-25T21:05:12.830Z",
      "recordedAt": "2020-06-25T21:05:12.830Z",
      "lat": "45.524098",
      "lon": "-122.688408",
      "meta": {
        "acc": 233.44,
        "spd": 11.22,
        "hdg": 76.8,
        "alt": 12
      },
      "uncertainty": "934"
    }
  ],
  "total": 10,
  "pageNextToken": "4bb1f9ab35bd"
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.