Click here to Skip to main content
13,828,588 members
Click here to Skip to main content
Add your own
alternative version

Tagged as

Stats

2.3K views
9 bookmarked
Posted 10 Jan 2019
Licenced CPOL

Route Calculations with TomTom Maps APIs

, 10 Jan 2019
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.

Editorial Note

This article is in the Product Showcase section for our sponsors at CodeProject. These articles are intended to provide you with information on products and services that we consider useful and of value to developers.

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

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.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Mike Mackrory
United States United States
Mike Mackrory is a Global citizen who has settled down in the Pacific Northwest - for now. By day he works as a Senior Engineer on a Quality Engineering team and by night he writes, consults on several web based projects and runs a marginally successful eBay sticker business. When he’s not tapping on the keys, he can be found hiking, fishing and exploring both the urban and the rural landscape with his kids. Always happy to help out another developer, he has a definite preference for helping those who bring gifts of gourmet donuts, craft beer and/or Single-malt Scotch.

You may also be interested in...

Comments and Discussions

 
-- There are no messages in this forum --
Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web03 | 2.8.190114.1 | Last Updated 10 Jan 2019
Article Copyright 2019 by Mike Mackrory
Everything else Copyright © CodeProject, 1999-2019
Layout: fixed | fluid