Introduction

Service version: 1
Last edit: 2022.09.01

Important note:

Before a customer can use Geofencing endpoints they must register.

  • Registering creates a configuration for the customer and creates an Admin Key, used to create/edit/delete Geofencing data.
  • Use the Register Admin Key endpoint in the Configuration service to do this.

What is TomTom's Geofencing API?

TomTom's Geofencing API service is intended to define virtual barriers on real geographical locations. Together with the location of an object, you can determine whether that object is located within, outside, or close to a predefined geographical area.

Any object that has connectivity can be geofenced. It can be:

  • A person
  • A vehicle
  • A package
  • A telephone

Libraries of fences and objects

For Geofencing to work, you need to create your own library of fences.

  • Fences can be arranged into projects for easier administration.
  • Fences can have multiple user-defined attributes.
  • Fences can be of any shape or size.

You can also create a library of your objects and optionally define their attributes.

Location report

A location report for a given radius contains a list of fences that:

  • The object is in.
  • The object is outside of.

Regardless of the selected radius, a user will always receive the nearest outside fence, if available.

Geofencing API services

Configuration service

Provides a client-side reporting device acting as a representation of the item to be geofenced.

Projects service

Provides a collection of fences identified by a unique ID.

Fences service

The Fences service enables you to create fences (areas) with geometries of a certain type, such as "CIRCLE".

Custom fence shapes

Describes what fence shapes (apart from GeoJSON polygon/multipolygon) can be used in the Geofencing API.

Objects service

Provides a client-side reporting device acting as a representation of the item to be geofenced.

Report service

The Report service provides a JSON document that contains information for a specified object or point.

Transitions service

Provides the means to manage and read transition data. A transition is an event of an object crossing a border of a fence.

Archive service

The Archive service provides ways to download a user's data in compressed packages.

Alert service

Responsible for creating alert messages which will be sent to users via the Notifications API.

Transition alerts (Deprecated)

The Transition alerts service is deprecated. Use the Alert service instead.

Dwell alerts (Deprecated)

The Dwell alerts service is deprecated. Use the Alert service instead.

Getting started

  1. To get your API Key, you first need to be registered for the TomTom Developer Portal. If you don't have an account, no worries! Register / Sign in now before continuing.
  2. Once you are registered, go to your Dashboard and locate the API Key that you would like to use (we've created the first one for you, it's called My first API Key).
  3. Read the documentation and start coding.
  4. Consider using the TomTom Maps SDK for Web, for iOS, and for Android.
  5. Check related Blog articles for further information.

Features

The following features are included in the Geofencing API.

  1. A Geofencing service available via this online Geofencing API.
  2. Geofencing configuration that is securely stored by TomTom in the cloud.
  3. Circles, polygons, corridors, and two-point rectangle fences with labels.
  4. Objects reported inside or outside of a fence.
  5. The distance from an object to the nearest border of a fence.

Current limits include:

  • 1k objects
  • 10k projects
  • 1k fences in each project
  • 1k vertices per polygon fence
  • Transition history is kept as active data for 3 months.
  • Transition history is kept as a cold archive 6 months after the active period.

To change any of these limits, please contact your TomTom licensing assistant.

There are no surface size limits on polygons used as fences, except precision. Coordinates with difference smaller than 0.000001 degree between them are indistinguishable.

Surface size of polygons has little impact on response speed, but the number of vertices impacts speed significantly. To receive response faster - one should consider simplifying polygons used as fences.

Interactions with other APIs

Location History API

The Geofencing API and Location History API share Objects when both are on the same account.

  • Each API has access to a view of an Object that is relevant for the given API.
  • In the Geofencing API view, the name, defaultProject, and properties fields are available for an Object.

The Geofencing API and Location History API share the consentForStoringObjectsPositionsHistory setting.

  • When this setting is set to true both services can save an Objects' positions.
  • After sending a position through the Geofencing API and triggering a transition calculation, the latest previous position is used, no matter from which service it has been sent.

Quick start guide

Configuration

Your API and Admin Keys

You need to have two keys to work with Geofencing:

  • An API Key: This allows you to work with any TomTom Maps API, including Geofencing.
  • An Admin Key: This is used by Geofencing to administer (create, edit, delete) your projects, fences and objects.

