Route Planning with TomTom Maps APIs

Add personalized route calculations for your app using TomTom Maps APIs. This tutorial goes over how to create the fastest, shortest and most economical routes for users.

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.

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://api.tomtom.com/routing/1/calculateRoute/47.460858,-122.292098:47.595409,-122.328979/json?key=ReplaceWithYourAPIKeyHere

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://api.tomtom.com/routing/1/calculateRoute/47.460858,-122.292098:47.595409,-122.328979/json?key=ReplaceWithYourAPIKeyHere&routeType=eco

I mapped the results from the query above for each of the route types so that you can compare them. In hindsight, there aren’t many travel options between those two locations.

| 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://api.tomtom.com/routing/1/calculateRoute/47.460858,-122.292098:47.595409,-122.328979/json?key=ReplaceWithYourAPIKeyHere&routeType=fastest&vehicleEngineType=combustion&constantSpeedConsumptionInLitersPerHundredkm=80,6.92

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://api.tomtom.com/routing/1/calculateRoute/47.460858,-122.292098:47.595409,-122.328979/json?key=ReplaceWithYourAPIKeyHere&routeType=fastest&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=30,16.75:80,20.94 

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.

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.

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.