Long Distance EV Routing
Purpose
The Long Distance EV Routing service calculates a route between a given origin and destination, passing through waypoints if they are specified. 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
Run this endpoint
You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.
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.
- The Charging Model 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:
- Waypoints
- Circle waypoints are not supported.
- The parameter
computeBestOrder
and the optionrouteRepresentation=none
are not supported. routeType
values other thanfastest
are not supported.
alternativeType
values other thanbetterRoute
are not supported.travelMode
values other thancar
,motorcycle
,bus
, orvan
are not supported.computeTravelTimeFor
is not supported.
Deprecation notice
March 15, 2024
- Value
tollRoad
for the input parametersectionType
as well as the respective response section typeTOLL_ROAD
have been deprecated.- This section will be withdrawn following a 12 months deprecation period.
- The planned withdrawal date is March 15, 2025.
- Following withdrawal, requests for
toll road section
may result in an HTTP 400 error in the response.We recommend using
toll
andtoll vignette
sections instead.
Request data
HTTPS method: POST
- Constants and parameters enclosed in curly brackets { } must be replaced with their values.
- Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.
URL example
1https://{baseURL}/routing/{versionNumber}/calculateLongDistanceEVRoute/{routePlanningLocations}/json?key={Your_API_Key}2&vehicleEngineType={vehicleEngineType}3&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}4¤tChargeInkWh={float}5&maxChargeInkWh={float}6&minChargeAtDestinationInkWh={float}7&minChargeAtChargingStopsInkWh={float}8&callback={callback}9&maxAlternatives={alternativeRoutes}10&minDeviationDistance={integer}11&minDeviationTime={integer}12&vehicleHeading={integer}13§ionType={sectionType}14&report={effectiveSettings}15&departAt={time}16&arriveAt={time}17&traffic={boolean}18&avoid={avoidType}19&prefer={preferType}20&instructionsType={instructionsType}21&language={language}22&chargingStopsStrategy={chargingStopsStrategy}23&vehicleMaxSpeed={vehicleMaxSpeed}24&vehicleWeight={vehicleWeight}25&vehicleAxleWeight={vehicleAxleWeight}26&vehicleNumberOfAxles={vehicleNumberOfAxles}27&vehicleLength={vehicleLength}28&vehicleWidth={vehicleWidth}29&vehicleHeight={vehicleHeight}30&vehicleCommercial={boolean}31&vehicleLoadType={vehicleLoadType}32&vehicleAdrTunnelRestrictionCode={vehicleAdrTunnelRestrictionCode}33&handsFreeDrivingCapability={handsFreeDrivingCapability}34&accelerationEfficiency={float}35&decelerationEfficiency={float}36&uphillEfficiency={float}37&downhillEfficiency={float}38&consumptionInkWhPerkmAltitudeGain={float}39&recuperationInkWhPerkmAltitudeLoss={float}40&auxiliaryPowerInkW={float}41&chargeMarginsInkWh={commaSeparatedFloats}
curl command example
1curl -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¤tChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&minChargeAtChargingStopsInkWh=4'\2 -H 'Content-Type: application/json' -d '{3 "chargingParameters": {4 "batteryCurve": [5 {6 "stateOfChargeInkWh": 50.0,7 "maxPowerInkW": 2008 },9 {10 "stateOfChargeInkWh": 70.0,11 "maxPowerInkW": 10012 },13 {14 "stateOfChargeInkWh": 80.0,15 "maxPowerInkW": 4016 }17 ],18 "chargingConnectors": [19 {20 "currentType": "AC3",21 "plugTypes": [22 "IEC_62196_Type_2_Outlet",23 "IEC_62196_Type_2_Connector_Cable_Attached",24 "Combo_to_IEC_62196_Type_2_Base"25 ],26 "efficiency": 0.9,27 "baseLoadInkW": 0.2,28 "maxPowerInkW": 1129 },30 {31 "currentType": "DC",32 "plugTypes": [33 "IEC_62196_Type_2_Outlet",34 "IEC_62196_Type_2_Connector_Cable_Attached",35 "Combo_to_IEC_62196_Type_2_Base"36 ],37 "voltageRange": {38 "minVoltageInV": 0,39 "maxVoltageInV": 50040 },41 "efficiency": 0.9,42 "baseLoadInkW": 0.2,43 "maxPowerInkW": 15044 },45 {46 "currentType": "DC",47 "plugTypes": [48 "IEC_62196_Type_2_Outlet",49 "IEC_62196_Type_2_Connector_Cable_Attached",50 "Combo_to_IEC_62196_Type_2_Base"51 ],52 "voltageRange": {53 "minVoltageInV": 500,54 "maxVoltageInV": 200055 },56 "efficiency": 0.9,57 "baseLoadInkW": 0.258 }59 ],60 "chargingTimeOffsetInSec": 6061 }62}'
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.
Required parameters | Description |
---|---|
minChargeAtDestinationInkWh float | The battery level upon arrival at the destination of the resulting route
will be at least this much. |
minChargeAtChargingStopsInkWh float | The desired minimum battery charge level upon arrival at each charging
station. However, the remaining charge at the first charging stop may be
lower. |
Optional parameters | Description |
---|---|
| This feature allows EV drivers to manually choose the charging stops along their itinerary, while optimizing charging times for minimal ETT. Possible values are:
automaticFastest |
POST request body format
ChargingParameters
1{2 [...],3 "chargingParameters": {4 "batteryCurve": [5 {6 "stateOfChargeInkWh": 50.0,7 "maxPowerInkW": 2008 },9 {10 "stateOfChargeInkWh": 70.0,11 "maxPowerInkW": 10012 },13 {14 "stateOfChargeInkWh": 80.0,15 "maxPowerInkW": 4016 }17 ],18 "chargingConnectors": [19 {20 "currentType": "AC3",21 "plugTypes": [22 "IEC_62196_Type_2_Outlet",23 "IEC_62196_Type_2_Connector_Cable_Attached",24 "Combo_to_IEC_62196_Type_2_Base"25 ],26 "efficiency": 0.9,27 "baseLoadInkW": 0.2,28 "maxPowerInkW": 1129 },30 {31 "currentType": "DC",32 "plugTypes": [33 "IEC_62196_Type_2_Outlet",34 "IEC_62196_Type_2_Connector_Cable_Attached",35 "Combo_to_IEC_62196_Type_2_Base"36 ],37 "voltageRange": {38 "minVoltageInV": 0,39 "maxVoltageInV": 50040 },41 "efficiency": 0.9,42 "baseLoadInkW": 0.2,43 "maxPowerInkW": 15044 },45 {46 "currentType": "DC",47 "plugTypes": [48 "IEC_62196_Type_2_Outlet",49 "IEC_62196_Type_2_Connector_Cable_Attached",50 "Combo_to_IEC_62196_Type_2_Base"51 ],52 "voltageRange": {53 "minVoltageInV": 500,54 "maxVoltageInV": 200055 },56 "efficiency": 0.9,57 "baseLoadInkW": 0.258 }59 ],60 "chargingTimeOffsetInSec": 60,61 "preferredMSPs": ["Shell Recharge", "MyEasyCharge"]62}
ChargingModes
1{2 [...],3 "chargingModes" : [4 {5 "chargingConnections" : [6 {"facilityType" : "Charge_200_to_240V_1_Phase_at_32A", "plugType" : "CHAdeMO"},7 {"facilityType" : "Charge_380_to_480V_3_Phase_at_16A", "plugType" : "CHAdeMO"}8 ],9 "chargingCurve" : [10 {"chargeInkWh" : 1.0, "timeToChargeInSeconds" : 300},11 {"chargeInkWh" : 2.1, "timeToChargeInSeconds" : 500},12 {"chargeInkWh" : 10.0, "timeToChargeInSeconds" : 3100}13 ]14 },15 {16 "chargingConnections" : [17 {"facilityType" : "Charge_200_to_240V_1_Phase_at_10A", "plugType" : "Standard_Household_Country_Specific"},18 {"facilityType" : "Charge_100_to_120V_1_Phase_at_16A", "plugType" : "CHAdeMO"}19 ],20 "chargingCurve" : [21 {"chargeInkWh" : 1.0, "timeToChargeInSeconds" : 600},22 {"chargeInkWh" : 3.0, "timeToChargeInSeconds" : 2000},23 {"chargeInkWh" : 10.0, "timeToChargeInSeconds" : 8000}24 ]25 },26 "reassessmentParameterSets" : [27 {"auxiliaryPowerInkW" : 0.3}28 ]29 ]30}
PointWaypoints
1{2 [...],3 "supportingPoints": [4 {"latitude": 52.50930, "longitude": 13.42936},5 {"latitude": 52.50844, "longitude": 13.42859},6 {"latitude": 52.50764, "longitude": 13.42752}7 ],8 "pointWaypoints": [9 {10 "waypointSourceType": "AUTO_GENERATED",11 "supportingPointIndex": 1,12 "chargingInformationAtWaypoint": {13 "chargingParkUuid": "ffffffff-bcd3-2fa5-0000-000000153b86",14 "targetChargeInkWh": 40.0,15 "chargingTimeInSeconds": 1800,16 "chargingConnectionInfo": {17 "chargingPlugType": "Combo_to_IEC_62196_Type_2_Base",18 "chargingCurrentType": "Direct_Current",19 "chargingPowerInkW": 25.0,20 "chargingVoltageInV": 400.0,21 "chargingCurrentInA": 62.022 }23 }24 }25 ]26}
AvoidChargingParks
1{2 [...],3 "avoidChargingParks" : ["{uuid1}", "{uuid2}", {...}, "{uuidN}"]4}
Prefer Charging Park Operators
1{2 [...],3 "preferChargingParkOperators" : ["{id1}", "{id2}", {...}, "{idN}"]4}
Avoid Charging Park Operators
1{2 [...],3 "avoidChargingParkOperators" : ["{id1}", "{id2}", {...}, "{idN}"]4}
Preferred Mobility Service Providers (MSPs)
1{2 [...],3 "preferredMSPs": ["{msp1}", "{msp2}", {...}, "{mspN}"]4}
POST request body parameters
The POST data body must contain either a chargingParameters
JSON object (recommended charging model) or a chargingModes
JSON array (legacy charging model). It may also contain a reassessmentParameterSets
JSON array, supportingPoints
JSON array, or pointWaypoints
JSON array described in the Calculate Route POST requests section.
The POST data body can also contain a avoidChargingParks
JSON array of UUIDs
of charging parks to avoid in the route. You can specify up to 40 charging
parks to be avoided. This is a soft avoid, i.e., a route with avoided parks
is returned if no other route can be found.
The list of charging parks to avoid can't be empty and every element must follow the format specified in RFC4122.
The POST data body can also contain a preferChargingParkOperators
JSON array of unique preferred operators to use in the route. You can specify up to 20 preferred operators.
The POST data body can also contain an avoidChargingParkOperators
JSON array of unique operators to avoid in the route. You can specify up to 40 operators to be avoided. This is a soft avoid, i.e., a route with avoided operators is returned if no other route can be found.
The POST data body can also contain a non-empty preferredMSPs
JSON array of
unique preferred Mobility Service Providers (MSPs). You can specify up to 20
MSPs to be preferred. The MSPs supported at a charging park can be seen in the
response in the brand
field of a chargingParkPaymentOption
. Each string can
be up to 40 characters long.
ChargingParameters
Required parameters | Description |
---|---|
batteryCurve array | A piecewise-constant function which maps a state of charge (SoC) of a
battery to the maximum charging power supported for this state of
charge. It is used to compute the charging times of the vehicle.
It must contain zero to up to 20 (inclusive) JSON objects each
containing the properties The following requirements must be fulfilled:
If an empty curve is provided, the charging power will be limited solely by the maximum power of the specified connectors and the charging facility's supported charging power. |
chargingConnectors array | Must be a non-empty array of
|
chargingConnector.currentType string | One of the values |
chargingConnector.plugTypes array of plugType | A non-empty list of |
Optional parameters | Description |
---|---|
chargingTimeOffsetInSec integer | A constant time offset in seconds added to the computed charging time
at each charging stop planned along the route. If not specified, the
default value |
chargingConnector.efficiency float | Optional efficiency factor applied to the power provided by a charging
facility and the maximum charging power for each point of the battery
charging curve. If not specified, the default value |
chargingConnector.baseLoadInkW float | An optional base load considered when determining the available
charging power. The base load is subtracted from the power
provided by the charging facility prior to applying the efficiency
factor. If not specified, the default value |
chargingConnector.maxPowerInkW float | Sets an upper limit for the charging power. The resulting
charging power is the minimum of the charging power supported by the
respective charging facility and this value.
It must be a positive number or zero, where |
chargingConnector.maxVoltageInV float | Sets an upper limit for the voltage when charging. The resulting
voltage is the minimum of the voltage supported by the respective
charging facility and this value.
It must be a positive number or zero, where |
chargingConnector.maxCurrentInA float | Sets an upper limit for the current when charging. The resulting
amperage is the minimum of the amperage supported by the respective
charging facility and this value.
It must be a positive number or zero, where |
chargingConnector.voltageRange object | Specifies a voltage range as a right-open interval for the connector,
defaulting to the range
Note: Explicitly specifying the voltage range of a connector may be necessary when the vehicle supports multiple connectors with the same current type (typically DC) and plug type, with each connector supporting different maximum charging powers depending on the voltage. |
ChargingModes
Required parameters | Description |
---|---|
facilityType string | A string matching a |
plugType string | A string matching a |
chargeInkWh float | A battery charge level in kWh. A float in the |
timeToChargeInSeconds integer | A time span in seconds. A non-negative integer. |
chargingCurveSupportPoint object | A supporting point of a charging curve consisting of |
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.
|
chargingConnection object | Contains one |
chargingConnections array | A non-empty list of at most 20 unique |
chargingMode object | Contains |
chargingModes array | A non-empty list of at most 10 |
PointWaypoints
Required parameters | Description |
---|---|
waypointSourceType string | Denotes the source of the waypoint. Possible values:
|
supportingPointIndex | An index into the
|
Optional parameters | Description |
---|---|
chargingInformationAtWaypoint object | Specified if the waypoint is a charging stop. Must contain the fields
|
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.
Possible values for
|
Possible values for
|
Possible values for
|
Possible values for
|
Response data
Response body
A successful response could look like this:
1[...],2 "routes": [3 {4 [...],5 "summary": {6 [...],7 "remainingChargeAtArrivalInkWh": 16.5,8 "totalChargingTimeInSeconds": 25429 },10 "legs": [11 [...],12 {13 [...],14 "summary": {15 [...],16 "originalWaypointIndexAtEndOfLeg": 0,17 "remainingChargeAtArrivalInkWh": 12.5,18 "chargingInformationAtEndOfLeg": {19 "targetChargeInkWh" : 30.0,20 "chargingTimeInSeconds" : 2542,21 "chargingConnections" : [22 {"facilityType" : "Charge_380_to_480V_3_Phase_at_32A", "plugType" : "NEMA_5_20"},23 {"facilityType" : "Charge_Direct_Current_at_50kW", "plugType" : "IEC_62196_Type_2_Outlet"}24 ],25 "chargingParkUuid" : "a4b60dff-b599-339a-0a1b-aae200153b86",26 "chargingParkName" : "Charging park 1",27 "chargingParkOperatorName": "Charging park operator name",28 "chargingParkLocation": {29 "coordinate" : {"latitude" : 0.6666667, "longitude" : -33.3333333},30 "street" : "Main street",31 "houseNumber" : "42a",32 "city" : "New Berlin",33 "postalCode" : "32606",34 "countryCode" : "US"35 },36 "chargingConnectionInfo": {37 "chargingCurrentType" : "Direct_Current",38 "chargingPowerInkW" : 25.0,39 "chargingPlugType" : "IEC_62196_Type_2_Outlet"40 },41 "chargingParkPaymentOptions": [42 {"method": "Direct"}43 ],44 "chargingStopType" : "Auto_Generated",45 "chargingParkPowerInkW" : 50.046 }47 }48 }49 ]50 }51 ]52}
Response fields
A successful Long Distance EV Routing response extends the fields specified in the Calculate Route Response data section as follows:
JSON 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 float | The estimated battery charge in kWh upon arrival at the end of the leg or the route. |
chargingInformationAtEndOfLeg object | The
In addition, it may contain any of the following:
|
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 |
chargingParkName string | The common name of this charging park. |
chargingParkOperatorName string | The operator name of this charging park. |
chargingParkPowerInkW float | The rated power in kilowatts of the charging park. |
chargingParkLocation object | The
|
coordinate object | Object is the coordinate of the charging station defined by its latitude and longitude fields. It may differ from the location on the road to drive to. |
street string | The street name of the charging park. |
houseNumber string | The house number of the charging park. |
city string | The city of the charging park. |
region string | The region of the charging park. |
postalCode string | The postal code of the charging park. |
countryCode string | The country code of the charging park in the
|
chargingConnectionInfo object | The
In addition, it may contain any of the following:
|
chargingVoltageInV float | The rated voltage in volts of the charging process. |
chargingCurrentInA float | The rated current in amperes of the charging process. |
chargingCurrentType string | An element of the currentType codes table. |
chargingPowerInkW float | The rated maximal power in kilowatts of the charging connection. |
chargingPlugType string | The element of the plugType codes table used for the charging process. |
chargingParkPaymentOptions object | A list of one or more |
chargingParkPaymentOption object | The
|
method string | An element of the paymentMethod codes table. |
brands array | A list of |
brand string | A brand name associated with the charging park. The brand and a Mobility Service Provider are synonymous. |
chargingStopType string | The source of the charging stop at the end of this leg. Values:
|
chargingConnection string | Contains one |
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
|
planningReason string | The reason for a better route proposal. May have an additional
|
| The index of the waypoint at the end of the leg that corresponds to:
This field is not provided if the end of the leg corresponds to the destination or to a new charging waypoint that is not present in the request. |