Get fences transitions
Purpose
This endpoint requests all transitions of multiple objects from a fence point of view.
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/fences/{fenceId}?key={Your_API_Key}&from={timestamp}&to={timestamp}&maxResults={integer}&pageNumber={integer}
curl command format
GET
Request curl command example
curl 'https://{baseURL}/geofencing/{versionNumber}/transitions/fences/{fenceId}?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 . |
fenceId string | A fence UUID for which a transition history is requested. Value: Requested fence'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). |
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 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 "objectId": "uuid_string",24 "objectName": "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 fence'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. |
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. |
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 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 |
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 maxResults 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 fence. |
Example
Get fences transitions
Get transitions of the 'Custom area' fence (id: e0b44791-bd14-48d5-829e-5d958d188f71
).
Request URL
GET
URL request example
https://api.tomtom.com/geofencing/1/transitions/fences/e0b44791-bd14-48d5-829e-5d958d188f71?key={Your_API_Key}&from=2019-08-29T01:00:00&to=2019-08-29T23:00:00
Response body
Response body - JSON
1{2 "summary": {3 "name": "Support car 1",4 "id": "e0b44791-bd14-48d5-829e-5d958d188f71",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 "objectId": "abdbaaa6-2851-4946-90d1-41e676506a93",23 "objectName": "Support car",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}