Adding EV Routing to a TomTom Web Map: Understanding the APIs

TomTom Developer Portal

May 28, 2020 · 9 min read

By 2040, more than half of all vehicles sold are expected to be electric. But today, Electric vehicle (EV) owners often struggle to plan trips that ensure timely and convenient access to charging facilities. In this article, the first part of a series, we'll explore how developers can use the EV Routing Service to easily create engaging and helpful applications that help EV owners plan travel routes that include charging stops.

By the year 2040, 57% of passenger vehicles sold will be electric, according to a recent BloombergNEF report (Source: BloombergNEF). Today, consumers continue to struggle to plan trips that ensure timely and convenient access to charging facilities — due in large part to navigation software that lacks the routing services needed by electric vehicle (EV) drivers.

Thankfully, TomTom is helping EV owners avoid "range anxiety" with its award-winning Long-Distance EV Routing service. In this two-part article, we'll explore how developers can use the EV Routing service to easily create engaging and helpful applications for consumers. We’ll start in Part 1 with a look at the relevant APIs, and explore information particular to EVs. In Part 2, we’ll build an app that allows the user to specify a starting and finishing location, calculate a route between these endpoints, and display both the route and charging stops along the way.

To use TomTom's services, you’ll need to obtain an API key that authorizes their use. In the code and URLs that follow, just be sure to replace "YOUR_API_KEY" with the TomTom API Key you obtained.

You should also log in to the TomTom developer dashboard, edit your application, and make certain that all of the necessary TomTom products (such as the Search API and Extended Search API) are checked.

Now let’s look at the various APIs we’ll use to create the app.

Search API

In order to use the TomTom Routing API or the Long Distance EV Routing service, the unique starting and ending locations the route will connect are required. The Search API provides a powerful mechanism for turning a user's colloquial input (for example, Los Angeles) into a unique location (such as latitude 34.05224 and longitude -118.24334).

That mechanism is TomTom's Fuzzy Search service. To search for "Los Angeles" you can make a simple web request to the following URL:

https://api.tomtom.com/search/2/search/los%20angeles.json?key=YOUR_API_KEY

The response would appear as follows, with the "position" property of the first result providing the latitude and longitude of the city.

{
  "summary": {
    "query": "los angeles",
    "queryType": "NON_NEAR",
    "queryTime": 47,
    "numResults": 10,
    "offset": 0,
    "totalResults": 28490,
    "fuzzyLevel": 1
  },
  "results": [
    {
      "type": "Geography",
      "id": "US/GEO/p0/355711",
      "score": 5.90292,
      "entityType": "Municipality",
      "address": {
        "municipality": "Los Angeles",
        "countrySecondarySubdivision": "Los Angeles",
        "countryTertiarySubdivision": "Los Angeles",
        "countrySubdivision": "CA",
        "countryCode": "US",
        "country": "United States",
        "countryCodeISO3": "USA",
        "freeformAddress": "Los Angeles, CA",
        "countrySubdivisionName": "California"
      },
      "position": {
        "lat": 34.05224,
        "lon": -118.24334
      },
      "viewport": {
        "topLeftPoint": {
          "lat": 34.33673,
          "lon": -118.6684
        },
        "btmRightPoint": {
          "lat": 33.70366,
          "lon": -118.15541
        }
      },
      "boundingBox": {
        "topLeftPoint": {
          "lat": 34.33673,
          "lon": -118.6684
        },
        "btmRightPoint": {
          "lat": 33.70366,
          "lon": -118.15541
        }
      },
      "dataSources": {
        "geometry": {
          "id": "00005543-3600-3c00-0000-00005a3f4260"
        }
      }
    },
    .
    .
    .
  ]
}

For web developers, TomTom also offers a Web SDK to simplify interaction with its APIs. This API provides a simple-to-call function for most services. These functions typically format the URL, issue the web request, fetch and parse the response, and return a JavaScript promise with which you can interact.

For example, the following function call is equivalent to the earlier Fuzzy Search example. If the web request succeeds, the JavaScript promise’s “then” function is called with a simple object containing the response; otherwise, its “catch” function is called with information describing the error.

