Get objects transitions

Service version: 1
Last edit: 2022.07.20

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 parametersDescription
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 parametersDescription
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_number
19          ]
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": number
36  }
37}

Response fields

The following table describes all of the response fields.

Primary fields
FieldDescription
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
FieldDescription
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
FieldDescription
type
string		In the current implementation this is always "FeatureCollection".
features
array (event)		Array of historical transitions.
event object
FieldDescription
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
FieldDescription
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
FieldDescription
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

CodeMeaning & possible causes
200OK
400Bad Request:
  • Wrong datetime format.
  • Bad order of dates.
  • The value of parameter is not a positive decimal number.
  • Date range can span up to 24 hours.
404Not 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.161628
18          ]
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": 1
35  }
36}