--- name: cumulocity-track-location description: "Read and set the current position of a device, record location updates, query the movement of the device in a time range, and delete a location update. Use when the user wants to read, set, or track the position of a device." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Track the location of a device Source: https://cumulocity.com/docs/skills/device-management/track-location/ Sector: Skills, Device management & connectivity Release: Latest Description: Read and set the current position of a device, record location updates, query the movement of the device in a time range, and delete a location update. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) Cumulocity stores the location of a device in two places: * The current position is the `c8y_Position` fragment in the managed object of the device. * The movement history is a series of events of type `c8y_LocationUpdate`. Each event has its own `c8y_Position` fragment with the position at the time of the event. The `c8y_Position` fragment has the following properties: * `lat`: The latitude in degrees. Mandatory. * `lng`: The longitude in degrees. Mandatory. * `alt`: The altitude in meters. Optional. In the Device Management application, the **Location** tab shows the current position, and the **Tracking** tab shows the movement, see [Location](https://cumulocity.com/docs/device-management-application/viewing-device-details/#location) and [Tracking](https://cumulocity.com/docs/device-management-application/viewing-device-details/#tracking). For the device side, see [Tracking](https://cumulocity.com/docs/device-integration/fragment-library/#tracking) in the fragment library. > **Requirements:** > ROLES & PERMISSIONS: > > * To read the current position: ROLE_INVENTORY_READ > * To set the current position: ROLE_INVENTORY_ADMIN > * To record and delete location updates: ROLE_EVENT_ADMIN > * To read location updates: ROLE_EVENT_READ The examples use `` for the ID of the device, and `` and `` for the start and the end of a time range. Write times in ISO 8601 format with a time zone, for example `2026-09-01T08:30:00.000Z`. In a query string, encode `+` as `%2B`. ### To read the current position {#to-read-the-current-position} Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request: ```http GET /inventory/managedObjects/ ``` The platform returns HTTP 200 and the managed object. The fragment `c8y_Position` contains the current position. If the fragment is missing, the device has no position yet. ### To set the current position {#to-set-the-current-position} Send an [Update a specific managed object](https://cumulocity.com/api/core/#operation/putManagedObjectResource) request: ```http PUT /inventory/managedObjects/ Content-Type: application/json Accept: application/json { "c8y_Position": { "lat": 51.151977, "lng": 6.95173, "alt": 67 } } ``` Send the values as numbers. Leave out `alt` if you do not know the altitude. The update is partial: the platform changes only `c8y_Position` and keeps all other fragments of the device. The platform returns HTTP 200 and the managed object with the new `c8y_Position`. To remove the position, send `"c8y_Position": null` in the same request. ### To record a location update {#to-record-a-location-update} Send a [Create an event](https://cumulocity.com/api/core/#operation/postEventCollectionResource) request: ```http POST /event/events Content-Type: application/json Accept: application/json { "source": { "id": "" }, "type": "c8y_LocationUpdate", "text": "Location updated", "time": "2026-09-01T08:30:00.000Z", "c8y_Position": { "lat": 51.151977, "lng": 6.95173, "alt": 67 } } ``` The properties `source`, `type`, `text`, and `time` are mandatory. `time` is the time of the position. The platform returns HTTP 201 and the event with its `id`. If it returns HTTP 422, one of the mandatory properties is missing or invalid. The current position and the location updates are separate. If the event has the latest position of the device, also set the current position, see [To set the current position](https://cumulocity.com/docs/skills/device-management/track-location/#to-set-the-current-position). ### To query the movement of a device {#to-query-the-movement-of-a-device} Send a [Retrieve all events](https://cumulocity.com/api/core/#operation/getEventCollectionResource) request: ```http GET /event/events?source=&type=c8y_LocationUpdate&dateFrom=&dateTo=&pageSize=200 ``` `dateFrom` is inclusive, and `dateTo` is exclusive. The platform returns HTTP 200 and the location updates in the `events` array, the newest first. Add `revert=true` to get the oldest first. The `c8y_Position` of each event is one point of the movement. To read the next page, follow the `next` link of the response. If the `events` array is empty, the device recorded no location updates in this time range. ### To delete a location update {#to-delete-a-location-update} Send a [Remove a specific event](https://cumulocity.com/api/core/#operation/deleteEventResource) request with the `id` of the event as ``: ```http DELETE /event/events/ ``` The platform returns HTTP 204. If it returns HTTP 404, the event does not exist. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [GET /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/getManagedObjectResource): Retrieve a specific managed object - [PUT /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/putManagedObjectResource): Update a specific managed object - [POST /event/events](https://cumulocity.com/api/core/#operation/postEventCollectionResource): Create an event - [GET /event/events](https://cumulocity.com/api/core/#operation/getEventCollectionResource): Retrieve all events - [DELETE /event/events/{id}](https://cumulocity.com/api/core/#operation/deleteEventResource): Remove a specific event ## Linked from the documentation - [Fragment library > Tracking](https://cumulocity.com/docs/device-integration/fragment-library/#tracking) - [Viewing device details](https://cumulocity.com/docs/device-management-application/viewing-device-details/)