With TomTom’s recent announcement of expanded access to their APIs, as well as an increased adoption of electric vehicles, developers have incredible opportunities to meet the needs of consumers with innovative and useful applications.
In this article, I’m going to introduce you to API functionality which can be leveraged specifically for drivers of electric vehicles. Owners and potential owners of electric vehicles may face "range anxiety"—and the primary causes of this anxiety include the owner's uncertainty over the expected range from a single charge, and how the type of route effects that range.
I’ll talk briefly about how to get started with the TomTom APIs and demonstrate which APIs you can leverage to provide consumers of your application with answers to questions like:
- Can I reach my destination with my current charge?
- Are these estimates accurate for my car?
- What is the most economical route to reach my destination?
Getting Started with the TomTom Maps APIs
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.
You’ll need to set the name for your application and select all TomTom products that your application requires to access the necessary functionality. The product we’ll be referencing in this article is Routing API, so if you’re following along, be sure to check that box.
Fig. 2 Creating a New Application
Applications are approved quickly and appear on your dashboard. The entry shows the Consumer API Key, and information about your application, including the approval status of the application, and each of the products it uses.
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:
Fig. 3 Application Details
The dashboard also allows you to see any credits you have on your account and metrics related to your API transactions. The TomTom free tier allows 2,500 transactions per day, which provides plenty of opportunity for exploration, development, and testing.
Building Your First Reachable Range Request
Now that we have an API key, we can send a request to the Routing API. For these examples, I’ll be using GET requests and requesting responses in JSON format. The endpoints also accept POST requests and can return XML-formatted responses. (I’ll provide links at the end of the article where you can get additional information on how to change your requests to support these use cases.)
The reachable range requires a starting point which is included as part of the URL, as a pair of latitude and longitude coordinates. I’ll be using the rental car counter at the Portland Oregon International Airport (PDX), which is located at:
- Latitude: 45.5868227
- Longitude: -122.5937596
To complete this request, we’ll also need our API Key, and to define key parameters for the range calculation engine to use. We’re trying to determine the range for an electric vehicle, so we’ll be passing in the parameter energyBudgetInkWh. We’ll also need to add some additional information, but let’s work through it step by step.
The current version of the routing API is 1, so our base URL is:
https:
Fig. 4 Base URL
The first things we need to add are the starting point for our route, the format of the response or return type, and our API key. The starting point and the return type are passed in as path parameters as part of the URL. We’ll set the return type to be JSON. The API key is passed in as a query parameter.
We’ll also need to explicitly state the type of engine we’re using in an electric vehicleEngineType. Setting the engine type indicates to the API that the energy consumption model we’re using is electric-based. We’ll work on the consumption model next, but so far, our URL should look similar to the one below.
https:
Fig. 5 Base URL with Starting Point, Return Type, API Key, and Engine Type
The API also needs to know our energy budget and the energy consumption model used by our car, and it expects these values in metric format. The first value should be easy to get as it’s the kWh available within the vehicle, but we may need to do a little math for the second number. We need to provide energy consumption in pairs of speed in km/h and energy consumption in kWh for 100km.
If you’ve tracked the fuel or energy consumption of your vehicle, you’ll know that the numbers can vary based on terrain, speed, load and even your driving habits. We’ll look at how to receive better results from the API in the next section, but to get an average idea, we’re going to calculate this based on the EPA-provided fuel consumption numbers.
Let’s assume we’re driving the 2018 Nissan Leaf with a 40 kWh battery, and EPA-calculated fuel consumption of 125 MPGe City and 100 MPGe Highway. Based on what I was able to find out about the EPA tests, city driving is generally equivalent to an average speed of approximately 20mph, and highway driving is equivalent to an average speed of approximately 50mph. These values convert to approximately 30km/h and 80km/h respectively. We’ll be using the numbers for the first number of the pair for each parameter.
One MPGe is the equivalent of using 33.7kWh to travel one mile. Let’s start with the City driving number—125 MPGe means that if the car travels 125 miles, it’ll use 33.7kwh. If we convert 125 miles into kilometers we get 201.16, and then if we divide 33.7 by 201.16 and multiply it by 100, we’ll get the energy consumption over 100km. The result of this calculation is an energy consumption estimate of 16.75kWh of 100km. So our first pair is {30, 16.75}.
We’ll repeat the calculation for Highway driving—100 works out to be 160.93km. Divide 33.7 by this number and multiply it by 100, and we get our second result of 20.94, giving us a second pair of {80, 20.94}
We pass this data to the API as a series of comma-separated pairs within the URL, separated from each other by colons. Depending on how you’re building the URL, you may also need to encode the data. I’ll include both the unencoded and the encoded URLs we just built below.
https:
Fig. 6 Final URL with All Required Parameters (Unencoded)
https:
Fig. 7 Final URL with All Required Parameters (Encoded)
Understanding the Response
The response generated by TomTom’s range calculation engine is a collection of points which can be used to trace a perimeter around the starting location, indicating the maximum range for the vehicle.
{
"formatVersion": "0.0.1",
"copyright": "Copyright 2018 TomTom International BV. ...",
"privacy": "TomTom keeps information that tells us how ...",
"reachableRange": {
"center": {
"latitude": 45.58671,
"longitude": -122.59387
},
"boundary": [
{
"latitude": 46.61204,
"longitude": -122.62502
},
...
{
"latitude": 46.60672,
"longitude": -122.47402
}
]
}
}
Fig. 8 Example Response from the Route Range API
You can use this data in a couple of ways. If you’re developing a visual tool, you could plot each of these points on a map, and color the area within them where the user can expect to travel without range anxiety.
You could also save the values in a map within your application, and as the user selects locations or points of interest, a function could take the destination and the range map and determine if the destination falls within the boundaries of the reachable range.
Additional Ways to Tune Your Request for Better Accuracy
The API includes a plethora of additional parameters that can be used to determine the range of the vehicle more accurately. Each of these parameters is explained with examples in the Routing API Documentation. In addition to tuning the parameters on the consumption model we discussed above, you can also include the following parameters for a more accurate range.
vehicleWeight - a positive integer in kilograms. It is used in conjunction with the following efficiency parameters:
accelerationEfficiencydecelerationEfficiencyuphillEfficiencydownhillEfficiency
auxiliaryPowerInkWh - The amount of energy consumed by AC, radio, lights, and heating.currentChargeInkWh/maxChargeInkWh - Used together to provide a better understanding of the current state of the battery.
Routing Within the Range
Also within the Routing API is the ability to determine and calculate routes between locations. Routes are passed into the URL as path parameters, as two pairs of latitude and longitude values. Query parameters such as routeType allow the request to customize the fastest route based on speed to arrival, shortest route based on distance, or eco, which finds the route which will best extend the range of the vehicle involved.
Like the reachableRange API, the calculateRoute API is included in the Online Routes product, and is well documented in the Routing API Documentation.
More Information
If you need to explore different use cases or would like to learn more about the Routing API, TomTom has provided the following resources which you’ll find useful. If you find yourself needing more information, such as the current version of the API, or understanding of the data, including in requests and responses, these resources are excellent places to start.
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 API 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.
