Sorry, you need to enable JavaScript to visit this website.

Long Distance EV Routing

 

Service version: 1.0
Last edit: 2019.08.19

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=*****
&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/50.95421,6.90852:52.50825,13.45686/json?key=*****&vehicleEngineType=electric&maxChargeInkWh=10&currentChargeInkWh=10&constantSpeedConsumptionInkWhPerHundredkm=50.0,6.5:100.0,8.5&minChargeAtDestinationInkWh=5.2&minChargeAtChargingStopsInkWh=1.5

curl command

curl -X POST "https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/50.95421,6.90852:52.50825,13.45686/json?key=*****&vehicleEngineType=electric&maxChargeInkWh=10&currentChargeInkWh=10&constantSpeedConsumptionInkWhPerHundredkm=50.0,6.5:100.0,8.5&minChargeAtDestinationInkWh=5.2&minChargeAtChargingStopsInkWh=1.5"\
   -H "Content-type: application/json" -d '{
  "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}
      ]
    }
  ]
}'

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.
Required parameters
Parameter Description
minChargeAtDestinationInkWh
float
The battery level upon arrival at the destination of the resulting route will be at least this much.
Maximum value: maxChargeInkWh
minChargeAtChargingStopsInkWh
float
The battery level upon arrival at each intermediate charging stop of the resulting route will be at least this much.
Maximum value: 0.2 × maxChargeInkWh

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.

Required parameters
Parameter Description
facilityType
string
A string matching a facilityType in the following facilityType values table.
plugType
string
A string matching a plugType in the following plugType values table.
chargeInkWh
float
A battery charge level in kWh. A float in the range (0, maxChargeInkWh].
timeToChargeInSeconds
integer
A time span in seconds. A non-negative integer.
chargingCurveSupportPoint
object
A supporting point of a charging curve consisting of chargeInkWh and timeToChargeInSeconds such that the time it takes to charge the battery from 0kWh to chargeInkWh kWh is given by timeToChargeInSeconds.
chargingCurve
array
A piecewise-linear function which maps a target charge level to the time it takes to charge an empty battery to this level, that is used to compute charging times of the vehicle.

  • It is given by a sequence of at most 10 non-duplicate chargingCurveSupportPoints that are totally, increasingly ordered in timeToChargeInSeconds and chargeInkWh.
  • The last chargeInkWh is maxChargeInkWh.
  • The curve is given by connecting the given points in order after adding the first point:
    {
      "chargeInkWh" : 0.0,
      "timeToChargeInSeconds" : 0
    }
chargingConnection
object
Contains one facilityType and one plugType which are compatible with the vehicle.
chargingConnections
array
A non-empty list of at most 20 unique chargingConnections which result in the same charging curve.
chargingMode
object
Contains chargingConnections and a chargingCurve that describes the charging behavior of the vehicle using the specified charging connections.
chargingModes
array
A non-empty list of at most 10 chargingModes, which the vehicle is able to use to charge. Each chargingConnection appears in at most one chargingMode.

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.

plugType parameter value codes

Possible values for plugType. This list may be extended in the future.

Description
Small_Paddle_Inductive
Large_Paddle_Inductive
IEC_60309_1_Phase
IEC_60309_3_Phase
IEC_62196_Type_1_Outlet
IEC_62196_Type_2_Outlet
IEC_62196_Type_3_Outlet
IEC_62196_Type_1_Connector_Cable_Attached
IEC_62196_Type_2_Connector_Cable_Attached
IEC_62196_Type_3_Connector_Cable_Attached
Combo_to_IEC_62196_Type_1_Base
Combo_to_IEC_62196_Type_2_Base
Type_E_French_Standard_CEE_7_5
Type_F_Schuko_CEE_7_4
Type_G_British_Standard_BS_1363
Type_J_Swiss_Standard_SEV_1011
China_GB_Part_2
China_GB_Part_3
IEC_309_DC_Plug
AVCON_Connector
Tesla_Connector
NEMA_5_20
CHAdeMO
SAE_J1772
TEPCO
Better_Place_Socket
Marechal_Socket
Standard_Household_Country_Specific

facilityType parameter value codes

Possible values for facilityType. This list may be extended in the future.

Description
Battery_Exchange
Charge_100_to_120V_1_Phase_at_8A
Charge_100_to_120V_1_Phase_at_10A
Charge_100_to_120V_1_Phase_at_12A
Charge_100_to_120V_1_Phase_at_13A
Charge_100_to_120V_1_Phase_at_16A
Charge_100_to_120V_1_Phase_at_32A
Charge_200_to_240V_1_Phase_at_8A
Charge_200_to_240V_1_Phase_at_10A
Charge_200_to_240V_1_Phase_at_12A
Charge_200_to_240V_1_Phase_at_16A
Charge_200_to_240V_1_Phase_at_20A
Charge_200_to_240V_1_Phase_at_32A
Charge_200_to_240V_1_Phase_above_32A
Charge_200_to_240V_3_Phase_at_16A
Charge_200_to_240V_3_Phase_at_32A
Charge_380_to_480V_3_Phase_at_16A
Charge_380_to_480V_3_Phase_at_32A
Charge_380_to_480V_3_Phase_at_63A
Charge_50_to_500V_Direct_Current_at_62A_25kW
Charge_50_to_500V_Direct_Current_at_125A_50kW
Charge_200_to_450V_Direct_Current_at_200A_90kW
Charge_200_to_480V_Direct_Current_at_255A_120kW
Charge_Direct_Current_at_20kW
Charge_Direct_Current_at_50kW
Charge_Direct_Current_above_50kW

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:

Field Description
summary
object
A summary of a route or a route leg. In addition to the information provided by the Calculate Route service, it contains the following:

  • remainingChargeAtArrivalInkWh
  • chargingInformationAtEndOfLeg, if it is a leg summary and the leg ends at a charging stop
  • totalChargingTimeInSeconds, if it is a route summary
remainingChargeAtArrivalInkWh
float
The estimated battery charge in kWh upon arrival at the end of the leg or the route.
chargingInformationAtEndOfLeg
object
The chargingInformationAtEndOfLeg object is contained in the leg summary if and only if the leg ends at a charging stop. It contains:

  • targetChargeInkWh
  • chargingTimeInSeconds
  • chargingConnections
  • chargingParkUuid
targetChargeInkWh
float
The charge in kWh to which the battery should be charged.
chargingTimeInSeconds
integer
The estimated time in seconds spent at the charging stop, allowing for some additional time needed to use the charging facility.
chargingConnections
array
A list of chargingConnections, one of which should be used at this charging stop.
chargingConnection
string
Contains one facilityType and one plugType which are compatible with the vehicle.
facilityType
string
An element of the facilityType codes table.
chargingParkUuid
string
The unique identifier of this charging park. This uuid can be used to check the availability of the charging park.
plugType
string
An element of the plugType codes table.
totalChargingTimeInSeconds
integer
The estimated time spent at all charging stops in the route. The travelTimeInSeconds of the route includes the totalChargingTimeInSeconds value.

You are here