tt.services.fuzzySearch({ key: 'YOUR_API_KEY', query:  'Los Angeles' })
  .go()
  .then(function(response) {
    console.log('Success!');
    console.log(response);
  })
  .catch(function(error) {
    console.log('Error!');
    console.log(error);
  });

Routing API

TomTom offers a Routing API that calculates a route between two endpoints. The Routing API takes real-time traffic information and weather incidents into account to help consumers avoid delays. This powerful API now includes the Long-Distance EV Routing service, which allows consumers to provide detailed information about their electric vehicles and get a route specifically calculated to ensure that charging stations are available along the way.

To use the service, you’ll need to understand basic information that may be necessary when creating apps for electric vehicles. Unfortunately, the information provided by automobile manufacturers and reviewers often includes abbreviations that are used with little or no explanation. In the table below, you'll find a glossary of some common abbreviations used in the description of electric vehicles.

| Abbr | Meaning | Description | | A | Amperes | Amperage is a measure of electric current — the quantity of electric charge moving across a circuit in a given period of time. Using plumbing as an analogy, it’s similar to flow rate. | | V | Volts | Voltage is a measure of electromotive force. It measures the force driving the electric charge across a circuit. Again, using plumbing as an analogy, it’s similar to water pressure. | | AC | Alternating Current | With alternating current, electric current alternates directions at regular intervals. When you plug something in at home or at work, power is delivered via alternating current. | | DC | Direct Current | With direct current, electric current flows in a single direction. Battery-operated devices run on direct current. In truth, most devices run on direct current. Plug-in devices simply take an extra step, first converting the alternating current from your wall plug into the direct current they require. | | W | Watts | Wattage is a measure of the total power. It’s calculated quite easily by multiplying voltage by amperage (W = V x A). | | kW | Kilowatts | One kilowatt is a thousand watts (kW = W / 1000). | | kWh | Kilowatt Hours | A kilowatt-hour is a measure of power over time. For example, 1 kilowatt-hour could deliver a single kilowatt of power for an entire hour, 500 watts for two hours, or 1 watt for 1,000 hours. | | SoC | State of Charge | The state of charge (SoC) is a measure of the percentage of charge in a battery, ranging from 0 (empty) to 1 (full). For example, an SoC of 0.5 would indicate that a battery is at 50%. | | PEV | Plug-in Electric Vehicle | A plug-in electric vehicle is any vehicle that can be plugged in to charge the battery. It includes both battery-electric vehicles (BEV) and plug-in hybrid electric vehicles (PHEV). | | BEV | Battery Electric Vehicle | A battery-electric vehicle runs entirely on battery power. It does not use gasoline. | | PHEV | Plug-in Hybrid Electric Vehicle | A plug-in hybrid electric vehicle runs on either battery power or gasoline. It can be refueled either by adding gasoline or by plugging in to recharge the battery. |

There are also a number of parameters used as inputs to the service. The first is the consumption model, which describes the battery capacity of the vehicle, how quickly it discharges, and how it behaves under various driving conditions (such as acceleration).

Another set of inputs to this service describes the charging model — the different modes of charging supported by the electric vehicle. This includes the type of plug (or connector), the type of electrical facility, and the rate at which the vehicle will charge when a particular combination of plug and facility is used. Thankfully, TomTom has provided a very flexible model for specifying this information that accommodates virtually any vehicle. Here’s a bit more detail:

The plug type describes the physical connection between the car and the charging station. While some common plug types are emerging (such as SAE J1772), there remains a patchwork of different connectors that often depend on automobile manufacturer or geographical location.
The facility type describes the electrical characteristics of the port at the charging station. A single plug may allow a connection with different ports, each with different electrical characteristics, including the type of current (alternating or direct), the voltage (120V or 240V), the amperage (12A or 20A), and (for AC connections) the number of phases (1 or 3).
The charging curve describes how a particular vehicle will charge at a facility, given its specific characteristics. The rate at which batteries charge depends principally on the facility type and the unique charging circuitry of the vehicle. However, batteries don’t necessarily charge in a linear fashion. They generally charge more quickly when empty and less quickly as they approach a full charge.

To provide accurate estimates of charging times, the TomTom API lets you use the unique charging curve of the vehicle when connected to a specific pairing of plug type and facility type.

