Get projects transitions
Service version: 1
Last edit: 2020.07.30
On this page
- ▸ Purpose
- ▸ Request data
Purpose
This endpoint requests all transitions linked with fences in a project.
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/projects/projectId?key=Your_API_Key&from=timestamp[&to=timestamp][&maxResults=integer][&pageNumber=integer]
curl command
curl 'https://baseURL/geofencing/versionNumber/transitions/projects/projectId?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.
- 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 .
|
projectId string |
An project UUID for which a transition history is requested. Value: Requested project'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). |
[maxResults] 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 maxResults 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
]
},
"objectId": "uuid_string",
"objectName": "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 project's transitions request. |
transitions{} object |
Contains information about transitions. |
resultInfo{} object |
Contains information about response paging. |
summary{} object |
|
Field | Description |
id string |
UUID of a project for which this report is generated. |
name string |
Name of a project 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. |
objectId string |
UUID of an object for which a transition has been recorded. |
objectName string |
Name of an object 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 a timestamp (ISO 8601 format). |
estimatedTransitionTime string |
Estimated transition time as a timestamp (ISO 8601 format). If transition is triggered by the first recorded position or transition is of "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 |
maxResults 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 project. |
Examples
Get transitions for the 'Support car parking lots' project (id: cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d)
Request URL
https://api.tomtom.com/geofencing/1/transitions/projects/cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d?key=Your_API_Key&from=2019-08-29T01:00:00&to=2019-08-29T23:00:00
Response body (JSON)
{
"summary": {
"name": "Support car parking lots",
"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
]
},
"objecId": "2e60fde8-f21d-4640-a7ed-69cd99783abc",
"objectName": "Support car I",
"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": "1122719"
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
5.257872,
52.161737
]
},
"objecId": "ddbeb555-787d-48f1-a59c-158b40a3df8e",
"objectName": "Support car II",
"fenceId": "e5f3615e-62c8-4454-957b-dc577bb3914b",
"fenceName": "Europe-29-Netherlands",
"transitionType": "ENTER",
"recordedTransitionTime": "2019-08-29T14:31:34",
"estimatedTransitionTime": "2019-08-29T14:30:58",
"estimatedDwellTime": "0"
}
]
},
"resultInfo": {
"maxResults": 100,
"pageNumber": 1,
"itemsCount": 2
}
}