Get objects transitions
Service version: 1
Last edit: 2020.07.30
On this page
- ▸ Purpose
- ▸ Request data
Purpose
This endpoint requests all transitions of a single object.
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/geofencing/versionNumber/transitions/objects/objectId?key=Your_API_Key&from=timestamp[&to=timestamp][&projects=string][&maxResults=integer][&pageNumber=integer]
curl command
curl 'https://baseURL/geofencing/versionNumber/transitions/objects/objectId?key=Your_API_Key&from=timestamp[&to=timestamp][&projects=string][&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.
- 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 |
An object UUID for which a transition 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 |
The beginning date for a 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). |
[projects] string |
UUIDs of projects to be included in the response. If the list is empty no filter is applied, and all projects are included in the response. Value: Comma-separated list of project IDs. Default: Empty list. |
[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 the items 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
The following JSON code block demonstrates a successful response from the API server.
{
"summary": {
"name": "string",
"id": "uuid_string",
"from": "ISO8601_timestamp",
"to": "ISO8601_timestamp"
},
"transitions": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
longitude_number,
latitude_number,
altitude_number
]
},
"projectId": "uuid_string",
"projectName": "string",
"fenceId": "uuid_string",
"fenceName": "string",
"transitionType": "string",
"recordedTransitionTime": "ISO8601_timestamp",
"estimatedTransitionTime": "ISO8601_timestamp",
"estimatedDwellTime": "number"
}
]
},
"resultInfo": {
"maxResults": number,
"pageNumber": number,
"itemsCount": number
}
}
Response fields
The following table describes all of the response fields.
Primary fields | |
---|---|
Field | Description |
summary{} object |
Contains information about the object's transitions request. |
transitions{} object |
Contains information about transitions. |
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. |
transitions{} object |
|
Field | Description |
type string |
In the current implementation this is always "FeatureCollection". |
features[] array(event) |
Array of historical transitions. |
event{} object |
|
Field | Description |
type string |
In the current version this is always "Feature". |
geometry{} object |
Estimated transition point. GeoJSON Point. If the transition is triggered by the first recorded position, or the transition is of the "DWELL" type, this field will be null. |
projectId string |
UUID of a project for which a transition has been recorded. |
projectName string |
Name of a project for which a transition has been recorded. |
fenceId string |
UUID of a fence for which a transition has been recorded. |
fenceName string |
Name of a fence for which a transition has been recorded. |
transitionType string |
Transition type: "ENTER", "LEAVE", or "DWELL". |
recordedTransitionTime string |
Recorded time as timestamp (ISO 8601 format). |
estimatedTransitionTime string |
Estimated transition time as a timestamp (ISO 8601 format). If the transition is triggered by the first recorded position, or the transition is of the "DWELL" type, this field will be null. |
estimatedDwellTime integer |
Estimated dwell time (in seconds) inside the fence before this transition occurred. If it's "ENTER" transition or the transition is triggered by the first recorded position - this field will be 0. |
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:
|
404 |
Not found: No such object. |
Examples
Get transitions of the 'Support car 1' object (id: cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d)
Request URL
https://api.tomtom.com/geofencing/1/transitions/objects/cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d?key=Your_API_Key&from=2019-08-29T01:00:00&to=2019-08-29T23:00:00&projets=2e60fde8-f21d-4640-a7ed-69cd99783abc,23486586-c558-4edd-bc59-3a62356237f9
Response body (JSON)
{
"summary": {
"name": "Support car 1",
"id": "cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d",
"from": "2019-08-29T01:00:00",
"to": "2019-08-29T23:00:00"
},
"transitions": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
5.257763,
52.161628
]
},
"projectId": "2e60fde8-f21d-4640-a7ed-69cd99783abc",
"projectName": "Support car parking lots",
"fenceId": "e5f3615e-62c8-4454-957b-dc577bb3914b",
"fenceName": "Europe-29-Netherlands",
"transitionType": "LEAVE",
"recordedTransitionTime": "2019-08-29T10:03:28",
"estimatedTransitionTime": "2019-08-29T10:02:53",
"estimatedDwellTime": "1123256"
}
]
},
"resultInfo": {
"maxResults": 100,
"pageNumber": 1,
"itemsCount": 1
}
}