Using the Long-Distance EV Routing Service

The Long Distance EV Routing service calculates a route between an origin and a destination that includes charging stops. The consumption model and many other parameters are passed as simple query string parameters in the URL for the web request.

For example, when accompanied by a POST body that specifies charging modes, the URL below calculates the route between Boston (latitude 42.35899, longitude -71.05863) and Washington D.C. (latitude 38.89206, longitude -77.01991), making certain that the route includes charging stops so that the remaining battery charge never drops below 20 kWh. The consumption model specifies an electric vehicle that’s fully charged to its maximum capacity of 100 kWh. It further indicates that when traveling at a constant speed of 100 km/h, the vehicle will consume 20 kWh of battery charge for every 100 kilometers of travel.

https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/42.35899,-71.05863:38.89206,-77.01991/json?vehicleEngineType=electbric&maxChargeInkWh=100&currentChargeInkWh=100&constantSpeedConsumptionInkWhPerHundredkm=100,20&minChargeAtDestinationInkWh=20&minChargeAtChargingStopsInkWh=20&key=YOUR_API_KEY

The charging modes are passed in the body of a POST web request. The example below uses an SAE J1772 plug that can be connected to a single-phase alternating current at 200-240 volts, at 32 amperes or above. When connected, the vehicle will charge to 80kWh in 25,000 seconds, reaching a full charge of 100kWh in 50,000 seconds.

{
  "chargingModes": [
    {
      "chargingConnections": [
        {
          "facilityType": "Charge_200_to_240V_1_Phase_at_32A",
          "plugType": "SAE_J1772"
        },
        {
          "facilityType": "Charge_200_to_240V_1_Phase_above_32A",
          "plugType": "SAE_J1772"
        }
      ],
      "chargingCurve": [
        {
          "chargeInkWh": 80,
          "timeToChargeInSeconds": 25000
        },
        {
          "chargeInkWh": 100,
          "timeToChargeInSeconds": 50000
        }
      ]
    }
  ]
}

A successful response includes a route summary, the legs of the route, a summary of each leg, and the points (latitude and longitude) that make up that leg. The route is broken up into legs so that each charging stop can be represented. The charging stop (or destination) appears as the final point in each route leg. Here’s an excerpt from an example response:

{
  "formatVersion": "0.0.12",
  "routes": [
    {
      "summary": {
        "lengthInMeters": 713569,
        "travelTimeInSeconds": 64578,
        "trafficDelayInSeconds": 0,
        "departureTime": "2019-10-14T09:16:54-04:00",
        "arrivalTime": "2019-10-15T03:13:12-04:00",
        "batteryConsumptionInkWh": 142.71380000000002,
        "remainingChargeAtArrivalInkWh": 21.01679999999999,
        "totalChargingTimeInSeconds": 39266
      },
      "legs": [
        {
          "summary": {
            "lengthInMeters": 318653,
            "travelTimeInSeconds": 11640,
            "trafficDelayInSeconds": 0,
            "departureTime": "2019-10-14T09:16:54-04:00",
            "arrivalTime": "2019-10-14T12:30:54-04:00",
            "batteryConsumptionInkWh": 63.7306,
            "remainingChargeAtArrivalInkWh": 36.2694,
            "chargingInformationAtEndOfLeg": {
              "targetChargeInkWh": 100,
              "chargingTimeInSeconds": 39266,
              "chargingConnections": [
                {
                  "facilityType": "Charge_200_to_240V_1_Phase_at_32A",
                  "plugType": "SAE_J1772"
                }
              ],
              "chargingParkUuid": "2cfb40b9-66ed-3afd-4a01-b5ba00153b86"
            }
          },
          "points": [
            {
              "latitude": 42.35899,
              "longitude": -71.05864
            },
            ...

In this article, we’ve looked at the TomTom Long Distance EV Routing service and discussed what you need to know to create an application that uses the service to supply routing and charging information to electric vehicle users.

In part two of this article, we’ll create an app that lets users specify a starting and ending point, calculates a route between them, and shows charging stops along the route.

To get started with what was covered in this article and learn more about some of TomTom's products, check out some of the links below:

Happy coding!

#routing #search #code

APIs & SDKs

Developers

Support

Legal