Sorry, you need to enable JavaScript to visit this website.

Report request

 

Service version: 1
Last edit: 2019.09.18

On this page

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

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/report/projectId?key=Your_API_Key&point=longitude,latitude,altitude&object=objectId&range=range

curl command

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

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.
Required parameters
Parameter 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
Parameter 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.

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>

▲ Return to top

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.

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

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/report/projectId?key=Your_API_Key&point=longitude,latitude,altitude&object=objectId&range=range

▲ Return to top

Response data

The Geofencing Report contains:

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

{
  "summary": {
    "project": "project_id",
    "type": "Point",
    "coordinates": [
      longitude,
      latitude,
      altitude
    ],
    "range": range_in_meters
  },
  "inside": {
    "type": "FeatureCollection",
    "features": []
  },
  "outside": {
    "type": "FeatureCollection",
    "features": []
  }
}

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

{
  "feature": {
    "id": "fence_id",
    "name": "fence_name",
    "distance": distance_to_the_nearest_border_in_meters,
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [
        longitude,
        latitude,
        altitude
      ]
    },
    "properties": {
      "key": "value"
    }
  }
}

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

▲ Return to top

Examples

Example 1. 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
&object=bb02af69-9dbd-4504-b0a0-c93deb0d82d0
&range=1000
&key=Your_API_Key

Example 2. 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
&object=bb02af69-9dbd-4504-b0a0-c93deb0d82d0
&range=1000
&key=Your_API_Key

▲ Return to top

You are here