Start working with the Geofencing API

  • Follow these steps to start working with the Geofencing API.
  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.

Step 1. Register for an API Key

This key will let you read data from the service and request reports. In addition, it will let you register for an Admin Key.

Step 2. Register an Admin Key

To register for an Admin Key, use the Configuration service "Register Admin Key" endpoint. An Admin Key is used to manage objects/fences/projects within the Geofencing API.

Register for your Admin Key using this URL:

URL request example

POST
URL - Register for your Admin Key
1https://api.tomtom.com/geofencing/1/register?key={Your_API_Key}
2{
3 "secret": "your_secret"
4}

or use the curl command:

curl command request example

POST
curl - Register for your Admin Key
1curl -XPOST "Content-type: application/json" -d
2'{
3 "secret": "your_secret"
4 }'
5'https://api.tomtom.com/geofencing/1/register?key={Your_API_Key}'

The secret has to be between 10 and 30 characters. The secret is a password used to regenerate a stolen or lost Admin Key. It will not be asked for in any other circumstances.

The endpoint returns a generated Admin Key. For example:

Response body - JSON
1{
2 "adminKey": "ooCP41LoslEhThwNPyCFjtTsgCDyJgTaoz9JJFpVJvW8MjA3"
3}

You should save your Admin Key for administrative calls. You can fully manage your account in the Geofencing API when you have both the API Key and Admin Key.

Step 3. Create a Project

Fences must be added to at least one project, so you need to create a project before creating fences. A Project is created using the Project service "Add new project" endpoint.

URL request example

POST
URL request example
1https://api.tomtom.com/geofencing/1/projects?key={Your_API_Key}&adminKey={Your_Admin_Key}
2{
3 "name": "A unique project name"
4}

curl command request example

POST
Request curl command format
1curl -XPOST "Content-type: application/json" -d
2'{
3 "name": "A unique project name"
4 }'
5'https://api.tomtom.com/geofencing/1/projects?key={Your_API_Key}&adminKey={Your_Admin_Key}'

The endpoint returns project details including a project id.

Response body - JSON
1{
2 "id": "57dc2cad-85a3-439a-8224-2730d7822133",
3 "name": "A unique project name"
4}

This project id is required for future calls (i.e., adding a fence to a project).

Step 4. Creating fences

Fences can be created and added to a project using the Fence service "Add new fence to a project" endpoint.

URL request example

POST
URL request example
1https://api.tomtom.com/geofencing/1/projects/{projectId}?key={Your_API_Key}&adminKey={Your_Admin_Key}
2{
3 "name": "Flemish diamond"
4 "type": "Polygon",
5 "coordinates": [
6 [
7 [3.55, 51.08],
8 [4.36, 50.73],
9 [4.84, 50.85],
10 [4.45, 51.30],
11 [3.55, 51.08]
12 ]
13 ]
14}

curl command request example

POST
Request curl command example
1curl -XPOST "Content-type: application/json" -d '
2{
3 "name": "Flemish diamond"
4 "type": "Polygon",
5 "coordinates": [
6 [
7 [3.55, 51.08],
8 [4.36, 50.73],
9 [4.84, 50.85],
10 [4.45, 51.30],
11 [3.55, 51.08]
12 ]
13 ]
14}'
15'https://api.tomtom.com/geofencing/1/projects/{projectId}?key={Your_API_Key}&adminKey={Your_Admin_Key}'

For your convenience, TomTom has a web app to create your fences which can be downloaded at "Geofences Creator" from our GitHub repository.

The endpoint returns fence details.

Response body - JSON
1{
2 "id": "e33f7aee-2e86-4485-af82-631debd73d86",
3 "name": "Flemish diamond",
4 "type": "Feature",
5 "geometry": {
6 "type": "Polygon",
7 "coordinates": [
8 [
9 [3.55, 51.08],
10 [4.36, 50.73],
11 [4.84, 50.85],
12 [4.45, 51.30],
13 [3.55, 51.08]
14 ]
15 ]
16 },
17 "properties": {}
18}

Step 5. Creating objects

