Maps SDK for Web

Class MatrixRouting

Matrix routing service implementation using using the TomTom's Routing API - Matrix Routing.

The Routing API - Matrix Routing service allows calculation of a matrix of route summaries for a set of routes which are defined with origin and destination locations.

For every given origin this service calculates the cost of routing from that origin to every given destination. The set of origins and the set of destinations can be thought of as the column and row headers of a table and each cell in the table contains the costs of routing from the origin to the destination for that cell.

The following costs are computed for each route:

  • Travel times
  • Distances

Parameters can be passed to the constructor or provided via convenient methods that can be chained until the method go performs the actual call.

The call is asynchronous therefore the user have two options for receive the response:

  • Passing a callback function.
  • Use the Promise returned by the go method to handle the response.

Constructor

MatrixRouting([options], [computeTravelTimeFor])

Parameters
Name Description Required Type/Values Default
options Options to be passed to the routing call, or Array of such options objects to perform batch request. No Object None
options.key An API Key issued from Developer Portal No String global API key
options.origins A set of origin locations represented by coordinates (lat, lon). At least one origin is required. No Array None
options.destinations A set of destination locations represented by coordinates (lat, lon). At least one destination is required. Yes Array None
options.routeType The type of route requested. No String None
options.traffic Determines if traffic data should be used to calculate the route No Boolean None
options.travelMode The travel mode for the requested route. The possible values are documented here. No String None
options.avoid Specifies something that the route calculation should try to avoid when determining the route. The possible values are documented here. No String None
options.departAt The date and time of departure from the origin point No String None
options.arriveAt The date and time of arrival at the destination point response No String None
options.hilliness Degree of hilliness for thrilling route. The possible values are documented here. No String None
options.vehicleAxleWeight The vehicle axle weight in kg. No Number None
options.vehicleCommercial True if vehicle is used for commercial purposes. No Boolean None
options.vehicleEngineType The vehicle engine type. One of "combustion" or "electric" No String None
options.vehicleHeight The vehicle height in m. No Number None
options.vehicleLength The vehicle length in meters. No Number None
options.vehicleLoadType The array of truck cargo classification. The possible values are documented here. No Array | String None
options.vehicleMaxSpeed The maximal allowed vehicle speed in km/h. No Number None
options.vehicleWeight The vehicle weight in kg. No Number None
options.vehicleWidth The vehicle width in m. No Number None
options.windingness Level of turns for thrilling route. The possible values are documented here. No String None
options.protocol Protocol's type, one of "http" or "https". No String None
computeTravelTimeFor Setting to all provides additional information regards travel times. No String None
Example
var origins = [
  { point: { latitude: 51.63685, longitude: 19.4171 } },
  { point: { latitude: 51.63685, longitude: 19 } }
];
var destinations = [
  { point: { latitude: 52.23498, longitude: 21.00849 } },
  { point: { latitude: 52.63685, longitude: 18 } }
];
function callbackFn(routeGeoJson) {
  console.log(routeGeoJson);
}
var request = tomtom.matrixRouting({
  origins: origins,
  destinations: destinations,
  traffic: true
});
request.go()
  .then(callbackFn);

Methods

arriveAt([arriveAt]): String Chainable

A setter and getter for 'arriveAt' attribute. 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.

Parameters
Name Description Required Type/Values Default
arriveAt The properly formatted date with time value. Date cannot be in the past. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or language if argument is omitted.

avoid([avoid]): Array Chainable

A setter and getter for avoid attribute.

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 carpool (HOV/ High Occupancy Vehicle) lanes.
  • alreadyUsedRoads avoids using the same road multiple times.

Most useful in conjunction with routeType=thrilling.

Parameters
Name Description Required Type/Values Default
avoid Specifies something that the route calculation should try to avoid when determining the route No Array | String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or street number value if argument is omitted.

callback([newValue]): Function Chainable

Sets or gets the value of the option callback. This callback function will be called only after the go method successfully complete its task. Its first and unique argument passed to the callback will be the result of the request.

