TomTom LogoDocs
Products
Resources
Pricing
Sign in
Location History API

Send position

Service version: 1Last edit: 2022.08.31

Decommission notice

December 16, 2025

  • This service will be decommissioned on January 31, 2027.
  • All endpoints will be withdrawn following a 12 months deprecation period.
  • There is no recommended migration path.

Important note

Before a customer can use the Location History API Send position endpoint they must give consent for the storing of historical positions. Use the Set new settings values endpoint in the Configuration service to do this. Consent for storing historical positions can be revoked at any time.

Purpose

This endpoint is used to send the position of the Object.

Request data

HTTPS method: POST

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL format

post
URL request format
https://{baseURL}/locationHistory/{versionNumber}/history/positions?key={Your_API_Key}

curl command request format

post
curl command request format
curl -XPOST "Content-type: application/json" -d
'{
   "type": "Feature",
   "geometry": {
     "type": "Point",
     "coordinates": [
       longitude,
       latitude,
       altitude
     ]
   },
   "object": "object_uuid",
   "timestamp": "YYYY-MM-DDThh:mm:ss"
 }'
'https://{baseURL}/locationHistory/{versionNumber}/history/positions?key={Your_API_Key}'

POST request body

post
POST request body - JSON
{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      longitude,
      latitude,
      altitude
    ]
  },
  "object": "object_uuid",
  "timestamp": "YYYY-MM-DDThh:mm:ss"
}

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.

Note: There are no optional parameters in this endpoint.

Required parameters

Description

baseURL


string

The base URL for calling the API.


Value: api.tomtom.com

versionNumber


string

Service version.


Value: 1

key


string

An API Key valid for the requested service.


Value: Your valid API Key.

POST body request fields

Primary fields

Field

Description

type


string

In the current version this is always “Feature”.

geometry


object

GeoJSON Point

object


UUID

The UUID of an object for which a position will be saved.

timestamp


string

The date and time of the position being recorded by the user.


Default value: The request server time.
Value: ISO 8601 format timestamp (YYYY-MM-DDThh:mm:ss)

geometry object

Field

Description

type


string

Type of geometry. In the current version this is always “Point”.

coordinates


array (double)

Coordinates of the point in the form of an array containing (in this order): longitude, latitude, altitude. Altitude is optional.

Response data

Response body

The response body is empty.

Response codes

Code

Meaning & possible causes

201

Created

400

Bad request :

  • Wrong datetime format.
  • The timestamp is later than the current date.

  • The timestamp is earlier than or equal to the timestamp of the last position.

403

Forbidden : No consent for storing historical data for the provided key.

404

Not found : No such object.

Example

Send a position.

POST request example

post
POST request example
https://api.tomtom.com/locationHistory/1/history/positions?key={Your_API_Key}

POST request body example

post
POST request body - JSON
{
  "geometry": {
    "type": "Point",
    "coordinates": [5.068704, 52.364897, 0.0]
  },
  "object": "cf6eae04-bd5e-4220-ae02-8151e1e8e34f"
}