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

Geofencing Documentation

 

Product version: 1.0 (Public Preview)
Last edit: 2019.02.08

The TomTom Geofencing API is currently available in Public Preview. To find out what our Public Preview is and to revisit our Terms & Conditions, see here.

On this page

Important note:

Before a customer can act as an Admin for Geofencing services and their 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.

Purpose

What is TomTom's Geofencing service?

TomTom's Geofencing 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
  • Vehicle
  • Package
  • 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.

▲ Return to top

Features

The following features are included in the Geofencing API.

  1. A Geofencing service available via developer.tomtom.com and an Online 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

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

Services with endpoints

Objects service
The Objects service provides a client-side reporting device acting as a representation of the item to be geofenced.
GETList objects
GETGet object details
POSTAdd new object
PUTEdit object
DELETEDelete object
Projects service
The Projects service provides a collection of fences identified by a unique ID.
GETList projects
GETGet project details
POSTAdd new project
PUTEdit projects
DELETEDelete projects
Report service
The Report service provides a JSON (a lightweight data-interchange format) document that contains information for a specified object or point:
GETReport request
 
Configuration service
The Configuration service is responsible for managing one's options. It is essential to create and work with one's account.
POSTRegister Admin Key
POSTRegenerate Admin Key
POSTChange customer secret
Fences service
The Fences service enables you to create fences (areas) with geometries of a certain type, such as "CIRCLE".
GETList fences for a given project
GETGet fence details
PUTEdit fence
POSTAdd new fence to a project
POSTCreate new fence & assign to multiple projects
DELETEDelete fence
DELETEDelete fence from project
Note: The Fences service also contains a chapter titled "Custom fence shapes", describing what fence shapes (apart from GeoJSON polygon/multipolygon) can be used in the Geofencing API.

▲ Return to top

Quick start guide

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, incl. Geofencing.
  • An Admin Key: This is used exclusively to enable Geofencing to configure your fences and objects.

Getting started

Follow these steps to start working with the Geofencing API:

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. See Step 2.
Step 2. Register an Admin Key.
An Admin Key is used to manage objects/fences/projects within the Geofencing API.
Register for your Admin Key using:

POST https://api.tomtom.com/geofencing/1/register?key=*****{“secret”: “your_secret”}

or use the curl command

curl -v -XPOST -H "Content-type: application/json" -d'{“secret”: “your_secret”}''https://api.tomtom.com/geofencing/1/register?key=*****'
Step 3. An Admin Key will be sent in return.
The secret is a password used to regenerate a stolen or lost Admin Key.
It will not be asked in any other circumstance.

You can fully manage your account in the Geofencing API when you have both the API Key and Admin Key.

▲ Return to top

Roles in Geofencing

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

Role Description
Customer The 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.
Requester A client-side entity with read-only rights for data within a configuration. The Requester only requires an API Key to query the service.
Admin A 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.
Object A 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 don't affect each other.

▲ Return to top

Entities in Geofencing

Entities are manageable elements within the Geofencing API.

Entity Description
Point The object's coordinate on earth, obtained by GPS sensors or otherwise.
Configuration A 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.
Project A collection of fences identified by a unique ID. A Configuration can have multiple Projects, but each Project is attached to only one Configuration.
Fence A 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).
Report A a JSON (a lightweight data-interchange format) 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.

Customer key 1 ——— 1 Configuration 1 ——— 0..* Project 1..* ——— 0..* Fence

* In the preceding diagram, an asterisk denotes that an object can update its state, i.e., it can add its current state to the list (position + attributes).

▲ Return to top

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 project/fence/object.
(U)pdate: An entity can change attributes and properties of projects/fences/objects, assign a fence to a project.
(D)elete: An entity can delete projects/fences/objects, remove a fence relation to a project, or object relation to a project.
  Fence Object Project Report
C R U D C R U D C R U D R
Admin + + + + + + + + + + + + +
Requestor/Object - + - - - + - - - + - - +

▲ Return to top