Maps SDK for Web
tt.services.longDistanceEVRouting
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
The types used in the Long Distance EV Routing service:
-
chargingMode - An object that contains
chargingConnections
and achargingCurve
that describes the charging behavior of the vehicle using the specified charging connections. -
chargingConnections - A non-empty array of at most 20 unique
chargingConnections
which result in the same charging curve. -
chargingConnection - Contains one
facilityType
and oneplugType
which are compatible with the vehicle.{ "facilityType" : "Charge_380_to_480V_3_Phase_at_32A", "plugType" : "IEC_62196_Type_2_Outlet" }
-
facilityType - A string matching a
facilityType
in the values table, which can be found in Distance EV Routing API documentation. -
plugType - A string matching a
plugType
in the values table, which can be found in Distance EV Routing API documentation. -
chargingCurve - 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 has to follow these rules:
- It is given by a sequence of at most 10 non-duplicate
chargingCurveSupportPoints
that are totally, increasingly ordered intimeToChargeInSeconds
andchargeInkWh
. - The last
chargeInkWh
ismaxChargeInkWh
. - The curve is given by connecting the given points in order after adding the first point:
- It is given by a sequence of at most 10 non-duplicate
-
chargingCurveSupportPoint - A supporting point of a charging curve consisting of
chargeInkWh
andtimeToChargeInSeconds
such that the time it takes to charge the battery from0
kWh tochargeInkWh
kWh is given bytimeToChargeInSeconds
.{ "chargeInkWh" : 6, "timeToChargeInSeconds" : 300 }
-
timeToChargeInSeconds - A time span in seconds. A non-negative integer.
-
chargeInkWh - A battery charge level in kWh. A float in the range (0,
maxChargeInkWh
>.
Response
This service extends the API response by providing the following methods:
toGeoJson()
, converts route data into a Feature Collection of LineString or MultiLineString geometries.getTrackingId()
, returns theTracking-ID
associated with the request.
To read more about services responses take a look at Difference between API responses and this library's responses section.
Constructor
tt.services.longDistanceEVRouting([options], [additionalOptions])
Example
tt.services.longDistanceEVRouting({
key: <Your API key>,
locations: '4.878,52.367:4.879,52.367',
vehicleEngineType: 'electric',
avoid: 'unpavedRoads',
constantSpeedConsumptionInkWhPerHundredkm: ['50.0,6.5', '100.0,8.5'],
currentChargeInkWh: 10,
maxChargeInkWh: 40,
minChargeAtDestinationInkWh: 5.2,
minChargeAtChargingStopsInkWh: 1.5,
chargingModes: [
{
chargingConnections: [
{
facilityType: 'Charge_380_to_480V_3_Phase_at_32A',
plugType: 'IEC_62196_Type_2_Outlet'
}
],
chargingCurve: [
{
chargeInkWh: 6,
timeToChargeInSeconds: 300
},
{
chargeInkWh: 12,
timeToChargeInSeconds: 720
}
]
}
]
}).then(function(routeData) {
console.log(routeData.toGeoJson());
});
Parameters
Name | Description |
---|---|
options
Object | Array default:None |
Options to be passed to the routing call, or an array of such options objects to perform a batch request. |
additionalOptions
Object default:None |
Additional options to be passed to the service. |
additionalOptions.abortSignal
Object default:None |
Signal created with abortController. Use AbortController to cancel requests in progress. Example
|
options.accelerationEfficiency
Number default:None |
Specifies the efficiency of converting chemical energy stored in fuel to kinetic energy when the vehicle accelerates (i.e., KineticEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter. |
options.allowVignette
String | String[] default:None |
An array of country codes. List of 3-character ISO 3166-1 alpha-3 country codes of countries in which toll roads with vignettes are allowed. Specifying allowVignette with some countries X is equivalent to specifying avoidVignette with all countries but X. Specifying allowVignette with an empty list is the same as avoiding all toll roads with vignettes. It is an error to specify both avoidVignette and allowVignette. |
options.arriveAt
String default:None |
The properly formatted date with a time value. Date cannot be in the past and has to follow ISO 8601 standard. The date and time of arrival at the destination point. It must be specified as a dateTime. When a time zone offset is not specified it will be assumed to be that of the destination point. The arriveAt value must be in the future. The arriveAt parameter cannot be used in conjunction with departAt. |
options.auxiliaryPowerInkW
Number default:None |
Specifies the amount of power consumed for sustaining auxiliary systems in kilowatts (kW). It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc. |
options.auxiliaryPowerInLitersPerHour
Number default:None |
Specifies the amount of fuel consumed for sustaining auxiliary systems of the vehicle, in liters per hour. It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc. |
options.avoid
Array | String default:None |
Specifies something that the route calculation should try to avoid when determining the route. Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times. Possible values:
|
options.avoidAreas
Object[] default:None |
A list of shapes to avoid for planning routes. A list of shapes to avoid for planning routes. Supported shapes include rectangles. Can contain one of each supported shapes element. Example
Supported point formats:
|
options.avoidVignette
String | String[] default:None |
An array of country codes. List of 3-character ISO 3166-1 alpha-3 country codes of countries in which all toll roads with vignettes are to be avoided. Toll roads with vignettes in countries not in the list are unaffected. It is an error to specify both avoidVignette and allowVignette. |
options.chargingModes
Array default:None |
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 .
|
options.constantSpeedConsumptionInkWhPerHundredkm
Array default:None |
Colon-delimited list of ElectricConstantSpeedConsumptionPairs, e.g., an array of such pairs "60,7". Specifies the speed-dependent component of consumption. Provided as an unordered list of speed/consumption-rate pairs. The list defines points on a consumption curve. Consumption rates for speeds not in the list are found as follows:
|
options.constantSpeedConsumptionInLitersPerHundredkm
Array default:None |
Colon-delimited list of CombustionConstantSpeedConsumptionPairs, e.g., an array of such pairs "60,7". Specifies the speed-dependent component of consumption. Provided as an unordered list of speed/consumption-rate pairs. The list defines points on a consumption curve. Consumption rates for speeds not in the list are found as follows:
|
options.consumptionInkWhPerkmAltitudeGain
Number default:None |
Electric energy in kWh Specifies the electric energy in kWh consumed by the vehicle through gaining 1000 meters of elevation.
recuperationInkWhPerkmAltitudeLoss
Maximum value: 500.0
|
options.currentChargeInkWh
Number default:None |
Specifies the current electric energy supply in kilowatt hours (kWh). |
options.currentFuelInLiters
Number default:None |
Specifies the current supply of fuel in liters. |
options.decelerationEfficiency
Number default:None |
Specifies the efficiency of converting kinetic energy to saved (not consumed) fuel when the vehicle decelerates (i.e., ChemicalEnergySaved/KineticEnergyLost). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter. |
options.departAt
String default:None |
The properly formatted date with the time or 'now' value. Date cannot be in the past and has to follow ISO 8601 standard. The date and time of departure from the origin point. Departure times, apart from now, must be specified as a dateTime. When a time zone offset is not specified, it will be assumed to be that of the origin point. The departAt value must be in the future. The departAt parameter cannot be used in conjunction with arriveAt. |
options.downhillEfficiency
Number default:None |
Specifies the efficiency of converting potential energy to saved (not consumed) fuel when the vehicle loses elevation (i.e., ChemicalEnergySaved/PotentialEnergyLost). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter. |
options.fuelEnergyDensityInMJoulesPerLiter
Number default:None |
Specifies the amount of chemical energy stored in one liter of fuel in megajoules (MJ). It is used in conjunction with the *Efficiency parameters for conversions between saved or consumed energy and fuel. For example, energy density is 34.2 MJ/l for gasoline, and 35.8 MJ/l for Diesel fuel. |
options.hilliness
String default:None |
The level of hilliness on a thrilling route. Degree of hilliness for thrilling route. Possible values: low, normal, high. This parameter can only be used in conjunction with routeType thrilling. |
options.key
String default:None |
A valid API Key for the requested service. Key is required to make use of the given service. It can be issued in the Developer Portal. |
options.maxChargeInkWh
Number default:None |
Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in the vehicle's battery. |
options.minChargeAtChargingStopsInkWh
Number default:None |
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
|
options.minChargeAtDestinationInkWh
Number default:None |
The battery level upon arrival at the destination
of the resulting route will be at least this much.
*Maximum value:* maxChargeInkWh
|
options.protocol
String default:None |
Protocol type, one of http or https. Represents the type of protocol used to perform the service call. |
options.recuperationInkWhPerkmAltitudeLoss
Number default:None |
Electric energy in kWh Specifies the electric energy in kWh gained by the vehicle through losing 1000 meters of elevation.
consumptionInkWhPerkmAltitudeGain
|
options.report
String default:None |
The level of a verbose answer from the service, useful for debugging purposes. Specifies which data should be reported for diagnosis purposes. Possible values: effectiveSettings Reports the effective parameters or data used when calling the API. In the case of defaulted parameters, the default will be reflected where the parameter was not specified by the caller. |
options.routeType
String default:'fastest' |
The route type to be used during route calculation. The type of route requested. Notes on specific values:
|
options.sectionType
String | String[] default:None |
An array of section types.
Specifies which of the section types is reported in the route response. Possible values:
|
options.trackingId
String default:uuid |
Sets value of "Tracking-ID" header. Specifies an identifier for the request. If not set by the user, UUID is generated for each call.
|
options.traffic
Boolean default:true |
A boolean flag determines if traffic data should be used to calculate the route. Possible values:
|
options.travelMode
String default:None |
The primary means of transportation to be used while routing. The travel mode for the requested route. Possible values: car, truck, taxi, bus, van, motorcycle, bicycle, pedestrian Note that the requested travelMode may not be available for the entire route. Where the requested travelMode is not available for a particular section, the |
options.uphillEfficiency
Number default:None |
Specifies the efficiency of converting chemical energy stored in fuel to potential energy when the vehicle gains elevation (i.e., PotentialEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter. |
options.vehicleAdrTunnelRestrictionCode
String default:None |
An ADR restriction code If specified, the vehicle is subject to ADR tunnel restrictions.
|
options.vehicleAxleWeight
Number default:None |
The vehicle axle wight in kg (kilograms). Weight per axle of the vehicle in kg (kilograms). A value of 0 means that weight restrictions per axle are not considered during route planning. This parameter is currently only considered for travelMode truck. |
options.vehicleCommercial
Boolean default:None |
True if the vehicle is used for commercial purposes. The vehicle is used for commercial purposes and thus may not be allowed to drive on some roads. This parameter is currently only considered for travelMode truck. |
options.vehicleEngineType
String default:None |
The vehicle engine type. Engine type of the vehicle. This parameter is currently only considered for travelMode truck. Valid options are: combustion, electric |
options.vehicleHeading
Number default:None |
The angle in which the vehicle is heading.
The directional heading of the vehicle in degrees starting at true North and continuing in a clockwise direction. North is 0 degrees, East is 90 degrees, South is 180 degrees, West is 270 degrees. Possible values are 0-359. |
options.vehicleHeight
Number default:None |
The vehicle height in meters. Height of the vehicle in meters. A value of 0 means that height restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck. |
options.vehicleLength
Number default:None |
The vehicle length in meters. Length of the vehicle in meters. A value of 0 means that length restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck. |
options.vehicleLoadType
Array | String default:None |
The array of truck cargo classification. Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries. Use these for routing in US
|
options.vehicleMaxSpeed
Number default:None |
The maximal allowed vehicle speed in km/h. Maximum speed of the vehicle in km/hour. A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning. A non-zero value may be overridden during route planning. This parameter is currently only considered for travelMode truck. |
options.vehicleWeight
Number default:None |
The vehicle weight in kg (kilograms). Weight of the vehicle in kg. A value of 0 means that weight restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck. |
options.vehicleWidth
Number default:None |
The vehicle width in meters. Width of the vehicle in meters. A value of 0 means that width restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck. |
options.windingness
String default:None |
The level of windingness on a thrilling route. Level of turns for thrilling route. Possible values: low, normal, high. This parameter can only be used in conjunction with routeType thrilling. |