For each entity to be geofenced (person, vehicle, package, telephone, etc.) an object can be created using the Object service "Add new object" endpoint.

Note: Creating an object currently is not mandatory to get a report based on a position. In future releases we will include support for an object's history where creating an object is required to use the history feature.

URL request example

POST
URL request example
1https://api.tomtom.com/geofencing/1/objects?key={Your_API_Key}&adminKey={Your_Admin_Key}
2{
3 "name": "A Volvo Car"
4}

curl command request example

POST
curl command request example
1curl -XPOST "Content-type: application/json" -d
2'{
3 "name": "A Volvo Car"
4 }'
5'https://api.tomtom.com/geofencing/1/objects?key={Your_API_Key}&adminKey={Your_Admin_Key}'

Step 6. Reporting

Pass an object location to the Report service "Geofencing Report request" endpoint to get:

  • A list of fences the object is inside of.
  • A list of fences the object is outside of.

URL request example

GET
URL request example
https://api.tomtom.com/geofencing/1/report/{projectId}?key={Your_API_Key}&point={lon,lat}

curl command request example

GET
curl command request example
curl 'https://api.tomtom.com/geofencing/1/report/{projectId}?key={Your_API_Key}&point=4.055737,51.030168'

Roles in Geofencing

Each Geofencing API user has a Role assigned to them. Roles define activities that a user can perform within the service.

EntityDescription
CustomerThe owner of the API Key.
  • The Customer is an abstract entity that can be a Requester, an Admin, or just the owner of an account.
  • The Customer has no assigned role in the system.
RequesterA client-side entity with read-only rights for data within a configuration. The Requester only requires an API Key to query the service.
AdminA client-side entity with rights to create, read, update and delete data belonging to an account (identified by an API Key) that it is assigned to. To perform administrative functions, the Admin requires both an API Key and an Admin Key.
ObjectA client-side reporting device that acts as a representation of the thing to be geofenced (a person, drone, vehicle, etc.). It is defined on the customer side by an Admin.
An Object has the following characteristics:
  • It is uniquely identifiable.
  • It can only be linked to a single Configuration at a time.
  • It has a certain connectivity capability.
  • It does not have to always be connected to the Geofencing service.
  • It has a position. It may also have other user-defined properties.
To query the service, an Object only requires an API Key.
Note: Both "Requester" and "Admin" are sometimes called "user" if their respective rights do not conflict.

Entities in Geofencing

Entities are manageable elements within the Geofencing API.

EntityDescription
PointThe object's coordinate on earth, obtained by GPS sensors or otherwise.
ConfigurationA series of projects, fences, and objects with their attributes, referred to by an API Key.
  • Configurations are defined on the customer side.
  • There can be only one configuration per customer key.
ProjectA collection of fences identified by a unique ID. A Configuration can have multiple Projects, but each Project is attached to only one Configuration.
FenceA virtual representation of a certain geographic area.
  • Fences can have various shapes and can have multiple user-defined properties.
  • A Project can have one Fence. It can also have multiple Fences.
  • A Fence must belong to at least one Project (it can belong to more).
Geofencing ReportA JSON document that contains the following information for a specified object or point:
  • A list of fences the object/point is inside of.
  • A list of the fences within a specified radius that the object/point is not inside of.
  • The lists can be empty if no fences match the request parameters.

The lists:

  • Can be empty if no fences match the request parameters.
  • Will always show the closest outside fence, even if it is outside of the search radius.
  • The outside fences list can only be empty if there are no more fences left in the project.
Customer key1 ——— 1Configuration1 ——— 0..*Project1..* ——— 0..*Fence

Rights in Geofencing

Rights describe types of actions that a user can perform within the Geofencing API.

Legend to the following data table

  • (C)reate: an entity can create new projects, fences, objects.
  • (R)ead: an entity can generate reports, list projects/fences/objects, get details about a project/fence/object.
  • (U)pdate: an entity can change attributes and properties of projects/fences/objects, and assign a fence to a project
  • (D)elete: an entity can delete projects/fences/objects, remove a fence relation to a project, or an object relation to a project.
 FenceObjectProjectReportArchive
CRUDCRUDCRUDRCR
Admin+++++++++++++++
Requestor/Object-+---+---+--+--