Maps SDK for Web

tt.services.alongRouteSearch

Makes a search request using the TomTom Search API - Along Route Search.

The Search Along Route endpoint allows you to perform a fuzzy search for POIs along a specified route. This search is constrained by specifying the 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.

Parameters need to be passed to the constructor.

Response

The response is extended with getTrackingId() method, which returns the Tracking-ID associated with the request.

Additionally, the response extends API response by providing toGeoJson() method, which converts along route search data into FeatureCollection with Point geometry.

Each point feature represents poi from the original response. Properties of poi are mapped into feature properties

Please refer to Difference between API responses and this library's responses section.

Constructor

tt.services.alongRouteSearch([options], [additionalOptions])

Example
tt.services.alongRouteSearch({
    key: <Your API key>,
    limit: 20,
    maxDetourTime: 120,
    query: 'gas station',
    route: [
        {
            'lat': 37.7524152343544,
            'lon':-122.43576049804686
        },
        {
            'lat': 37.70660472542312,
            'lon':-122.43301391601562
        },
        [-122.36434936523438, 37.712059855877314], // Another valid format
    ]
  }).then(function(response) {
    console.log('SUMMARY:');
    console.table(response.summary);
    console.log('RESULTS:');
    console.table(response.results);
  });

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

Parameters
Name Description
options
Object
default:None
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
var abortController = new AbortController();
var options = {};
tt.services.calculateRoute(options, { abortSignal: abortController.signal })
    .then(function(response) { console.log(response) });
    .catch(function(error) {
        if (abortController.signal.aborted === true) {
            console.log('Request aborted.');
        }
    });
abortController.abort();
options.brandSet
String
default:None

A list of brands divided by commas.


This option specifies brands to use for the search.
Example
// search for TomTom and Foobar facilities
tt.services.fuzzySearch({
  query: 'office',
  brandSet: 'TomTom,Foobar'
}).then(handleResults);

// search for TomTom offices
tt.services.fuzzySearch({
  query: 'office',
  brandSet: 'TomTom'
}).then(handleResults);
options.categorySet
String
default:None

A list of categories codes divided by commas.


This option specifies categories codes to use for the search. Those codes can be retrieved by using poiCategories service.
Example
// search places of category Restaurant
tt.services.fuzzySearch({
  query: 'food',
  categorySet: '7315'
})
.then(handleResults);

// search places of category either Italian or French Restaurant
tt.services.fuzzySearch({
  query: 'food',
  categorySet: '7315025,7315017'
})
.then(handleResults);
options.connectorSet
String
default:None

A list of Electrical Vehicle connector types divided by commas.


This option specifies connector types, which could be used to restrict the result to Points Of Interest of type Electric Vehicle Station supporting specific connector types. For more info about EV connector names, please refer to Supported Connector Types documentation page.
Example
// search for Electric Vehicle Station supporting IEC62196Type1
tt.services.fuzzySearch({
  query: 'station',
  connectorSet: 'IEC62196Type1'
}).then(handleResults);

// search for Electric Vehicle Station supporting IEC62196Type1 or GBT20234Part2
tt.services.fuzzySearch({
  query: 'station',
  connectorSet: 'IEC62196Type1,GBT20234Part2'
}).then(handleResults);
options.detourOffset
Boolean
default:false

Parameter which turns on calculation of the distance between the start of the route and the starting point of the detour to a POI.

  • Detour offset is also calculated when sortBy parameter is set to detourOffset.
  • Value is provided in a response only when detourOffset is set to true.
options.fuelSet
String
default:None

A list of Fuel Types divided by commas.


This option specifies fuel types, which could be used to restrict the result to the Points Of Interest of specific fuels. If fuelSet is specified, the query can remain empty. Only POIs with a proper fuel type will be returned. Value: A comma-separated list of fuel type identifiers (in any order).
  • Item order does not matter.
  • When multiple fuel types are provided, only POIs that belong to (at least) one of the fuel types from the provided list will be returned.
Available values:
  • Petrol
  • LPG
  • Diesel
  • Biodiesel
  • DieselForCommercialVehicles
  • E85
  • LNG
  • CNG
  • Hydrogen
  • AdBlue
