Developer

Report request

Service version: 1
Last edit: 2023.06.01

Purpose

Geofencing Reports are the central part of our Geofencing service. Each Geofencing Report contains information about provided position's surrounding fences that exist in the selected project.

This endpoint provides:

  • A short summary containing a unique project id, the position for which the Geofencing Report is generated, and a radius used to create the Geofencing Report expressed in meters.
  • A list of fences that the request point is inside of, sorted by distance in ascending order.
  • A list of fences that the request point is outside of, sorted by distance in ascending order.

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.

GET URL request format

get
GET URL request format
https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&object={objectId}&range={range}

GET curl command request format

get
GET curl command request format
curl 'https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&object={objectId}&range={range}'

HTTPS method: POST

It's the same type of Geofencing Report as the standard one: Geofencing API Report. If a user uses this POST version, it will detect and save transitions of the provided object.

Important note:

Before a customer can send a position in the report they must give consent for the storing of historical positions and to record a transition they must give consent for storing transitions, both are required.

If consent is given, this endpoint writes the provided position to positions history. To accurately calculate transitions, this endpoint uses the freshest, previous, position from history, regardless which API recorded it.

POST URL request format

post
POST URL request format
https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&object={objectId}&range={range}&timestamp={timestamp}

POST curl command request format

post
POST curl command request format
curl -XPOST 'https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&object={objectId}&range={range}&timestamp={timestamp}'

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.

Required parameters

Description

baseURL
string

The base URL for calling the API.
Value: api.tomtom.com

versionNumber
string

The service version number.
Value: 1

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

point
array (of floats)

A location (in coordinates) for which the Geofencing Report is requested.
Value: An array of floats:

  • longitude

  • latitude

  • altitude (optional)

latitude
float

The latitude coordinate of the point in degrees with a precision of 6 digits after the decimal point.
Value: A latitude coordinate
Unit: degrees
Range: <-90,90>
Reference: See WGS84 datum (World Geodetic System)

longitude
float

Longitude coordinate of the point in degrees with a precision of 6 digits after the decimal point.
Value: A longitude coordinate
Unit: degrees
Range: <-180,180>
Reference: WGS84 datum (World Geodetic System)

altitude
float (optional)

The altitude coordinate of the point expressed in meters, with a precision of 0.1 meter.
Value: An altitude coordinate
Default value: 0
Unit: meters
Range: <-500,15000>
Reference: WGS84 datum (World Geodetic System)

Optional parameters

Description

projectId
string

The unique project id used to generate the Geofencing Report.

  • If no project id is provided, but an object with a default project is provided, that default project is used for this request.

  • If no project is provided and the object has no default project, a HTTP 400 error is returned with that information.

  • If a project id is provided then it takes precedence over object's default project.


Value: A UUID
Default value: The object 's default project if it exists.

object
string

The object unique id used to generate a Geofencing Report. If no project id is provided, but the object has a default project, that default project is used for this request.
Value: A UUID

range
float

The radius of a circle around the provided point. This is used to decide whether fences, that do not contain the point, are close enough to report. It does not affect fences that contain the point. If this parameter's value is 0 or not included, only the closest fence is included in the outside element of the response.
Default value: 0
Other value: A circle's radius
Unit: meters
Range: <0,100000>

timestamp
string

The date and time of the position being recorded by the user.
Default value: server timestamp of the request
Value: ISO 8601 format timestamp (YYYY-MM-DDThh:mm:ss)

Response data

The Geofencing Report contains:

  1. A short summary containing:

    • A unique project id.
    • A position generated for the Geofencing Report.

    • A radius used to create the Geofencing Report, expressed in meters.

  2. A list of fences that the request point is inside of, sorted by distance in ascending order. If the object is not inside any fences, the list is empty. If not, each fence entry contains:

    • A unique fence id.
    • A fence name.

    • The distance from the request point to the nearest point on the fence border, represented as a negative value.

    • Coordinates of the nearest point on the fence border.

  3. A list of fences that the request point is outside of, sorted by distance in ascending order. As long as there is at least one outside fence in the requested project, the list contains at least one entry. Each fence entry contains:

    • A unique fence id.
    • A fence name.

    • The distance from the request point to the nearest point on the fence border, represented as a positive value.

    • Coordinates of the nearest point on the fence border.

