Get objects transitions
Purpose
This endpoint requests all transitions of a single object.
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
URL request example
https://{baseURL}/geofencing/{versionNumber}/transitions/objects/{objectId}?key={Your_API_Key}&from={timestamp}&to={timestamp}&projects={string}&maxResults={integer}&pageNumber={integer}
curl command format
GET
Request curl command example
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.
- 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 | 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 | Description |
---|---|
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.
Response body - JSON
1{2 "summary": {3 "name": "string",4 "id": "uuid_string",5 "from": "ISO8601_timestamp",6 "to": "ISO8601_timestamp"7 },8 "transitions": {9 "type": "FeatureCollection",10 "features": [11 {12 "type": "Feature",13 "geometry": {14 "type": "Point",15 "coordinates": [16 longitude_number,17 latitude_number,18 altitude_number19 ]20 },21 "projectId": "uuid_string",22 "projectName": "string",23 "fenceId": "uuid_string",24 "fenceName": "string",25 "transitionType": "string",26 "recordedTransitionTime": "ISO8601_timestamp",27 "estimatedTransitionTime": "ISO8601_timestamp",28 "estimatedDwellTime": "number"29 }30 ]31 },32 "resultInfo": {33 "maxResults": number,34 "pageNumber": number,35 "itemsCount": number36 }37}
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. |
Response codes
Code | Meaning & possible causes |
---|---|
200 | OK |
400 | Bad Request:
|
404 | Not found: No such object. |
Example
Get transitions
Get transitions of the 'Support car 1' object (id: cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d).
Request URL
GET
URL request example
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
Response body - JSON
1{2 "summary": {3 "name": "Support car 1",4 "id": "cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d",5 "from": "2019-08-29T01:00:00",6 "to": "2019-08-29T23:00:00"7 },8 "transitions": {9 "type": "FeatureCollection",10 "features": [11 {12 "type": "Feature",13 "geometry": {14 "type": "Point",15 "coordinates": [16 5.257763,17 52.16162818 ]19 },20 "projectId": "2e60fde8-f21d-4640-a7ed-69cd99783abc",21 "projectName": "Support car parking lots",22 "fenceId": "e5f3615e-62c8-4454-957b-dc577bb3914b",23 "fenceName": "Europe-29-Netherlands",24 "transitionType": "LEAVE",25 "recordedTransitionTime": "2019-08-29T10:03:28",26 "estimatedTransitionTime": "2019-08-29T10:02:53",27 "estimatedDwellTime": "1123256"28 }29 ]30 },31 "resultInfo": {32 "maxResults": 100,33 "pageNumber": 1,34 "itemsCount": 135 }36}