Get objects position history
Service version: 1
Last edit: 2019.10.03
On this page
- ▸ Purpose
- ▸ Request data
Purpose
This endpoint obtains a list of history positions of the user's objects. Each position contains information about estimated speed and direction.
If consent is given, the Geofencing API can also provide locations that will be available through this endpoint.
Request data
HTTPS method: GET
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in plain text.
https://baseURL/locationHistory/versionNumber/history/positions/objectId?key=Your_API_Key&from=timestamp[&to=timestamp][&maxResults=integer][&pageNumber=integer]
curl command
curl 'https://baseURL/locationHistory/versionNumber/history/positions/objectId?key=Your_API_Key&from=timestamp[&to=timestamp]'
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.
- If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
- The order of request parameters is not important.
- The maximum allowed time between provided timestamps is 24h.
Required parameters | |
---|---|
Parameter | 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 .
|
objectId string |
Object UUID for which history is requested. Value: Requested object's UUID .
|
adminKey string |
An Admin Key valid for the provided API Key. Value: Your valid Admin Key .
|
from timestamp |
Beginning date for the listing. Value: ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss). |
Optional parameters | |
[to] timestamp |
End date for the listing. Value: ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss). |
[maxResult] integer |
Maximum number of items returned in the response. Value: Greater than zero, less than or equal to 100. Default: 100 |
[pageNumber] integer |
The number of items on the page to be returned in the response. The maximum number of elements on the page is equal to the maxResult value. Value: Greater than zero. Default: 1 |
Response data
Response body
{
"summary": {
"name": "object_name",
"id": "object_id",
"from": "beginning_timestamp",
"to": "end_timestamp"
},
"positions": {
"type": "FeatureCollection",
"features": [
{
"timestamp": "timestamp",
"userTimestamp": "timestamp",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
longitude,
latitude,
altitude
]
},
"estimatedSpeed": speed_value,
"estimatedDirection": azimuth
}
]
},
"resultInfo": {
"maxResults": max_number_of_results,
"pageNumber": page_number,
"itemsCount": number_of_results
}
}
Response fields
The following table describes all of the fields that can appear in a response.
Primary fields | |
---|---|
Field | Description |
summary{} object |
Contains information about the object's history positions request. |
positions{} object |
Contains information about positions. |
resultInfo{} object |
Contains information about response paging. |
summary{} object |
|
Field | Description |
id string |
UUID of an object for which this report is generated. |
name string |
Name of an object for which this report is generated. |
from string |
Timestamp (ISO 8601 format) marking the start of a period the report is generated for. |
to string |
Timestamp (ISO 8601 format) marking the end of a period the report is generated for. |
positions{} object |
|
Field | Description |
type string |
In the current implementation this is always "FeatureCollection". |
features array(position) |
Array of historical positions. |
position{} object |
|
Field | Description |
type string |
In the current version this is always "Feature". |
geometry{} object |
Object's position. |
estimatedSpeed double |
Estimated speed of an object in the given time. Presented in km/h. |
estimatedDirection double |
Estimated direction presented as a north-based azimuth. Presented in degrees. |
timestamp string |
Recorded time as timestamp (ISO 8601 format). |
userTimestamp string |
The date and time of the position being recorded by the user as a timestamp (ISO 8601 format). If not set by the user, the server timestamp is used. |
geometry{} object |
|
Field | Description |
type string |
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. |
resultInfo{} object |
|
Field | Description |
maxResult integer |
Maximum number of items returned in the response. |
pageNumber integer |
Number of the items page to be returned in the response. Maximum number of elements on the page is equal to the maxResult value. |
itemsCount integer |
Number of returned items on the page. |
HTTP response codes
Code | Meaning & possible causes |
---|---|
200 |
OK |
400 |
Bad Request:
|
403 |
Forbidden: Provided Admin Key is invalid. |
404 |
Not found: No such project. |
Examples
List all objects available to the user.
Request URL GET
https://api.tomtom.com/locationHistory/1/history/positions/61310ef2-e324-4966-9751-c70b3907d788?key=Your_API_Key&from=timestamp[&to=timestamp]
Response body
The following JSON code block demonstrates a successful response from the API server.
{
"summary": {
"name": "Example object",
"id": "c0c22f72-fdb6-412a-a8b9-92e0521e2e0d",
"from": "2019-05-30T13:00:00+0000",
"to": "2019-05-30T13:30:00Z+0000"
},
"positions": {
"type": "FeatureCollection",
"features": [
{
"timestamp": "2019-05-30T13:25:51+0000",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
19.448183,
51.759135,
0.00
]
},
"estimatedSpeed": 16.66,
"estimatedDirection": 90.00
}
]
},
"resultInfo": {
"maxResults": 100,
"pageNumber": 1,
"itemsCount": 25
}
}