Developer

Long Distance EV Routing

Service version: 1
Last edit: 2024.06.07
TomTom Maps

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

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 option routeRepresentation=none are not supported.
    • routeType values other than fastest are not supported.
  • alternativeType values other than betterRoute are not supported.
  • travelMode values other than car, motorcycle, bus, or van are not supported.
  • computeTravelTimeFor is not supported.

Deprecation notice

March 15, 2024

  • Value tollRoad for the input parameter sectionType as well as the respective response section type TOLL_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 and toll 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

post
URL request example
1https://{baseURL}/routing/{versionNumber}/calculateLongDistanceEVRoute/{routePlanningLocations}/json?key={Your_API_Key}
2&vehicleEngineType={vehicleEngineType}
3&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}
4&currentChargeInkWh={float}
5&maxChargeInkWh={float}
6&minChargeAtDestinationInkWh={float}
7&criticalMinChargeAtDestinationInkWh={float}
8&minChargeAtChargingStopsInkWh={float}
9&callback={callback}
10&maxAlternatives={alternativeRoutes}
11&minDeviationDistance={integer}
12&minDeviationTime={integer}
13&vehicleHeading={integer}
14&sectionType={sectionType}
15&report={effectiveSettings}
16&departAt={time}
17&arriveAt={time}
18&traffic={boolean}
19&avoid={avoidType}
20&prefer={preferType}
21&instructionsType={instructionsType}
22&language={language}
23&chargingStopsStrategy={chargingStopsStrategy}
24&vehicleMaxSpeed={vehicleMaxSpeed}
25&vehicleWeight={vehicleWeight}
26&vehicleAxleWeight={vehicleAxleWeight}
27&vehicleNumberOfAxles={vehicleNumberOfAxles}
28&vehicleLength={vehicleLength}
29&vehicleWidth={vehicleWidth}
30&vehicleHeight={vehicleHeight}
31&vehicleCommercial={boolean}
32&vehicleLoadType={vehicleLoadType}
33&vehicleAdrTunnelRestrictionCode={vehicleAdrTunnelRestrictionCode}
34&handsFreeDrivingCapability={handsFreeDrivingCapability}
35&accelerationEfficiency={float}
36&decelerationEfficiency={float}
37&uphillEfficiency={float}
38&downhillEfficiency={float}
39&consumptionInkWhPerkmAltitudeGain={float}
40&recuperationInkWhPerkmAltitudeLoss={float}
41&auxiliaryPowerInkW={float}
42&chargeMarginsInkWh={commaSeparatedFloats}

curl command example

post
Request 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&currentChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&criticalMinChargeAtDestinationInkWh=2&minChargeAtChargingStopsInkWh=4'\
2  -H 'Content-Type: application/json' -d '{
3    "chargingParameters": {
4      "batteryCurve": [
5        {
6          "stateOfChargeInkWh": 50.0,
7          "maxPowerInkW": 200
8        },
9        {
10          "stateOfChargeInkWh": 70.0,
11          "maxPowerInkW": 100
12        },
13        {
14          "stateOfChargeInkWh": 80.0,
15          "maxPowerInkW": 40
16        }
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": 11
29        },
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": 500
40          },
41          "efficiency": 0.9,
42          "baseLoadInkW": 0.2,
43          "maxPowerInkW": 150
44        },
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": 2000
55          },
56          "efficiency": 0.9,
57          "baseLoadInkW": 0.2
58        }
59      ],
60      "chargingTimeOffsetInSec": 60
61	}
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.
Minimum value: 0.0
Maximum value: maxChargeInkWh

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.
Minimum value: 0.0
Maximum value: 0.5 × maxChargeInkWh

Optional parametersDescription
chargingStopsStrategy
string

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: the service automatically generates charging stops that minimize the total ETT, including charging time.

  • manualFastest: the service doesn't add charging stops to the route.

    • It calculates the fastest route visiting charging and non-charging waypoints, optimizing charging times at the former to minimize the total ETT, with respect of the minimal charge at charging stops and destination when possible.
    • Since no additional charging stops are added to the route, it may happen that arrival charges at waypoints and destination are below the corresponding minimal charge, or even null or negative.
    • When a charging stop or the destination is unreachable, the target charge at the previous charging stop, when it exists, is set to 100% of the vehicle's charge capacity.
Default value:automaticFastest

For both values, charging waypoints are specified by adding their coordinates in the locations part of the URL and their charging park IDs in the corresponding chargingWaypoints item of the post data.