Parameters
Name Description Required Type/Values Default
newValue The new callback function No Function None
Throws

If the given argument is not a function

Returns

The same service instance or the current callback function if no argument was given

Example
function callbackFn(results) {
  console.log(results);
}
tomtom.fuzzySearch()
  .query("pizza")
  .callback(callbackFn)
  .go();

computeTravelTimeFor([computeTravelTimeFor]): String Chainable

A setter and getter for 'computeTravelTimeFor' attribute. Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time. Possible values:

  • none - do not compute additional travel times,
  • all - compute travel times for all types of traffic information. Specifying all results in the fields noTrafficTravelTimeInSeconds, historicTrafficTravelTimeInSeconds and liveTrafficIncidentsTravelTimeInSeconds being included in the summaries in the route response.

Parameters
Name Description Required Type/Values Default
computeTravelTimeFor Setting all provides additional information regards travel times. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

departAt([departAt]): String Chainable

A setter and getter for 'departAt' attribute. 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.

Parameters
Name Description Required Type/Values Default
departAt The properly formatted date with time or 'now' value. Date cannot be in the past. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or language if argument is omitted.

destinations([destinations]): String Chainable

A setter and getter for 'destinations' attribute. A set of destination locations represented by points (lat,lon). At least one destination is required.

Parameters
Name Description Required Type/Values Default
destinations A set of origin locations represented by points (lat,lon). No Array None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

fail([newValue]): Function Chainable

Sets or gets the value of the option fail. This function is called when an error occurs (e.g. invalid values or a communication error). The callback will receive just one argument which is the error description. This parameter will be ignored if the callback function is not defined and therefore the go method will return a Promise that will be rejected if an error occurs. If you don't specificy a failure callback, the default behavior in case of encounter a problem is to throw an error.

Parameters
Name Description Required Type/Values Default
newValue The new callback function No Function None
Throws

If the given argument is not a function

Returns

The same service instance or the current callback function if no argument was given

Example
function successCallback(results) {
  console.log(results);
}
function failureCallback(error) {
  console.log(error);
}
tomtom.fuzzySearch()
  .query("pizza")
  .callback(successCallback)
  .fail(failureCallback)
  .go();

go([success], [fail]): Promise | Null

Executes a predefined asynchronous task using the current configuration and then execute one of the callback functions based on the success of the result. It receives two optional arguments. The first one is a callback function that will be used when the task is successfully completed. The second one is another callback function that will be used only in case of failure. Both arguments are shortcuts for the callback and fail methods respectively.

Parameters
Name Description Required Type/Values Default
success The callback function to be called on case of success No Function None
fail The callback function to be called on case of failure. If a success callback was not given this argument will be ignored. In that case the returned Promise should be used to handle the failures. No Function None
Returns

