Get objects position history
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
- 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
GET
Request example
https://{baseURL}/locationHistory/{versionNumber}/history/positions/{objectId)?key={Your_API_Key}&from={timestamp}&to={timestamp}&maxResults={integer}&pageNumber={integer}
curl command format
GET
Request curl command
curl 'https://{baseURL}/locationHistory/{versionNumber}/history/positions/{objectId)?key={Your_API_Key}&from={timestamp}&to={timestamp}&maxResults={integer}&pageNumber={integer}'
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.
- The maximum allowed time between provided timestamps is 24h.
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 . |
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 | Description |
---|---|
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
Response body - JSON
1{2 "summary": {3 "name": "object_name",4 "id": "object_id",5 "from": "beginning_timestamp",6 "to": "end_timestamp"7 },8 "positions": {9 "type": "FeatureCollection",10 "features": [11 {12 "timestamp": "timestamp",13 "userTimestamp": "timestamp",14 "type": "Feature",15 "geometry": {16 "type": "Point",17 "coordinates": [18 longitude,19 latitude,20 altitude21 ]22 },23 "estimatedSpeed": speed_value,24 "estimatedDirection": azimuth25 }26 ]27 },28 "resultInfo": {29 "maxResults": max_number_of_results,30 "pageNumber": page_number,31 "itemsCount": number_of_results32 }33}
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. |
resultInfoobject | |
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. |
Response codes
Code | Meaning & possible causes |
---|---|
200 | OK |
400 | Bad Request:
|
403 | Forbidden: Provided Admin Key is invalid. |
404 | Not found: No such project. |
Example
List all objects available to the user.
Request URL
GET
Request example
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.
Response body - JSON
1{2 "summary": {3 "name": "Example object",4 "id": "c0c22f72-fdb6-412a-a8b9-92e0521e2e0d",5 "from": "2019-05-30T13:00:00+0000",6 "to": "2019-05-30T13:30:00Z+0000"7 },8 "positions": {9 "type": "FeatureCollection",10 "features": [11 {12 "timestamp": "2019-05-30T13:25:51+0000",13 "type": "Feature",14 "geometry": {15 "type": "Point",16 "coordinates": [17 19.448183,18 51.759135,19 0.0020 ]21 },22 "estimatedSpeed": 16.66,23 "estimatedDirection": 90.0024 }25 ]26 },27 "resultInfo": {28 "maxResults": 100,29 "pageNumber": 1,30 "itemsCount": 2531 }32}