Report request

Service version: 1
Last edit: 2019.09.18

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

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

GET curl command format

GET
Request curl command example
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.
  • 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

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

POST curl format

POST
curl request example
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.
Required parametersDescription
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 parametersDescription
projectId
string
The unique project id used to generate the Geofencing Report.
  • If no project id is provided, but an object with a defaultproject 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.
objectId
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.
  • 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 - 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
FieldDescription
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
FieldDescription
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
FieldDescription
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
FieldDescription
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
FieldDescription
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
FieldDescription
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&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.
GET
URL request example 2
https://api.tomtom.com/geofencing/1/report?point=-68.137385,45.138123&objectId=bb02af69-9dbd-4504-b0a0-c93deb0d82d0&range=1000&key={Your_API_Key}