Send position

Service version: 1
Last edit: 2022.07.21

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
Request example
https://{baseURL}/locationHistory/{versionNumber}/history/positions?key={Your_API_Key}

curl command format

POST
Request curl command
1curl -XPOST "Content-type: application/json" -d
2'{
3   "type": "Feature",
4   "geometry": {
5     "type": "Point",
6     "coordinates": [
7       longitude,
8       latitude,
9       altitude
10     ]
11   },
12   "object": "object_uuid",
13   "timestamp": "YYYY-MM-DDThh:mm:ss"
14 }'
15'https://{baseURL}/locationHistory/{versionNumber}/history/positions?key={Your_API_Key}'

POST request body

POST
POST request body - JSON
1{
2  "type": "Feature",
3  "geometry": {
4    "type": "Point",
5    "coordinates": [
6      longitude,
7      latitude,
8      altitude
9    ]
10  },
11  "object": "object_uuid",
12  "timestamp": "YYYY-MM-DDThh:mm:ss"
13}

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 parametersDescription
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.

Request fields

Primary fields
FieldDescription
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
FieldDescription
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

CodeMeaning & possible causes
201Created
400Bad 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.
403Forbidden: No consent for storing historical data for the provided key.
404Not found: No such object.

Example

Send a position.

Request URL

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

POST request body

POST
POST request body - JSON
1{
2  "geometry": {
3    "type": "Point",
4    "coordinates": [
5      5.068704,
6      52.364897,
7      0.0
8    ]
9  },
10  "object": "cf6eae04-bd5e-4220-ae02-8151e1e8e34f"
11}