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
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.
- 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
POST
URL request example
https://{baseURL}/geofencing/{versionNumber}/report/{projectId}?key={Your_API_Key}&point={longitude,latitude,altitude}&objectId={objectId}&range={range}×tamp={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}×tamp={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:
|
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.
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.
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:
- 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.
Response body - JSON
1{2 "summary": {3 "project": "project_id",4 "type": "Point",5 "coordinates": [6 longitude,7 latitude,8 altitude9 ],10 "range": range_in_meters11 },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 altitude13 ]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&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}