Example
// search Points Of Interest of the ¨Diesel¨ fuel type
tt.services.fuzzySearch({
  query: 'Gas stations',
  fuelSet: 'Diesel'
}).then(handleResults);

// search Points Of Interest of either the ¨Petrol¨ or ¨LPG¨ fuel type
tt.services.fuzzySearch({
  query: 'Gas stations',
  fuelSet: 'Petrol,LPG'
}).then(handleResults);
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.limit
Number
default:10

The maximum number of elements in the response. The maximum number is 20.
options.mapcodes
String
default:null

Enables the return of a comma-separted mapcodes list. It can also filter the response to only show selected mapcode types. See Mapcodes in the response. Values: One or more of:

  • Local
  • International
  • Alternative

A mapcode represents a specific location, to within a few meters. Every location on Earth can be represented by a mapcode. Mapcodes are designed to be short, easy to recognize, remember, and communicate. Visit the Mapcode project website for more information. Usage examples:


Example
tt.services.fuzzySearch({
  query: 'Some street',
  mapcodes: 'Local'
}).then(handleResults);

tt.services.fuzzySearch({
  query: 'Some street',
  mapcodes: 'Local,Alternative,International'
}).then(handleResults);
options.maxDetourTime
Number
default:None

New maximum detour time in seconds.


The maximum allowed value is 3600.
options.maxPowerKW
Number
default:None

A number representing a maximum power rate in kilowatts.


An optional parameter which can be used to restrict the result to the availability for connectors with a specific maximum value of power in kilowatts.
options.minPowerKW
Number
default:None

A number representing a minimum power rate in kilowatts.


An optional parameter which can be used to restrict the result to the availability for connectors with a specific minimum value of power in kilowatts.
options.openingHours
String
default:None

The only available option is 'nextSevenDays'.


This option shows the opening hours for the next week, starting with the current day in the local time of the POI.
Example
// search for cinemas inculding their opening hours.
tt.services.fuzzySearch({
  query: 'cinema',
  openingHours: 'nextSevenDays'
}).then(handleResults);
options.query
String
default:None

The query string. This value will be properly encoded during the creation of the request.


This option represents the text that will be searched.
options.route
Array
default:None

Route representation.


The following formats are supported:
  • String[] (longitude/latitude pairs)
    • ["4.8,52.3", "4.8,52.3"]
  • Array[] (longitude/latitude pairs)
    • [ [4.8,52.3], [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.
Example
function callbackFn(response) {
  console.log(response);
}

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

.then(callbackFn);
options.sortBy
String
default:'detourTime'

Parameter which provides possibility to sort returned results. Values: detourTime, detourDistance, detourOffset

  • Detour distance will be calculated as a difference between the original distance and the distance of a new route with Point Of Interest location.
  • detourDistance field will be present in every response regardless of sorting parameter.
  • If detour offset is set to false detourOffset=false and sorting parameter is set to detourOffset sortBy=detourOffset then detour offset will be calculated and results will be sorted as expected, but detourOffset value will not be present in the response.
options.spreadingMode
String
default:None

Enables the spreading of returned results evenly along the route.
options.timeZone
String
default:None

The only available option is iana.


This option is used to indicate the mode in which the timeZone object should be returned. The only available option is iana - mode that shows the IANA ID which allows the user to determine the current time zone for the POI.
Example
// search for cinemas including their opening hours and IANA ID.
tt.services.fuzzySearch({
  query: 'cinema',
  openingHours: 'nextSevenDays',
  timeZone: 'iana'
}).then(handleResults);
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.
  • It can be used to trace a call.
  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • An example of the format that matches this regular expression is UUID: (e.g. 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1). For details check RFC 4122.
  • If specified, it is replicated in the Tracking-ID Response header.
  • It is only meant to be used for support and does not involve tracking of you or your users in any form.
options.view
String
default:None

Geopolitical view.


Can be one of "Unified", "AR", "IN", "PK", "IL, "MA", "RU", "TR" and "CN". Legend:
  • Unified - International view
  • AR - Argentina
  • IN - India
  • PK - Pakistan
  • IL - Israel
  • MA - Morocco
  • RU - Russia
  • TR - Turkey
  • CN - China