Report request

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 format

https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&objectId={objectId}&range={range}

GET curl command format

curl 'https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&objectId={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.

• Use the Set new settings values endpoint in the Location History API Configuration service to do this.
• Consent for storing historical positions can be revoked at any time.

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

https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&objectId={objectId}&range={range}&timestamp={timestamp}

POST curl format

curl -XPOST 'https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&objectId={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.

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.

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:

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.

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

https://api.tomtom.com/geofencing/1/report/ad27ee08-9a32-11e8-9eb6-529269fb1459?point=-68.137385,45.138123&objectId=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.

https://api.tomtom.com/geofencing/1/report?point=-68.137385,45.138123&objectId=bb02af69-9dbd-4504-b0a0-c93deb0d82d0&range=1000&key={Your_API_Key}