---
title: "GetLocationHistory"
method: GET
path: "/location/history"
tags: ["Location History"]
---

# GetLocationHistory

`GET /location/history`

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__:
```sh
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__:
```sh
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__†:
```sh
curl -G $API_HOST/v1/location/history -H "Authorization: Bearer $API_KEY"
```

__Request all devices last known location__†:
```sh
curl -G $API_HOST/v1/location/history -d "latest=true" -H "Authorization: Bearer $API_KEY"
```

† Requires admin privileges

## Query parameters

- `deviceId` string — This is the canonical device id used in the device certificate, and as the MQTT client id.
- `latest` boolean
- `pageSort` 'asc' | 'desc' — Sorting order for the paginated results => desc (descending; default) or asc (ascending).
- `start` string, 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).
- `end` string, 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).
- `pageLimit` integer — Maximum number of items you want returned in the response (<=100).
- `pageNextToken` string — 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.
- `deviceIdentifier` string — This is the canonical device id used in the device certificate, and as the MQTT client id.
- `inclusiveStart` string, 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).
- `inclusiveEnd` string, 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).
- `tags` DeviceTag[]

## Response `200`

Contains JSON response

- PaginatedResultLocationTrackerItem
  - `items` LocationTrackerItem[], required
    - `id` string, required — Universally unique identifier
    - `deviceId` string, required — This is the canonical device id used in the device certificate, and as the MQTT client id.
    - `serviceType` 'GNSS' | 'GPS' | 'MCELL' | 'MCELL_EVAL' | 'SCELL' | 'SCELL_EVAL' | 'WIFI' | 'WIFI_EVAL', required — This is the service used to obtain the location of a device. GNSS location is derived on the device and reported back to the cloud. 'GPS' type has been deprecated, but will still return for older records. The '_EVAL' suffixed types are no longer produced, but still appear in records created while evaluation tokens existed.
    - `insertedAt` string, date-time, required — 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).
    - `recordedAt` string, 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).
    - `lat` string, required — GPS latitude.
    - `lon` string, required — GPS Longitude.
    - `meta` GnssMeta, required — Metadata sent from device when reporting GNSS location in PVT format. Can include other non-gnss related key/value pairs for easy retrieval later. Only populated for GNSS PVT formatted fixes, empty object otherwise.
      - `acc` number, double, required — Accuracy in (2D 1-sigma) in meters.
      - `alt` number, double, required — Altitude above WGS 84 ellipsoid in meters.
      - `spd` number, double, required — Horizontal speed in meters per second.
      - `hdg` number, double, required — Heading of movement in degrees.
    - `uncertainty` string, required — Radius of the uncertainty circle around the location in meters. Also known as Horizontal Positioning Error (HPE).
  - `total` integer — 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.
  - `pageNextToken` string — 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.

---

[API](https://skmtc.dev/nrfcloud/apis/nrf-cloud-rest-api.md) · [All operations](https://skmtc.dev/nrfcloud/apis/nrf-cloud-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nrfcloud/nrf-cloud-rest-api/revisions/c4e56e458ebf/schema)