Long Distance EV Routing
Service version: 1.0
Last edit: 2020.10.29
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 parametersminDeviationDistance
andminDeviationTime
are not supported.
- Reconstruction of a reference route (given by a
-
Waypoints:
- The locations must contain exactly two points, the origin and the destination. Waypoints, and consequently the parameter
computeBestOrder
and the optionrouteRepresentation=none
, are not supported.
- The locations must contain exactly two points, the origin and the destination. Waypoints, and consequently the parameter
-
routeType
values other than fastest are not supported. -
Alternative routes:
maxAlternatives
andalternativeType
are not supported.
-
Instructions
instructionType
andlanguage
are not supported.
arriveAt
is not supported.travelMode
values other thancar
are not supported.computeTravelTimeFor
is not supported.chargeMarginsInkWh
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
¤tChargeInkWh=float
&maxChargeInkWh=float
&minChargeAtDestinationInkWh=float
&minChargeAtChargingStopsInkWh=float
&callback=callback
&vehicleHeading=integer
§ionType=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
&vehicleAdrTunnelRestrictionCode=vehicleAdrTunnelRestrictionCode
&accelerationEfficiency=float
&decelerationEfficiency=float
&uphillEfficiency=float
&downhillEfficiency=float
&consumptionInkWhPerkmAltitudeGain=float
&recuperationInkWhPerkmAltitudeLoss=float
&auxiliaryPowerInkW=float
Example 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¤tChargeInkWh=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
.
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 0 kWh 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.
|
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.
Possible values for |
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 |
currentType
parameter value codes
Possible values for currentType
. This list may be extended in the future.
Description |
---|
Direct_Current |
Alternating_Current_1_Phase |
Alternating_Current_3_Phase |
paymentMethod
parameter value codes
Possible values for paymentMethod
. This list may be extended in the future.
Description |
---|
No_Payment |
Subscription |
Direct |
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"},
{"facilityType" : "Charge_Direct_Current_at_50kW", "plugType" : "IEC_62196_Type_2_Outlet"}
],
"chargingParkUuid" : "a4b60dff-b599-339a-0a1b-aae200153b86",
"chargingParkName" : "Charging park 1",
"chargingParkLocation": {
"street" : "Main street",
"houseNumber" : "42a",
"city" : "New Berlin",
"postalCode" : "32606",
"countryCode" : "US"
},
"chargingConnectionInfo": {
"chargingCurrentType" : "Direct_Current",
"chargingPowerInkW" : 25.0,
"chargingPlugType" : "IEC_62196_Type_2_Outlet"
},
"chargingParkPaymentOptions": [
{"method": "Direct", "brands" : []}
]
}
}
}
]
}
]
}
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 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 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 chargingConnection s, one of which should be used at this charging stop. |
chargingParkName string |
The common name of this charging park. |
chargingParkLocation object |
The chargingParkLocation describes location details of this charging park. It may contain any of the following:
|
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 ISO 3166-1 alpha-2 format. |
chargingConnectionInfo object |
The chargingConnectionInfo object describes details of the charging connection which should be used at this charging stop. It contains:
|
chargingVoltageInV integer |
The rated voltage in volts of the charging process. |
chargingCurrentInA integer |
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 elements. |
chargingParkPaymentOption object |
The chargingParkPaymentOption object describes payment options. It contains:
|
method string | An element of the paymentMethod codes table. |
brands array | A list of brand s that is associated with this charging park. |
brand string | A brand name associated with the charging park. |
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. |