minChargeAtFirstChargingStopInkWh
float

The desired minimum battery charge level upon arrival at the first charging station. If this parameter is not provided, an internal formula determines its value to allow route calculations with low current charge.


Minimum value:0.0
Maximum value:minChargeAtChargingStopsInkWh
criticalMinChargeAtDestinationInkWh
float

Upon arrival at the destination, the minimum battery charge level may be reduced to this value if it allows the planning of a route without any charging stops. For example, if the driver has a personal home charger and sets the home as the destination, it could be okay to arrive there with a charge level lower than minChargeAtDestinationInkWh


Minimum value:0.0
Maximum value:minChargeAtDestinationInkWh
Default value:minChargeAtDestinationInkWh

POST request body format

ChargingParameters

post
POST ChargingParameters format - JSON
1{
2      [...],
3        "chargingParameters": {
4          "batteryCurve": [
5            {
6              "stateOfChargeInkWh": 50.0,
7              "maxPowerInkW": 200
8            },
9            {
10              "stateOfChargeInkWh": 70.0,
11              "maxPowerInkW": 100
12            },
13            {
14              "stateOfChargeInkWh": 80.0,
15              "maxPowerInkW": 40
16            }
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": 11
29            },
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": 500
40              },
41              "efficiency": 0.9,
42              "baseLoadInkW": 0.2,
43              "maxPowerInkW": 150
44            },
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": 2000
55              },
56              "efficiency": 0.9,
57              "baseLoadInkW": 0.2
58            }
59          ],
60          "chargingTimeOffsetInSec": 60,
61	"preferredMSPs": ["Shell Recharge", "MyEasyCharge"]
62}

ChargingModes

post
POST ChargingModes format
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

post
POST PointWaypoints format
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.0
22        }
23      }
24    }
25  ]
26}

ChargingWaypoints

post
POST ChargingWaypoints format
1{
2  [...],
3  "chargingWaypoints": [
4    {
5      "waypointIndex": 1,
6      "chargingParkId": "64470d9f-100f-3c41-5d48-d2a500153b86"
7    }
8  ]
9}

AvoidChargingParks

post
POST AvoidChargingParks format
1{
2  [...],
3  "avoidChargingParks" : ["{uuid1}", "{uuid2}", {...}, "{uuidN}"]
4}

Prefer Charging Park Operators

post
POST Prefer Charging Park Operators format
1{
2  [...],
3  "preferChargingParkOperators" : ["{id1}", "{id2}", {...}, "{idN}"]
4}

Avoid Charging Park Operators

post
POST Avoid Charging Park Operators format
1{
2  [...],
3  "avoidChargingParkOperators" : ["{id1}", "{id2}", {...}, "{idN}"]
4}

Preferred Plug-and-Charge providers

post
POST Preferred Plug-and-Charge providers format
1{
2  [...],
3  "preferredPlugAndChargeProviders": ["{PnC1}", "{PnC2}", {...}, "{PnCN}"]
4}

Preferred Mobility Service Providers (MSPs)

post
POST Preferred MSPs
1{
2  [...],
3  "preferredMSPs": ["{msp1}", "{msp2}", {...}, "{mspN}"]
4}

Charging Park as Destination

Example POST request body with chargingDestination - JSON
1{
2  [...],
3  "chargingDestination":
4    {
5      "chargingParkId": "{uuid}"
6    },
7  [...]
8}

POST request body parameters

The POST data body must contain either a chargingParameters field (recommended charging model) or a chargingModes field (legacy charging model). It may also contain reassessmentParameterSets, supportingPoints, encodedPolyline, encodedPolylinePrecision, or pointWaypoints fields, described in the Calculate Route POST requests section.

The calculateLongDistanceEVRoute endpoint accepts requests with user defined (manual) waypoints to visit. A manual waypoint is specified by its coordinates and needs to be added to routePlanningLocations of the request path, similar to specifying manual waypoints for "normal" routes. A subset of such manually added waypoints can be marked as charging stops by extending the POST data body with the chargingWaypoints parameter. The details, such as the charging park unique identifier (UUID), of all the charging stops in the locations list must be provided under this parameter. If the charging stop details are not provided then the location is considered as a non-charging waypoint.

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 a 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 an optional preferredPlugAndChargeProviders non-empty JSON array of unique Plug-and-Charge Providers. The charging parks with these providers are preferred if there is a connector available that supports Plug-and-Charge. You can specify up to 20 Plug-and-Charge preferred providers. Each string can be up to 40 letters long.

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 specified mobility service providers will be given a precedence over other MSPs during the route search. 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.

