The TomTom route mapping engine is immensely powerful, and with the recent announcement that the TomTom APIs are available for developers to integrate into their applications, you can now harness the power of the routing engine and share it with your consumers.
In this article, I’m going to introduce you to the Routing API with a few examples. We’ll also discuss consumption models for gasoline and electric vehicles and use these models to plot the best route for your vehicle.
Finally, we’ll talk about the different route types which you can request from the API, and I’ll provide links to additional documentation and tools to help you learn more and take the next steps.
How to Generate Your Personal API Key
The TomTom Developer Portal is where you’ll find everything you need to get up and running with the TomTom APIs. The first thing you’ll want to do is create an account on the portal. From the home page, enter your email address and click on the "Get a free API key" button.
Fig. 1 The TomTom Developer Portal
The next step in the process is to select a username and read through the Terms and Conditions. Your free account supports up to 2,500 free transactions per day. It should be noted that should 2,500 API transactions per day not be enough, more transactions can be purchased by visiting the My Credits screen in the developer dashboard.
An email contains a link to set the password for your account, and with that, you’ll be ready to go. You need to configure an application before you can request an API Key. From your dashboard, click on the "+ Add an App" button.
Applications require a name, and you’ll need to enable the APIs which the application needs to access. For this example, the product we’ll be using is the Routing API product. If you’re following along, select the Routing API product and click on Create App.
Fig. 2 Creating a New Application
Once your application is set up, you can access the API Key from the Keys tab within the application object. The key is labeled the Consumer API Key. Each of the URL calls below contain ReplaceWithYourAPIKeyHere as the key. (You’ll want to replace this with your key.)
This article focuses on how to use the TomTom Routing API, but developers also have access to Web and Mobile SDKs which contain similar functionality. You can learn more about each of the SDKs from the following links:
Calculating the Route
We’re going to explore the API calls an application would make to determine a route between two points. I’ll use the API calls to keep this article as language-agnostic as possible. The APIs return data in XML format by default. I have a personal preference for JSON-formatted data, so we’ll add the necessary parameters to enable this.
For this scenario, let’s consider a situation where we land at the Seattle/Tacoma Airport and rent a car to travel to CenturyLink field. We’ll pretend we’re going to watch the Seahawks play, or attend a concert. We’ll send the locations to the API in the form of latitude/longitude pairs.
- SEATAC Car Rental - 47.460858, -122.292098
- Parking at CenturyLink Field - 47.595409, -122.328979
Let’s start off by identifying the fastest route. We’ll send a GET request to the routing endpoint on the TomTom API. The current routing API version is 1, which is passed in as a path parameter. The starting and ending points are passed in as path parameters as well, and we include the API key as a query parameter.
https:
Fig. 3 API Call to Determine Router Between Two Points
This particular route contains 275 route points, so I’ve included an abridged version below.
{
"formatVersion": "0.0.12",
"copyright": "Copyright 2018 TomTom International BV. ...",
"privacy": "TomTom keeps information that tells us how ...",
"routes": [
{
"summary": {
"lengthInMeters": 19997,
"travelTimeInSeconds": 1003,
"trafficDelayInSeconds": 0,
"departureTime": "2018-09-26T01:07:30-07:00",
"arrivalTime": "2018-09-26T01:24:12-07:00"
},
"legs": [
{
"summary": {
"lengthInMeters": 19997,
"travelTimeInSeconds": 1003,
"trafficDelayInSeconds": 0,
"departureTime": "2018-09-26T01:07:30-07:00",
"arrivalTime": "2018-09-26T01:24:12-07:00"
},
"points": [
{
"latitude": 47.46087,
"longitude": -122.29207
},
...
{
"latitude": 47.5954,
"longitude": -122.32907
}
]
}
],
"sections": [
{
"startPointIndex": 0,
"endPointIndex": 275,
"sectionType": "TRAVEL_MODE",
"travelMode": "car"
}
]
}
]
}
Fig. 4 Abridged Results for the Route
The results provide us with distance and time information, as well as any traffic delays and an expected departure and arrival time. The API also allows you to submit either the departure or the arrival time as a query parameter, in case you would like to explore different options based on time constraints in the future. You can discover how to use these and other options in the Routing API Documentation.
Fastest, Shortest and Most Economical Routes
The API allows the route to be optimized for different criteria. The different route types include:
- Fastest - the fastest route
- Shortest - the shortest route by distance
- Eco - strives to achieve a balance between economy and speed
- Thrilling - the route with the most challenging terrain. Hills and turns are maximized, and highways are avoided.
We can include the route type as an additional query parameter in the URL. Let’s update the original URL to return an economical route.
https:
Fig. 5 Updated Route API Request for the Most Economical Route
I mapped the results from the query above for each of the route types so that you can compare them.
| Route Type | Distance (km) | Time (minutes: seconds) |
| fastest | 19.99km | 16:42 |
| shortest | 16.81km | 22:42 |
| eco | 19.99km | 16:42 |
| thrilling | 16.81km | 22:42 |
Fig. 6 Comparison Between Different Routes
We can achieve more accuracy and identify better routes for the type of vehicle we’re driving if we include more information about the vehicle we’re driving. Let’s consider how we could pass additional information for a car with a traditional internal combustion engine, and an electric vehicle.
Defining a Gas-Based Consumption Model
For this example, let’s look at a BMW 430i. EPA reports indicate that we can expect approximately 34 mpg on the highway. We’ll need to do some calculations to convert these numbers to the metric system. The API expects a combination of the speed and the number of liters for 100 km. When we use an online calculator, we get a liters/100 km value of 6.9.
We need to set our engine type to combustion, and then pass the consumption data in as a consumption pair. If more values are available, each pair is separated by a colon.
https:
Fig. 7 Passing the Consumption Model in for a Combustion Engine
When the result returns, we’ll have an additional data point to consider: fuelConsumptionInLiters (in the summary section) as shown below.
{
...
"routes": [
{
"summary": {
"lengthInMeters": 19997,
"travelTimeInSeconds": 1003,
"trafficDelayInSeconds": 0,
"departureTime": "2018-09-26T02:15:10-07:00",
"arrivalTime": "2018-09-26T02:31:52-07:00",
"fuelConsumptionInLiters": 1.369581
},
...
]
}
Fig. 8 Fuel Consumption Results For the Route
Defining an Electric-Based Consumption Model
The electric consumption is similar, except the values are based on kWh instead of liters per hundred hours. Let’s consider how to create this model if we were driving a 2018 Nissan Leaf with a 40 kWh battery. The values we need to submit are a measure of kWh used over 100 km. Based on some math and a couple of conversions, we can expect the Leaf to use:
- 16.75 kWh over 100 km at a speed of 30 km/h.
- 20.94 kWh over 100 km at a speed of 80 km/h
We need to change the engine type to electric and then include our consumption model in the parameter labeled: constantSpeedConsumptionInkWhPerHundredkm.
https:
Fig. 9 Passing the Consumption Model in for an Electric Engine
The result is similar to the gasoline consumption request, with the kWh required for the route included in the summary section, as shown below.
{
...
"routes": [
{
"summary": {
"lengthInMeters": 19997,
"travelTimeInSeconds": 1003,
"trafficDelayInSeconds": 0,
"departureTime": "2018-09-26T02:28:56-07:00",
"arrivalTime": "2018-09-26T02:45:38-07:00",
"batteryConsumptionInkWh": 4.3892717
},
...
]
}
Fig. 10 Energy Consumption Results For the Route
Additional Options with the Routing API
The consumption models we created above give reasonable estimates for consumption on the selected route, but we can add additional information with our request to tune the results even more. Including this information would be particularly useful in an app which is tethered to a vehicle and can ingest metrics from the vehicle monitoring systems.
The API defines additional parameters you can include in your requests. These parameters include, but are not limited to:
- Acceleration and Deceleration Efficiency
- Vehicle Metrics - Weight, Load Type, Max Speed
- Efficiency - Uphill and Downhill Travel
You can learn more about the Routing API through TomTom’s extensive and detailed documentation. The documentation includes information related to the current version of the API, or the parameters and their associated data types which are included in requests and responses. The following resources are directly related to the Routing API product.
Routing API Explorer
This resource provides implementation details for the API, including which endpoints are available, what parameters to use and what responses to expect from each endpoint. The page also provides you with the opportunity to try out example calls to each endpoint.
Routing Documentation
The Routing API Documentation contains more detailed information about the parameters which are available for each type of route request, the expected format, and what data type each parameter should be. Similar information is provided for the responses as well.
