Get objects transitions

Service version: 1
Last edit: 2022.09.01

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 request format

GET
URL request format
https://{baseURL}/geofencing/{versionNumber}/transitions/objects/{objectId}?key={Your_API_Key}&from={timestamp}&to={timestamp}&projects={string}&maxResults={integer}&pageNumber={integer}

curl command request format

GET
curl command request format
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 format - 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

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:

  • 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.

404

Not found: No such object.

Example

Get transitions of the 'Support car 1' object (id: cfde72d8-4b9f-4f6d-83c8-87ae0465fd5d).

URL request example

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 example

Response body example - 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": [5.257763, 52.161628]
16        },
17        "projectId": "2e60fde8-f21d-4640-a7ed-69cd99783abc",
18        "projectName": "Support car parking lots",
19        "fenceId": "e5f3615e-62c8-4454-957b-dc577bb3914b",
20        "fenceName": "Europe-29-Netherlands",
21        "transitionType": "LEAVE",
22        "recordedTransitionTime": "2019-08-29T10:03:28",
23        "estimatedTransitionTime": "2019-08-29T10:02:53",
24        "estimatedDwellTime": "1123256"
25      }
26    ]
27  },
28  "resultInfo": {
29    "maxResults": 100,
30    "pageNumber": 1,
31    "itemsCount": 1
32  }
33}