The POST data body can also contain a non-empty chargingDestination JSON object describing a charging park; see Charging at Destination.

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 stateOfChargeInkWh and maxPowerInkW. The stateOfChargeInkWh of each entry in the curve defines the lower bound (included) of the half-open interval this maximum charging power applies to, with the possible exception of the interval corresponding to the lowest SoC, which is implicitly extended towards a state of charge of 0.


The following requirements must be fulfilled:

  • stateOfChargeInkWh must be larger than or equal to zero.

  • None of the stateOfChargeInkWh values from such an object may equal the stateOfChargeInkWh value of any other object.

  • maxPowerInkW must be larger than zero.

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 elements. No chargingConnector may be equivalent to another, where equivalent chargingConnector elements:

  • have the same currentType

  • share at least one element of plugTypes

  • have an overlapping voltageRange

chargingConnector.currentType
string

One of the values AC1, AC3 for single- or three-phase alternating current, or DC for direct current.

chargingConnector.plugTypes
array of plugType

A non-empty list of plugType elements. See the plugType values table for possible values of plugType.

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 60 applies. It must be larger than or equal to zero.

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 1.0 applies. It must be larger than zero and smaller than or equal to one.

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 0.0 applies. It must be larger than zero.

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 0 implies the power is only limited by the charging facility. If not specified, the default value of 0 applies.
Note: If a non-empty battery charging curve is specified, a potentially lower maximum charging power at a given state of charge according to the curve takes precedence over the maximum power specified here when calculating the predicted charging time.

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 0 implies the voltage is only limited by the charging facility. If not specified, the default value of 0 applies.

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 0 implies the amperage is only limited by the charging facility. If not specified, the default value of 0 applies.

chargingConnector.voltageRange
object

Specifies a voltage range as a right-open interval for the connector, defaulting to the range [0, infinity) if not specified.
It must contain the fields minVoltageInV and maxVoltageInV specifying minimal (included) and maximal (excluded) voltage values.

  • minVoltageInV must be a positive number or zero.

  • maxVoltageInV must be a number greater than minVoltageInV or 0, which is treated as infinity.

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 parametersDescription
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:

    Creating a curve
    1{
    2  "chargeInkWh": 0.0,
    3  "timeToChargeInSeconds": 0
    4}
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.

PointWaypoints

Required parameters

Description

waypointSourceType
string

Denotes the source of the waypoint. Possible values:

  • USER_DEFINED: a waypoint that was explicitly defined by the user.

  • AUTO_GENERATED: a waypoint that was defined by the system (e.g., the charging stop that was provided as a result of the LDEV route enhancement).

supportingPointIndex

An index into the supportingPoints array that denotes the location of the waypoint on the reference route.

  • Must be inside supportingPoints array boundaries.

Optional parameters

Description

chargingInformationAtWaypoint
object

Specified if the waypoint is a charging stop. Must contain the fields chargingConnectionInfo, chargingParkUuid, chargingTimeInSeconds, and targetChargeInkWh.

  • chargingConnectionInfo must contain chargingPlugType and may contain chargingCurrentType, chargingPowerInkW ,chargingVoltageInV, and chargingCurrentInA

ChargingWaypoints

Required parameters

Description

waypointIndex

integer

A positive integer depicting the charging waypoint's index in the route planning locations list. Must be in the range 1-150.

chargingParkId

string

A non-blank string depicting the ID of the charging park, which is at the index waypointIndex in the locations list. The user can retrieve this ID from the TomTom EV Search.

chargingWaypoint
object

A chargingWaypoint object describes charging stop details. It contains: a waypointIndex and a chargingParkId.

chargingWaypoints
array

A list of one or more chargingWaypoint elements.


Note that:

  • Two consecutive chargingWaypoint elements should have waypointIndex values in ascending order.

  • Two consecutive chargingWaypoint elements with consecutive waypointIndex values should not have the same chargingParkId.

PreferredMSPs

Required parameters

Description

preferredMSP

string

The name of the preferred Mobility Service Provider (MSP).

preferredMSPs

array

A list of one or more preferredMSP elements.


Note that:

  • The preferredMSP elements should be unique.

  • The number of preferredMSP elements should not exceed 20.

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
 
 

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 when chargingModes is used in the request could look like this:

