Maps SDK for Web

Class AlongRouteSearch

Allows to make search request using the TomTom's Search API - Along Route Search.

The Along Route Search endpoint allows you to perform a fuzzy search for POIs along a specified route. This search is constrained by specifying Detour Time limiting measure.

To send the route points this service will use a POST request with the route encoded as a JSON payload. The minimum number of route points is 2.

Constructor

AlongRouteSearch([options])

Parameters
Name Description Required Type/Values Default
options No Object None
options.key An API Key issued from Developer Portal. No String None
options.limit Maximum number of responses that should be returned. Maximum number is 20. No Number 10
options.view Geopolitical view No String "Unified"
options.maxDetourTime Maximum detour time in seconds. This option is mandatory. For that reason needs to be defined during the instance construction or using the maxDetourTime() setter function. The maximum allowed value is 3600. No String None
options.query Text that will be searched. This option is mandatory. For that reason needs to be defined during the instance construction or using the query() setter function. Yes String None
options.route The route representation. This option is mandatory. For that reason needs to be defined during the instance construction or using the route() setter function. See more details. Yes Array None
options.callback Callback function to use in case of success No Function None
options.fail Callback function to use in case of failure No Function default
Example
tomtom.alongRouteSearch({
    limit: 20,
    maxDetourTime: 120,
    query: 'gas station',
    route: [
        {
            "lat": 37.7524152343544,
            "lon":-122.43576049804686
        },
        {
            "lat": 37.70660472542312,
            "lon":-122.43301391601562
        },
        [37.712059855877314, -122.36434936523438], // Another valid format
        new L.LatLng(37.75350561243041, -122.37396240234374) // Leaflet's L.LatLng instances are also allowed
    ]
  })
  .go()
  .then(function(response) {
    console.log('SUMMARY:');
    console.table(response.summary);
    console.log('RESULTS:');
    console.table(response.results);
  });

For a list of all available format for routes read the documentation for the route option.

Methods

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();

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.

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

limit([limit]): Number Chainable

Sets or gets the limit of the elements for the response.

Parameters
Name Description Required Type/Values Default
limit Maximum number of the elements in response. Maximum number is 20. No Number 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.

maxDetourTime([value]): Number Chainable

Sets or gets the maximum detour time in seconds.

The maximum allowed value is 3600.

Parameters
Name Description Required Type/Values Default
value New maximum detour time in seconds. No Number 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.

query([newValue]): String Chainable

Sets or gets the value of the query option.

This option represents the text that will be searched.

Parameters
Name Description Required Type/Values Default
newValue The query string. This value will be properly encoded during the creation of the request. 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

route([route]): Array Chainable

Sets or gets the route to search along. The route should have at least two points.

The following formats are supported:

  • String[]
    • ["52.3,4.8", "52.3,4.8"]
  • Array[]
    • [ [52.3, 4.8], [52.3, 4.8] ]
  • Object[]
    • {lat: 52.3, lon: 4.8}
    • {lat: 53.3, lng: 5.8}
    • {x: 53.3, y: 5.8}
    • {latitude: 53.3, longitude: 5.8}
    • {lat: Function, lng: Function} The functions should return a numeric value

Parameters
Name Description Required Type/Values Default
route Route representation. No Array 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.

Example
tomtom.alongRouteSearch()
  .route([
    {
        lat: 37.7524152343544,
        lon:-122.43576049804686
    },
    {
        lat: 37.70660472542312,
        lon:-122.43301391601562
    }
  ])
  .go(callback);

view([newValue]): String Chainable

Sets or returns the view option value to be used in the calls.

Can be one of "Unified", "IN", "PK", "IL and "MA" Legend: Unifies - International view IN - India PK - Pakistan IL - Israel MA - Morocco

Parameters
Name Description Required Type/Values Default
newValue New value to be set No String None
Returns

When is used as setter this method is chainable