Get projects transitions

Service version: 1
Last edit: 2020.07.30

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

▲ Return to top

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.

▲ Return to top

HTTP 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 project.

▲ Return to top

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
  }
}

▲ Return to top

Get projects transitions

On this page

Purpose

Request data

HTTPS method: GET

URL format

curl command

Request parameters

Response data

Response body

Response fields

HTTP Response codes

Examples

Request URL

Response body (JSON)