Long Distance EV Routing

Service version: 1.0
Last edit: 2019.12.11

On this page

Purpose

The Long Distance EV Routing service calculates a route between a given origin and destination. The route contains charging stops that have been added automatically based on the vehicle's consumption and charging model.

• Each charging stop results in an additional leg in the route response.
• Each additional leg contains a chargingInformationAtEndOfLeg element in its leg summary.
• Both the route summary and the leg summary include a remainingChargeAtArrivalInkWh element.
• The route summary includes a totalChargingTimeInSeconds element.

The chargingInformationAtEndOfLeg field consists of:

• target battery charge
• charging time
• details about the charging stop

Differences to calculateRoute

This document assumes familiarity with the Calculate Route service and only describes how calculateLongDistanceEVRoute differs from it.

Prerequisites for Long Distance EV Routing support

There are two important prerequisites needed that differ from the Calculate Route service:

• The Electric Consumption Model must be set.
• At least one chargingMode must be supplied in the Request.

Unsupported calculateRoute features

As opposed to the Calculate Route service, the following features are not supported in Long Distance EV Routing:

• Route reconstruction:
  • Reconstruction of a reference route (given by a supportingPoints section in the POST data) is not supported.
    Consequently, the parameters minDeviationDistance and minDeviationTime are not supported.
• Waypoints:
  • The locations must contain exactly two points, the origin and the destination. Waypoints, and consequently the parameter computeBestOrder and the option routeRepresentation=none, are not supported.
• routeType values other than fastest are not supported.
• Alternative routes:
  • maxAlternatives and alternativeType are not supported.
• Instructions
  • instructionType and language are not supported.
• arriveAt is not supported.
• travelMode values other than car are not supported.
• computeTravelTimeFor is not supported.
• Long Distance EV Routing only supports json as the content type for its POST payload and encoding for its Response.

Request data

HTTPS method: POST

URL example

For ease of viewing and identification:

• Required constants and parameters are shown in bold text.
• Optional parameters are shown in plain text.

https://baseURL/routing/versionNumber/calculateLongDistanceEVRoute/locations/json?
key=Your_API_Key
&vehicleEngineType=vehicleEngineType
&constantSpeedConsumptionInkWhPerHundredkm=ElectricConstantSpeedConsumptionPairs
&currentChargeInkWh=float
&maxChargeInkWh=float
&minChargeAtDestinationInkWh=float
&minChargeAtChargingStopsInkWh=float
&callback=callback
&vehicleHeading=integer
&sectionType=sectionType
&report=effectiveSettings
&departAt=time
&traffic=boolean
&avoid=avoidType
&vehicleMaxSpeed=vehicleMaxSpeed
&vehicleWeight=vehicleWeight
&vehicleAxleWeight=vehicleAxleWeight
&vehicleLength=vehicleLength
&vehicleWidth=vehicleWidth
&vehicleHeight=vehicleHeight
&vehicleCommercial=boolean
&vehicleLoadType=vehicleLoadType
&accelerationEfficiency=float
&decelerationEfficiency=float
&uphillEfficiency=float
&downhillEfficiency=float
&auxiliaryPowerInkW=float

Example

https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/52.507,13.492:50.104,8.624/json?key=Your_API_Key&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01&currentChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&minChargeAtChargingStopsInkWh=4

curl command

curl -X POST 'https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/52.507,13.492:50.104,8.624/json?key=Your_API_Key&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01&currentChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&minChargeAtChargingStopsInkWh=4'\
  -H 'Content-Type: application/json' -d '{
  "chargingModes": [
    {
      "chargingConnections": [
        {
          "facilityType": "Charge_380_to_480V_3_Phase_at_32A",
          "plugType": "IEC_62196_Type_2_Outlet"
        }
      ],
      "chargingCurve": [
        {
          "chargeInkWh": 6,
          "timeToChargeInSeconds": 360
        },
        {
          "chargeInkWh": 12,
          "timeToChargeInSeconds": 720
        },
        {
          "chargeInkWh": 28,
          "timeToChargeInSeconds": 1944
        },
        {
          "chargeInkWh": 40,
          "timeToChargeInSeconds": 4680
        }
      ]
    },
    {
      "chargingConnections": [
        {
          "facilityType": "Charge_200_to_240V_1_Phase_at_10A",
          "plugType": "Standard_Household_Country_Specific"
        }
      ],
      "chargingCurve": [
        {
          "chargeInkWh": 6,
          "timeToChargeInSeconds": 15624
        },
        {
          "chargeInkWh": 12,
          "timeToChargeInSeconds": 32652
        },
        {
          "chargeInkWh": 28,
          "timeToChargeInSeconds": 76248
        },
        {
          "chargeInkWh": 40,
          "timeToChargeInSeconds": 109080
        }
      ]
    }
  ]
}
'

Request parameters

The following table only describes the parameters of calculateLongDistanceEVRoute that differ from the calculateRoute endpoint.

• Required parameters must be used or the call will fail.
• There are no optional parameters specific to calculateLongDistanceEVRoute.

POST Request body format (json)

{
  [...],
  "chargingModes" : [
    {
      "chargingConnections" : [
        {"facilityType" : "Charge_200_to_240V_1_Phase_at_32A", "plugType" : "CHAdeMO"},
        {"facilityType" : "Charge_380_to_480V_3_Phase_at_16A", "plugType" : "CHAdeMO"}
      ],
      "chargingCurve" : [
        {"chargeInkWh" : 1.0, "timeToChargeInSeconds" : 300},
        {"chargeInkWh" : 2.1, "timeToChargeInSeconds" : 500},
        {"chargeInkWh" : 10.0, "timeToChargeInSeconds" : 3100}
      ]
    },
    {
      "chargingConnections" : [
        {"facilityType" : "Charge_200_to_240V_1_Phase_at_10A", "plugType" : "Standard_Household_Country_Specific"},
        {"facilityType" : "Charge_100_to_120V_1_Phase_at_16A", "plugType" : "CHAdeMO"}
      ],
      "chargingCurve" : [
        {"chargeInkWh" : 1.0, "timeToChargeInSeconds" : 600},
        {"chargeInkWh" : 3.0, "timeToChargeInSeconds" : 2000},
        {"chargeInkWh" : 10.0, "timeToChargeInSeconds" : 8000}
      ]
    }
  ]
}

POST Request body parameters

The POST data body must contain a chargingModes json array.

Types for the Long Distance EV Routing service

The following table describes the types that are introduced for the Long Distance EV Routing service. The basic calculateRoute types are listed on the Common Routing Parameters page.

Response data

Response body

A successful Response in JSON format could look like this:

{
  [...],
  "routes": [
    {
      [...],
      "summary": {
        [...],
        "remainingChargeAtArrivalInkWh": 16.5,
        "totalChargingTimeInSeconds": 2542
      },
      "legs": [
        [...],
        {
          [...],
          "summary": {
            [...],
            "remainingChargeAtArrivalInkWh": 12.5,
            "chargingInformationAtEndOfLeg": {
              "targetChargeInkWh" : 30.0,
              "chargingTimeInSeconds" : 2542,
              "chargingConnections" : [
                {"facilityType" : "Charge_380_to_480V_3_Phase_at_32A", "plugType" : "NEMA_5_20"}
              ],
              "chargingParkUuid" : "a4b60dff-b599-339a-0a1b-aae200153b86"
            }
          }
        }
      ]
    }
  ]
}

Response fields

A successful Long Distance EV Routing JSON Response extends the fields specified here as follows: