Maps SDK for Web

tt.services.calculateReachableRange

Calculate a reachable range implementation using the TomTom Reachable Range API.

Makes a route request using the TomTom Routing API - Calculate Reachable Range.

Parameters need to be passed to the constructor. The method go performs the actual call.

The Calculate Reachable Range service calculates a set of locations that can be reached from the origin point, subject to the available fuel or energy budget that is specified in the request.

The information returned is a polygon boundary in counterclockwise orientation and the precise polygon center (the result of map-matching the origin point).

Constructor

tt.services.calculateReachableRange([options])

Example
    tt.services.calculateReachableRange({
        key: <Your API key>,
        origin: '19.454722,51.776667',
        fuelBudgetInLiters: 5,
        constantSpeedConsumptionInLitersPerHundredkm: ["10,20", "15,30"],
    })
        .go()
        .then(function(rangeData) {
            console.log(rangeData.toGeoJson());
        })
        .catch(function(error) {
            console.error(error);
        });
Parameters
Name Description
options
Object
default:None 		Options to be passed to the routing call, or an array of such options objects to perform a batch request.
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:
  • tollRoads: avoids toll roads.
  • motorways: avoids motorways.
  • ferries: avoids ferries.
  • unpavedRoads: avoids unpaved roads.
  • carpools: avoids routes that require use of a carpool (HOV/ High Occupancy Vehicle) lanes.
  • alreadyUsedRoads: avoids using the same road multiple times.
Most useful in conjunction with routeType=thrilling.
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
tt.services.calculateRoute({
     locations: '52.37173,4.91015:52.36357,4.898046255',
     avoidAreas: [{
     southWestCorner: {latitude: 52.36391, longitude:4.90106},
     northEastCorner: {latitude: 52.36554, longitude:4.90767}
}]);

Supported point formats:

  • 'lat,lon'
  • {lat:111, lon:111}
  • {lat:111, lng:111}
  • {latitude:111, longitude:111}
  • {x:111, y:111}
  • {lat: function(), lng:function()}
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.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:
  • By linear interpolation, if the given speed lies in between two speeds in the list.
  • By linear extrapolation otherwise, assuming a constant (ΔConsumption/ΔSpeed) determined by the nearest two points in the list.
The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed. If it only contains a single point, then the consumption rate of that point is used without further processing. Consumption specified for the largest speed must be greater than or equal to that of the penultimate highest speed. This ensures that extrapolation does not lead to negative consumption rates. Similarly, consumption values specified for the two lowest speeds in the list cannot lead to a negative consumption rate for any lower speed. The minimum and maximum values described here refer to the valid range for the consumption values (expressed in kWh/100km).
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:
  • By linear interpolation, if the given speed lies in between two speeds in the list.
  • By linear extrapolation otherwise, assuming a constant (ΔConsumption/ΔSpeed) determined by the nearest two points in the list.
The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed. If it only contains a single point, then the consumption rate of that point is used without further processing. Consumption specified for the largest speed must be greater than or equal to that of the penultimate highest speed. This ensures that extrapolation does not lead to negative consumption rates. Similarly, consumption values specified for the two lowest speeds in the list cannot lead to a negative consumption rate for any smaller speed. The minimum and maximum values described here refer to the valid range for the consumption values (expressed in l/100km).
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.
distanceBudgetInMeters
Number
default:None 		The distance budget in meters that determines the maximal range which can be traveled. The Consumption Model will only affect the range when routeType is eco. NOTE: _exactly one_ of fuelBudgetInLiters, energyBudgetInkWh, timeBudgetInSec and distanceBudgetInMeters must be set.
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.
energyBudgetInkWh
Number
default:None 		Electric energy budget in kilowatt hours (kWh) that determines maximal range which can be traveled using the specified Electric Consumption Model. NOTE: _exactly one_ of fuelBudgetInLiters, energyBudgetInkWh, timeBudgetInSec and distanceBudgetInMeters must be set.
fuelBudgetInLiters
Number
default:None 		Fuel budget in liters that determines the maximal range which can be traveled using the specified Combustion Consumption Model. Required if _vehicleEngineType_ is _combustion_. NOTE: _exactly one_ of fuelBudgetInLiters, energyBudgetInkWh, timeBudgetInSec and distanceBudgetInMeters must be set.
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.


A valid API 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.
origin
String | Array | Object
default:None 		Point from which the range calculation should start. The following formats are supported:
  • String (longitude/latitude pair)
    • "4.8,52.3"
  • Array (longitude/latitude pair)
    • [4.8, 52.3]
  • Object
    • {lon: 4.8, lat: 52.3}
    • {lng: 5.8, lat: 53.3}
    • {x: 53.3, y: 5.8}
    • {longitude: 5.8, latitude: 53.3}
    • {lng: Function, lat: Function} The functions should return a numeric value.
options.protocol
"http" | "https"
default:"https"

The protocol type to be used in the calls.


Represents the type of protocol used to perform a service call.
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:None 		The route type to be used during route calculation.
The type of route requested. Notes on specific values:
  • fastest returns the fastest route.
  • shortest returns the shortest route by distance.
  • eco routes balance economy and speed.
  • thrilling routes include interesting or challenging roads and use as few motorways as possible. You can choose the level of turns included and also the degree of hilliness. See the hilliness and windingness parameters to see how to set this. There is a limit of 900km on routes planned with routeType=thrilling.
The default value is fastest.
timeBudgetInSec
Number
default:None 		Time budget in seconds that determines maximal range which can be traveled using driving time. The consumption parameters will only affect eco-routes and thereby indirectly the driving time. NOTE: _exactly one_ of fuelBudgetInLiters, energyBudgetInkWh, timeBudgetInSec and distanceBudgetInMeters must be set.
options.traffic
Boolean
default:None 		A boolean flag determines if traffic data should be used to calculate the route.
Possible values:
  • true (do consider all available traffic information during routing)
  • false (ignores current traffic data during routing) Note that although the current traffic data is ignored during routing, the effect of historic traffic on effective road speeds is still incorporated.
The default is true.
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 element of the response for that section will be 'other'.
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.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.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
  • USHazmatClass1 Explosives
  • USHazmatClass2 Compressed gas
  • USHazmatClass3 Flammable liquids
  • USHazmatClass4 Flammable solids
  • USHazmatClass5 Oxidizers
  • USHazmatClass6 Poisons
  • USHazmatClass7 Radioactive
  • USHazmatclass8 Corrosives
  • USHazmatClass9 Miscellaneous
Use these for routing in all other countries
  • otherHazmatExplosive Explosives
  • otherHazmatGeneral Miscellaneous
  • otherHazmatHarmfulToWater Harmful to water
This parameter is currently only considered for travelMode truck.
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.

Methods

go( ): Promise

Executes a predefined asynchronous task using the current configuration.

Returns