Location History API Documentation
Service version: 1
Last edit: 2019.11.12
The TomTom Location History API is currently available.
On this page
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.
Purpose
What is TomTom's Location History service?
TomTom's Location History service 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
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
|
|
|
|
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
andproperties
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.
- When this setting is set to
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/fences/projects within the Location History API.
Register for your Admin Key using this URL:
URL format - HTTP Method: POST
https://api.tomtom.com/locationHistory/1/register?key=Your_API_Key
{
“secret”: “your_secret”
}
or use the curl command:
curl command
curl -XPOST "Content-type: application/json" -d
'{
“secret”: “your_secret”
}'
'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:
{
"adminKey": "ooCP41LoslEhThwNPyCFjtTsgCDyJgTaoz9JJFpVJvW8MjA3"
}
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 format
POST https://api.tomtom.com/locationHistory/1/objects?key=Your_API_Key&adminKey=Your_Admin_Key
{
"name": "A Volvo Car"
}
curl command
curl -XPOST "Content-type: application/json" -d
'{
"name": "A Volvo Car"
}'
'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 it's current position using Position History service "Send position" endpoint.
URL format
POST https://api.tomtom.com/locationHistory/1/history/positions?key=Your_API_Key
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
4.909934,
52.377607,
0
]
},
"object": "Your_Object_Id"
}
curl command
curl -v -XPOST -H "Content-type: application/json" -d
'{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
4.909934,
52.377607,
0
]
},
"object": "Your_Object_Id"
}'
'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 "Get objects position history" endpoint.
URL format
https://api.tomtom.com/locationHistory/1/history/positions/Your_Object_Id?key=Your_API_Key&from=2019-08-27T12AM
curl command
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.
|
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:
|
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.
|
Position |
An object's historical location representation that contains the following information for a specified object:
|
Customer key | 1 ——— 1 | Configuration | 1 ——— 0..* | Object | 1..* ——— 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 | |||||||
---|---|---|---|---|---|---|---|---|
C | R | U | D | C | R | |||
Admin |
+ | + | + | + | + | + | ||
Requestor/Object |
- | + | - | - | - | - |