Response body

The following JSON code block demonstrates a successful response from the API server.

Response body format - JSON
1{
2  "summary": {
3    "project": "project_id",
4    "type": "Point",
5    "coordinates": [
6      longitude,
7      latitude,
8      altitude
9    ],
10    "range": range_in_meters
11  },
12  "inside": {
13    "type": "FeatureCollection",
14    "features":
15  },
16  "outside": {
17    "type": "FeatureCollection",
18    "features":
19  }
20}

Each element in a features array is in the following format:

features array elements format - JSON
1{
2  "feature": {
3    "id": "fence_id",
4    "name": "fence_name",
5    "distance": distance_to_the_nearest_border_in_meters,
6    "type": "Feature",
7    "geometry": {
8      "type": "Point",
9      "coordinates": [
10        longitude,
11        latitude,
12        altitude
13      ]
14    },
15    "properties": {
16      "key": "value"
17    }
18  }
19}

Response fields

The following table describes all of the fields that can appear in a response.

Primary fields

Field

Description

summary
object

Contains information about the Geofencing Report request endpoint parameters.

inside
object

Contains information about the fences the object is in.

outside
object

Contains information about the fences the object is outside of. It contains at least the closest fence or list of fences inside the radius.

summary object

Field

Description

project
string

Project UUID of the project the Geofencing Report was generated for.

type
string

The type of object geometry the Geofencing Report was generated for. In the current version it is always "Point".

coordinates
array (double)

Coordinates of a geofenced object in the form of an array containing (in this order): longitude, latitude, and altitude. Altitude is optional.

range
integer

The maximum distance in meters, between an object and a fence that allows the fence to be included in a Geofencing Report.

inside object

Field

Description

type
string

The type of elements in the following collection. In the current version it is always "FeatureCollection".

features
array

A list of fences that the object is in. The list is sorted from the closest to the farthest fence.

outside object

Field

Description

type
string

The type of elements in the following collection. In the current version it is always "FeatureCollection".

features
array

A list of fences that the object is in. The list is sorted from the closest to the farthest fence.

feature object

Field

Description

id
string

The UUID of the listed fence.

name
string

The fence name.

distance
double

The distance (in meters) from a fence to the geofenced object. The value can be negative if the object is inside a fence.

type
string

In the current version it is always "Feature".

geometry
object

Contains the closest point on the fence to a geofenced object's position.

properties
object

This is an object containing user-defined properties of the fence. Its content varies between fences.

geometry object

Field

Description

type
string

The type of geometry. In the current version it is always "Point".

coordinates
array (double)

Coordinates of the point in an array containing (in this order): longitude, latitude.

Examples

Reports for fences.

A request for a Geofencing Report for fences in a 1km range for:

  • the project ad27ee08-9a32-11e8-9eb6-529269fb1459
  • the object bb02af69-9dbd-4504-b0a0-c93deb0d82d0
get
URL request example 1
https://api.tomtom.com/geofencing/1/report/ad27ee08-9a32-11e8-9eb6-529269fb1459?point=-68.137385,45.138123&object=bb02af69-9dbd-4504-b0a0-c93deb0d82d0&range=1000&key={Your_API_Key}

A request for a Geofencing Report for fences in a 1km range for:

  • The object bb02af69-9dbd-4504-b0a0-c93deb0d82d0 and its default project.
get
URL request example 2
https://api.tomtom.com/geofencing/1/report?point=-68.137385,45.138123&object=bb02af69-9dbd-4504-b0a0-c93deb0d82d0&range=1000&key={Your_API_Key}