Response body - JSON
1[...],
2  "routes": [
3    {
4      [...],
5      "summary": {
6        [...],
7        "remainingChargeAtArrivalInkWh": 16.5,
8        "totalChargingTimeInSeconds": 2542
9      },
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.0
46            }
47          }
48        }
49      ]
50    }
51  ]
52}

The following changes apply to the response when chargingParameters is used instead of chargingModes in the request:

  • chargingInformationAtEndOfLeg does not contain chargingConnections.

  • chargingInformationAtEndOfLeg contains chargingConnectionInfo and chargingParkExternalId.

  • chargingConnectionInfo contains chargingPlugType, chargingCurrentType, and chargingPowerInkW.

  • chargingConnectionInfo may contain chargingVoltageInV and chargingCurrentInA.

A successful response when chargingParameters is used in the request could look like this:

Response body - JSON
1[...],
2  "routes": [
3    {
4      [...],
5      "summary": {
6        [...],
7        "remainingChargeAtArrivalInkWh": 16.5,
8        "totalChargingTimeInSeconds": 2542
9      },
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              "chargingParkUuid" : "a4b60dff-b599-339a-0a1b-aae200153b86",
22              "chargingParkExternalId" : "4e9989d7-6586-44f6-ae76-fd6901b58777",
23              "chargingParkName" : "Charging park 1",
24              "chargingParkOperatorName": "Charging park operator name",
25              "chargingParkLocation": {
26                "coordinate" : {"latitude" : 0.6666667, "longitude" : -33.3333333},
27                "street" : "Main street",
28                "houseNumber" : "42a",
29                "city" : "New Berlin",
30                "postalCode" : "32606",
31                "countryCode" : "US"
32              },
33              "chargingConnectionInfo": {
34                "chargingVoltageInV": 900.0,
35                "chargingCurrentInA": 194.0,
36                "chargingCurrentType" : "Direct_Current",
37                "chargingPowerInkW" : 174.6,
38                "chargingPlugType" : "Combo_to_IEC_62196_Type_2_Base",
39                "plugAndChargeSupport" : "SUPPORTED"
40              },
41              "chargingParkPaymentOptions": [
42                {"method": "Direct"}
43              ],
44              "chargingStopType" : "Auto_Generated",
45              "chargingParkPowerInkW" : 175.0
46            }
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

  • 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

In addition, it may contain any of the following:

  • chargingConnectionInfo
  • chargingParkLocation
  • chargingParkName
  • chargingParkOperatorName
  • chargingParkPowerInkW
  • chargingStopType
  • chargingParkPaymentOptions
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.

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 chargingParkLocation object describes location details of this charging park. It may contain any of the following:

  • coordinate
  • street
  • houseNumber
  • city
  • region
  • postalCode
  • countryCode
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 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. Its contents may differ if the request contains chargingModes or chargingParameters.


For requests having chargingModes:


It contains:

  • chargingPlugType

In addition, it may contain any of the following:

  • chargingVoltageInV
  • chargingCurrentInA
  • chargingCurrentType
  • chargingPowerInkW

For requests having chargingParameters:


It contains:

  • chargingPlugType
  • chargingCurrentType
  • chargingPowerInkW

In addition, it may contain any of the following:

  • chargingVoltageInV
  • chargingCurrentInA
  • plugAndChargeSupport
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.

plugAndChargeSupport
string

Indicates if the selected charging connector supports Plug-and-Charge. Possible values are:

  • SUPPORTED
  • UNSUPPORTED
chargingParkPaymentOptions
object

A list of one or more chargingParkPaymentOption elements.

chargingParkPaymentOption
object

The chargingParkPaymentOption object describes payment options. It contains:

  • method
  • brands
method
string

An element of the paymentMethod codes table.

brands
array

A list of brands that is associated with this charging park. This element is not included if there are no associated brands.

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:

  • Auto_Generated for automatically added charging stops.

  • User_Defined for user-specified waypoints. If a waypoint also includes charging data then it is considered as a user-chosen charging station and the most optimal charging times are chosen for all the charging stops in order to get the fastest possible route. This may result in some manually added charging waypoints to have zero charging time, i.e., charge at departure = charge at arrival.

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.

chargingParkExternalId

string

A unique string id for search purposes.

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.

planningReason
string

The reason for a better route proposal. May have an additional Out_Of_Range value in case any stop of the reference route is unreachable.

originalWaypointIndexAtEndOfLeg
number

The index of the waypoint at the end of the leg that corresponds to:

  • The index of this waypoint in the list of waypoints from the routePlanningLocations base path parameter in the request (the first waypoint has an index equal to 0).

  • The index of this waypoint in the pointWaypoints field when reconstructing a route.

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.

Long Distance EV Routing response

A successful route response is received if the input parameters comprised of the coordinates, chargingParkId and waypointIndex are valid.

  • The response would contain all the specified waypoints in the requested order.
  • It may also contain charging stops that are automatically added based on the vehicle's consumption and charging model.
  • The most optimal charging times are chosen for all the charging stops in order to get the fastest possible route.
  • This may result in some manually added charging waypoints to have zero charging time, i.e., charge at departure = charge at arrival.

The type of charging stop is defined by the chargingStopType attribute in chargingInformationAtEndOfLeg. This attribute has the following values:

  • User_Defined for user-specified charging stops.
  • Auto_Generated for automatically-added charging stops.

In the case of invalid input parameters, route calculation fails, and no route is received.

Calculating Long Distance EV Route with a charging park as the final destination

The calculateLongDistanceEVRoute endpoint accepts requests with a charging park as the destination. A charging park is specified by its unique identifier (UUID) which must be added to the POST data of the request. It's required the charging park specified by the UUID matches the destination's coordinates.

POST request body with chargingDestination

Example POST request body with chargingDestination - JSON
1{
2  [...],
3  "chargingDestination":
4    {
5      "chargingParkId": "{uuid}"
6    },
7  [...]
8}

Description of the chargingDestination parameter

ParameterDescription
chargingParkId
string		A non-blank string depicting the ID of the charging park of the destination. The user can retrieve this ID from the TomTom EV Search.

Example curl command with chargingPark as the destination

Example POST curl command with chargingPark as the destination - JSON
1curl -X POST "https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/52.507,13.492:52.47582,13.36404/json?key={YOUR_API_KEY}&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01&currentChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&minChargeAtChargingStopsInkWh=4"\
2  -H 'Content-Type: application/json' -d '{
3  "chargingDestination":
4    {
5      "chargingParkId": "27cddfad-d11e-42bb-aba2-b5a850ee0db3"
6    },
7  "chargingModes": [
8    {
9      "chargingConnections": [
10        {
11          "facilityType": "Charge_380_to_480V_3_Phase_at_32A",
12          "plugType": "IEC_62196_Type_2_Outlet"
13        }
14      ],
15      "chargingCurve": [
16        {
17          "chargeInkWh": 6,
18          "timeToChargeInSeconds": 360
19        },
20        {
21          "chargeInkWh": 12,
22          "timeToChargeInSeconds": 720
23        },
24        {
25          "chargeInkWh": 28,
26          "timeToChargeInSeconds": 1944
27        },
28        {
29          "chargeInkWh": 40,
30          "timeToChargeInSeconds": 4680
31        }
32      ]
33    },
34    {
35      "chargingConnections": [
36        {
37          "facilityType": "Charge_200_to_240V_1_Phase_at_10A",
38          "plugType": "Standard_Household_Country_Specific"
39        }
40      ],
41      "chargingCurve": [
42        {
43          "chargeInkWh": 6,
44          "timeToChargeInSeconds": 15624
45        },
46        {
47          "chargeInkWh": 12,
48          "timeToChargeInSeconds": 32652
49        },
50        {
51          "chargeInkWh": 28,
52          "timeToChargeInSeconds": 76248
53        },
54        {
55          "chargeInkWh": 40,
56          "timeToChargeInSeconds": 109080
57        }
58      ]
59    }
60  ]
61}'

Long Distance EV Routing response

A successful route response is received if the input parameter chargingParkId is valid. The response would contain the data field chargingInformationAtEndOfLeg with charging information of the specified charging park in the summary of the last leg. The charging information would contain targetChargeInkWh calculated as max(maxChargeInkWh * 0.8, remainingChargeAtArrivalInkWh), and chargingTimeInSeconds set either to 0 or to the respective charging time if targetChargeInkWh is greater than remainingChargeAtArrivalInkWh. chargingTimeInSeconds in the summary of the last leg is not included into the route's nor the leg's travel time travelTimeInSeconds, and is provided as reference information for the driver.

In the case of an invalid input parameter chargingParkId, the chargingParkId is ignored, and the destination is considered as a destination without a charging park. The destination's coordinates are used as a final destination.