Introduction

What is TomTom's Notifications API?

The Notifications API and its services provides the ability to read and clear the history of sent notifications. If you wish to stop receiving any notifications from the Notifications API services, please contact our Support and provide the address you wish to unsubscribe. See the Contact Groups documentation page for further information on the Contact Groups API. TomTom's Notifications service is intended to manage communication from Maps APIs to users. The following means of contact are supported:

• webhooks
• e-mails

Current limits include:

• 20 webhook addresses per Contact Group.
• 20 e-mail addresses per Contact Group.

Benefits of using the Notifications API

The main benefit of choosing contact groups is that it can contain a single address or multiple addresses. When the same contact group has been used in multiple APIs and a change occurs in the way of communication in this group, then this change will appear in all APIs where this group is being used.

Services with endpoints

Getting Started

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

---

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.Follow these instructions.

---

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 BaseOpen the Knowledge Base

---

Using Data Science to Analyze and Visualize TomTom Notification Data

The TomTom flexible Notifications API service enables emails or webhooks to send Maps API data to an application. Webhooks are automated messages that send information when events happen. This allows us to start filling a database with valuable data, like whenever a delivery vehicle or taxi driver crosses a geofence, for example.

Read this blogRead this blog

---

Leverage Routing, Geofencing, and Notifications APIs to Send ETA Alerts

A good user experience includes timely notifications. Customers want alerts when their ride, food, or groceries are nearby, without having to constantly refresh their phone. This article will explore how you can create these essential tracking and notification functions using TomTom’s Routing, Geofencing, and Notifications APIs.

Read this blogRead this blog

Follow these steps to start working with the Notifications API.

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

Step 1. Register for an API Key

You need to have an API Key to work with Notifications. This allows you to work with any TomTom Maps API, including Notifications. This key will let you read data from the service, such as notification history.

Step 2. Create a Contact Group

A Group must be added with at least one way to send notifications. A Group is created using the Group service Create contact group endpoint.

URL example

1https://api.tomtom.com/notifications/1/groups?key={Your_API_Key}
2{
3  "name": "A contact group name",
4  "webhookUrls": ["http://www.example.com/"]
5}

curl command example

1curl -XPOST "Content-type: application/json" -d
2'{
3  "name": "A contact group name",
4  "webhookUrls": ["http://www.example.com/"]
5 }'
6'https://api.tomtom.com/notifications/1/groups?key={Your_API_Key}'

The endpoint returns contact group details including a group id.

Response body

1{
2  "id": "715c17e3-b5b8-47c7-ba0d-b2873f1dca1e",
3  "name": "Tutorial group",
4  "webhookUrls": ["http://www.example.com/"]
5}

This group id can be used for future calls (i.e., editing or deleting a group).

Step 3. Receive notification

Notifications can be sent by other TomTom services. They only need the id of the group which should receive notifications.

When notification has been received

Managing notifications

You need to have an API Key to work with Notifications. This allows you to work with any TomTom Maps API, including Notifications.

Follow these steps to start working with the Notifications API.

Step 1. Get notifications history

Notifications that have been sent by TomTom Services can be listed by using the List notifications history endpoint. History is kept for 7 days and after that time it will be automatically deleted.

URL format

https://api.tomtom.com/notifications/1/history?key={Your_API_Key}&from={TIMESTAMP}

The endpoint returns a list of the sent notifications.

curl command format

curl 'https://api.tomtom.com/notifications/1/history?key={Your_API_Key}&from={TIMESTAMP}'

TMESTAMP is an ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss), for example 2020-05-01T19:37:00.

Response body

1{
2  "summary": {
3    "from": "2020-05-01T19:37:00",
4    "to": "2020-05-02T19:37:00"
5  },
6  "notifications": [
7    {
8      "title": "Tutorial",
9      "body": "How to use notifications",
10      "contact": {
11        "type": "GROUP",
12        "value": "715c17e3-b5b8-47c7-ba0d-b2873f1dca1e"
13      },
14      "status": {
15        "type": "SUCCESS",
16        "details": "OK"
17      },
18      "sendDate": "2020-05-01T21:03:46+0000"
19    }
20  ],
21  "resultInfo": {
22    "maxResults": 100,
23    "pageNumber": 1,
24    "itemsCount": 1
25  }
26}

Step 2. Clear notifications

Notification history can be cleared by using Clear notifications history endpoint.

URL example

https://api.tomtom.com/notifications/1/history?key={Your_API_Key}

curl command example

curl -XDELETE 'https://api.tomtom.com/notifications/1/history?key={Your_API_Key}'

Response body

1{
2  "deleteAllHistoryMessagesBefore": "2020-05-01T19:37:00",
3  "deleteAllHistoryMessagesBeforeStatus": "PROCESSING"
4}

This means that the clearing of notifications history has been started. All notifications before 2020-05-01T19:37:00 will be deleted.