Send position
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" -d2'{3 "type": "Feature",4 "geometry": {5 "type": "Point",6 "coordinates": [7 longitude,8 latitude,9 altitude10 ]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 altitude9 ]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 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 . |
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:
|
403 | Forbidden: No consent for storing historical data for the provided key. |
404 | Not 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.08 ]9 },10 "object": "cf6eae04-bd5e-4220-ae02-8151e1e8e34f"11}