If the success callback is omitted (and wasn't defined one yet) this function will return a Promise

Example

All the ways of using this method:

// Defining callbacks as function arguments
tomtom.fuzzySearch()
  .query("pizza")
  .go(successCallback, failureCallback);

// Defining callbacks using setters methods
tomtom.fuzzySearch()
  .query("pizza")
  .callback(successCallback)
  .fail(failureCallback)
  .go();

// Using the returned Promise
tomtom.fuzzySearch()
  .query("pizza")
  .go()
  .then(successCallback)
  .catch(failureCallback);

The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.

hilliness([hilliness]): String Chainable

A setter and getter for 'hilliness' attribute. Degree of hilliness for thrilling route. Possible values: low, normal, high This parameter can only be used in conjunction with routeType thrilling.

Parameters
Name Description Required Type/Values Default
hilliness The level of hilliness on a thrilling route. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or language if argument is omitted.

key([newValue]): String Chainable

Sets or returns the API key to be used in calls made by this service instance.

Setting a key for each instance of this class is not needed if the key was already setted globally using the tomtom.searchKey() function.

A valid API key is required to make use of the Search API services. It can be issued from TomTom's Developer Portal.

Parameters
Name Description Required Type/Values Default
newValue key API Key valid for requested service No String None
Throws

If the given argument cannot be converted to a valid value

Returns

The same service instance or the current option value if no argument was given

origins([origins]): String Chainable

A setter and getter for 'origins' attribute. A set of origin locations represented by points (lat,lon). At least one origin is required.

Parameters
Name Description Required Type/Values Default
origins A set of origin locations represented by points (lat,lon). No Array None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

routeType([routeType]): String Chainable

A setter and getter for routeType attribute.

Represent 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 for how to set this. There is a limit of 900 km on routes planned with routeType=thrilling Default value is fastest

Parameters
Name Description Required Type/Values Default
routeType Route type to be used during route calculation. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or route type value if argument is omitted.

traffic([traffic]): Boolean Chainable

A setter and getter for 'traffic' attribute. Possible values: true (do consider all available traffic information during routing) false (ignore 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. Default is true

Parameters
Name Description Required Type/Values Default
traffic Boolean flag determine if traffic data should be used to calculate the route. No String | Boolean None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or traffic value if argument is omitted.

travelMode([travelMode]): String Chainable

A setter and getter for 'travelMode' attribute. The mode of travel 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.

Parameters
Name Description Required Type/Values Default
travelMode The primary mean of transportation to be used while routing. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or language if argument is omitted.

vehicleAxleWeight([vehicleAxleWeight]): Number Chainable

A setter and getter for 'vehicleAxleWeight' attribute. Weight per axle of the vehicle in kg. 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.

Parameters
Name Description Required Type/Values Default
vehicleAxleWeight The vehicle axle wight in kg. No Number None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleCommercial([vehicleCommercial]): String Chainable

A setter and getter for 'vehicleCommercial' attribute. 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.

Parameters
Name Description Required Type/Values Default
vehicleCommercial True if vehicle is used for commercial purposes. No Boolean None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleEngineType([vehicleEngineType]): String Chainable

A setter and getter for 'vehicleEngineType' attribute. Engine type of the vehicle. This parameter is currently only considered for travelMode truck. Valid options are: combustion, electric

Parameters
Name Description Required Type/Values Default
vehicleEngineType The vehicle engine type. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleHeight([vehicleHeight]): Number Chainable

A setter and getter for 'vehicleHeight' attribute. 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.

Parameters
Name Description Required Type/Values Default
vehicleHeight The vehicle height in m. No Number None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleLength([vehicleLength]): Number Chainable

A setter and getter for 'vehicleLength' attribute. 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.

Parameters
Name Description Required Type/Values Default
vehicleLength The vehicle length in m. No Number None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleLoadType([vehicleLoadType]): Array Chainable

A setter and getter for 'vehicleLoadType' attribute. 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.

Parameters
Name Description Required Type/Values Default
vehicleLoadType The array of truck cargo classification. No Array | String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleMaxSpeed([vehicleMaxSpeed]): Number Chainable

A setter and getter for 'vehicleMaxSpeed' attribute. 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.

Parameters
Name Description Required Type/Values Default
vehicleMaxSpeed The maximal allowed vehicle speed in km/h. No Number None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleWeight([vehicleWeight]): Number Chainable

A setter and getter for 'vehicleWeight' attribute. 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.

Parameters
Name Description Required Type/Values Default
vehicleWeight The vehicle weight in kg. No Number None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

vehicleWidth([vehicleWidth]): Number Chainable

A setter and getter for 'vehicleWidth' attribute. 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.

Parameters
Name Description Required Type/Values Default
vehicleWidth The vehicle width in m. No Number None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or current value if argument is omitted.

windingness([windingness]): String Chainable

A setter and getter for 'windingness' attribute. Level of turns for thrilling route. Possible values: low, normal, high This parameter can only be used in conjunction with routeType thrilling.

Parameters
Name Description Required Type/Values Default
windingness The level of windingness on a thrilling route. No String None
Throws

if the given argument cannot be converted to a valid value

Returns

Method returns the service instance allowing chaining or language if argument is omitted.