Developer

Introduction

Service version: 1
Last edit: 2024.01.16

What is TomTom's Location History API?

TomTom's Location History API is intended to keep track and manage the locations of multiple objects. It can share data with TomTom's Geofencing service to enhance it with the history of object transitions through fence borders.

Any object that has connectivity can send its location. It can be:

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

The TomTom Location History API consists of the following services with endpoints.

Configuration service

The Configuration service is responsible for managing user's options. It is essential to create and to work with your account.

Configuration service

Objects service

The Objects service provides a client-side reporting device acting as a representation of items to record positions for.

Objects service

Position History service

The Position History service providest tools to register object's position and read historical positions.

Position History service

Archive service

The Location History API Archive service is responsible for downloading a user's data in one, compressed file.

Archive service

Getting Started

Use the following topics to become more acquainted with this API and its endpoints.

How to get a TomTom API Key

How to get a TomTom API Key

When you use our location Service APIs, we need a way to identify that it is your application that is making the request to use the service (API).

Follow these instructions.
The TomTom Knowledge Base

TomTom Knowledge Base

The TomTom Knowledge Base optimizes the retrieval of information via articles, blogs, FAQs, tutorials, and videos for your use and reference.

Open the Knowledge Base
Location History API Service Basics

Location History API Service Basics

TomTom Location History API services offer the ability to build applications based on object location histories. The Location History service can potentially be used for managing vehicle fleets, handling optimal taxi pickup locations, and for delivering on-demand services. This article introduces you to some of the concepts behind location history services and provides an overview of the services and endpoints provided by the Location History APIs.

Read this blog
Creating a Real-Time Construction Fleet Planning App with TomTom Maps APIs

Creating a Real-Time Construction Fleet Planning App with TomTom Maps APIs

Learn how to build a construction fleet planning application using TomTom’s Routing API with its Calculate Route method to calculate the possible routes, the Location History API to track a vehicle location, and the Geofencing API to determine when construction vehicles are close to the site.

Read this blog

Location History API services

Important note:


Before a customer can use Location History endpoints they must register.

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

Libraries of objects

For Location History to work, you need to create a library of your objects and optionally define their attributes.

Features

The following features are included in the Location History API.

  • A Location History service.
  • Location History configuration that is securely stored by TomTom in the cloud.

Current limits include:

  • 1k objects
  • Location history is kept as active data for 3 months.
  • Location history is kept as a cold archive 6 months after the active period.

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

Services with endpoints

Configuration service

The Configuration service is responsible for managing one's options. It is essential to create and work with one's account.

  • POST Register Admin Key
  • POST Regenerate Admin Key
  • POST Change customer secret

Objects service

The Objects service provides a client-side reporting device acting as a representation of the item to be geofenced.

  • GET List objects
  • GET Get object details
  • POST Add new object
  • PUT Edit object
  • DELETE Delete object

Position History service

The Position History service provides tools for managing objects' location data.

  • DELETE Clear objects position history
  • GET Get objects position history
  • GET Last position
  • POST Send position

Archive service

The Archive service is a tool for downloading user's data in a single, compressed file.

  • GET Archive structure
  • GET Archive historical positions
  • GET Download prepared data

Interactions with other APIs

Geofencing API

The Location History API and Geofencing 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 Location History API view, the name and properties fields are available for an Object.

The Location History API and Geofencing API share the consentForStoringObjectsPositionsHistory setting. When this setting is set to true both services can save an Objects' positions. Positions saved from the Geofencing API and Location History API are available from the Location History API endpoints.

Quick start guide

Configuration

Your API and Admin Keys

You need to have two keys to work with Location History:

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

Getting started

Follow these steps to start working with the Location History 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.

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 within the Location History API.

Note: Constants and parameters enclosed in curly brackets { } must be replaced with their values.

Register for your Admin Key using this URL:

URL request example - HTTP Method: POST

post
URL request example
1https://api.tomtom.com/locationHistory/1/register?key={Your_API_Key}
2{
3  "secret": "your_secret"
4}

or use the POST curl command. See the following example:

post
curl command request example
1curl -XPOST "Content-type: application/json" -d
2'{
3   "secret": "your_secret"
4 }'
5'https://api.tomtom.com/locationHistory/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 - JSON
1{
2  "adminKey": "ooCP41LoslEhThwNPyCFjtTsgCDyJgTaoz9JJFpVJvW8MjA3"
3}

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

Step 3. Creating objects

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

URL request example

post
URL request example
1https://api.tomtom.com/locationHistory/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/locationHistory/1/objects?key={Your_API_Key}&adminKey={Your_Admin_Key}'

Step 4. Register an object's position

Each object can report its current position using the Position History service Send position endpoint.

URL request example

post
URL request example
1https://api.tomtom.com/locationHistory/1/history/positions?key={Your_API_Key}
2{
3  "type": "Feature",
4  "geometry": {
5    "type": "Point",
6    "coordinates": [
7      4.909934,
8      52.377607,
9      0
10    ]
11  },
12  "object": "{Your_Object_Id}"
13}

curl command request example

post
curl command request example
1curl -v -XPOST -H "Content-type: application/json" -d
2'{
3  "type": "Feature",
4  "geometry": {
5    "type": "Point",
6    "coordinates": [
7      4.909934,
8      52.377607,
9      0
10    ]
11  },
12  "object": "{Your_Object_Id}"
13}'
14'https://api.tomtom.com/locationHistory/1/history/positions?key={Your_API_Key}'

Step 5. Getting an object's position history

Historical positions can be retrieved using the Get objects position history endpoint.

URL request example

get
URL request example
https://api.tomtom.com/locationHistory/1/history/positions/{Your_Object_Id}?key={Your_API_Key}&from=2019-08-27T12AM

curl command request example

get
curl command request example
curl 'https://api.tomtom.com/locationHistory/1/history/positions/{Your_Object_Id}?key={Your_API_Key}&from=2019-08-27T12AM'

Roles in Location History

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

Entity

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 located (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 Location History 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 Location History

Entities are manageable elements within the Location History API.

Entity

Description

Point

The object's coordinate on earth, obtained by GPS sensors or otherwise.

Configuration

A series of 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.

Position

An object's historical location representation that contains the following information for a specified object:

  • Location record time.
  • A point representing a recorded position.
  • An object's estimated speed.
  • An object's estimated direction as a north-based azimuth.
Customer key1 ——— 1Configuration1 ——— 0..*Object1..* ——— 0..*Position

Rights in Location History

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

Legend to the following data table

  • (C)reate: an entity can create new objects.

  • (R)ead: an entity can get details about an object, generate position reports and send current position.

  • (U)pdate: an entity can change attributes and properties of objects.

  • (D)elete: an entity can delete objects and location history data.

     

    Object

    Archive

    CRUDCR

    Admin

    		++++++

    Requestor/Object

    		-+----