Planning Your Route with Electric Charging In Mind 

With the popularity electric vehicles developers need to start adding electric mobility options to their location-based applications. This how-to goes over building a reach request and understanding the response

Plan a trip With Your Electric Car in Mind

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?

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://api.tomtom.com/routing/1/calculateReachableRange/

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://api.tomtom.com/routing/1/calculateReachableRange/45.5868227,-122.5937596/json?key=ReplaceWithYourAPIKeyHere&vehicleEngineType=electric 

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://api.tomtom.com/routing/1/calculateReachableRange/45.5868227,-122.5937596/json?key=ReplaceWithYourAPIKeyHere&vehicleEngineType=electric&energyBudgetInkWh=40&constantSpeedConsumptionInkWhPerHundredkm=30,16.75:80,20.94

https://api.tomtom.com/routing/1/calculateReachableRange/45.5868227,-122.5937596/json?key=ReplaceWithYourAPIKeyHere&vehicleEngineType=electric&energyBudgetInkWh=40&constantSpeedConsumptionInkWhPerHundredkm=30%2C16.75%3A80%2C20.94 

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 
     } 
   ] 
 } 
} 

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:

  • accelerationEfficiency

  • decelerationEfficiency

  • uphillEfficiency

  • downhillEfficiency

• auxiliaryPowerInkWh - The amount of energy consumed by AC, radio, lights, and heating. c

• 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.

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.