Maps SDK for Web

Class LowBandwidthSearch

extends Search

Allows to make search request using the TomTom's Search API - Low Bandwidth Search.

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

LowBandwidthSearch([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.protocol Protocol's type No "http" | "https" "https"
options.unwrapBbox Changes the bounding box coordinates allowing longitudes that exceeds 180 degrees when is necessary. More No Boolean false
options.limit Maximum number of responses that will be returned No Number 10
options.view Geopolitical view No String "Unified"
options.language Language to use in the response. The list with all the available codes can be found here. No String null
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
options.query Text that will be searched. This parameter is required to be defined either in the options passed to the constructor or using the query() method. No String None
options.typeahead Enables the predictive mode No Boolean false
options.bestResult Return only one result, the best match result. No Boolean false
options.center Location where results should be biased No Number[] | String | L.LatLng | Object None
options.radius The search radius in meters using the coordinates given to the center option as origin. If the radius is zero the results will not be constrained. No Number 0
options.offset Starting offset of the returned results within the full result set No Number 0
options.countrySet List of country codes for limit the search request to those specific political limits No String None
options.boundingBox The bounding box is an area within the search results needs to limit to. If it is omitted then the whole world will be taken into consideration. No Object | Number[] | Object[] | String None
options.idxSet Specify which indexes to utilize for the search No String None
Example
function callbackFn(results) {
  console.log(results);
}

// Using a callback function
tomtom.lowBandwidthSearch()
  .key(<Your API key>) // this is optional if you defined a global key earlier
  .query("Amsterdam, The Netherlands")
  .callback(callbackFn)
  .go();

// Or using a Promise
tomtom.lowBandwidthSearch()
  .key(<Your API key>) // this is optional if you defined a global key earlier
  .query("Amsterdam, The Netherlands")
  .go()
  .then(callbackFn);

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

Methods

bestResult([newValue]): Boolean Chainable

Sets or gets the value of the option bestResult.

It makes the service instances to return only one result, the best match result.

This option overwrites both limit and offset parameters. It changes the response from an array to single result.

Parameters
Name Description Required Type/Values Default
newValue Defines whether geocode service should return the best result No Boolean 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

boundingBox([newValue]): Object | Number[] | Object[] | String Chainable

Sets or returns the value of the boundingBox option.

The bounding box is an area within the search results needs to limit to. If it is omitted then the whole world will be taken into consideration.

In case the area specified exceeds the world boundaries the following actions will be taken depending of which side was exceeded:

  • Latitudes: the exceeded values will be replaced with their maximun.
  • Longitudes: The service will split the area into two (or more) valid bounding boxes and will execute a search request for each one and them merge the responses into a single result.

This method is able to convert a number of popular formats into the bounding box.

The supported formats are listed below:

  • {minLon: 0, minLat: 0, maxLon: 1, maxLat: 1} Plain object with the keys minLon, minLat, maxLon, maxLat.
  • L.LatLngBounds Leaflet's L.LatLngBounds object.
  • [0, 0, 1, 1] An array of numbers describing the bounding box following the order: minLon, minLat, maxLon, maxLat.
  • ol.Extent Open Layers extent object.
  • [ol.Coordinate, ol.Coordinate] An array of two open layers coordinate objects with the order: southWest, northEast.
  • [[0, 0], [1, 1]] A two-dimensional array with two indexes [southWest, northEast], each one with latitude and longitude values.
  • "0,0,1,1" Comma separated string with numbers in the order: minLon, minLat, maxLon, maxLat.
  • [{lon: 0, lat: 0},{lon: 1, lat: 1}] A one-dimensional array with two objects in the order: southWest, northEast and each object with a lat and lon keys.
  • [{lng: 0, lat: 0},{lng: 1, lat: 1}] A one-dimensional array with two objects in the order: southWest, northEast and each object with a lat and lon keys.
  • [L.LatLng, L.LatLng] A one-dimensional array with two L.LatLng instances in the order: southWest and northEast.
  • google.maps.LatLngBounds Google Maps bounds object.
  • google.maps.LatLngBoundsLiteral Google Maps bounds object.
  • [LatLng, LatLng] array of two google.maps.LatLng.
  • [LatLngLiteral, LatLngLiteral] array of two google.maps.LatLngLiteral.

Parameters
Name Description Required Type/Values Default
newValue Bounding box area in one of the supported formats No Object | Number[] | Object[] | String None
Throws

If the given argument cannot be converted into a valid value

Returns

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

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

center([newValue]): Number[] | String | L.LatLng | Object Chainable

Sets or returns the value of the center option.

This method is able to convert a number of popular formats into a geographic coordinate.

The supported formats are listed below:

  • [0, 0] one-dimensional array with two indexes for latitude and longitude respectively.
  • "0,1" string with latitude and longitude divided by a comma.
  • L.LatLng leaflet's L.LatLng object.
  • {lat: Function, lng: Function} object with two functions returning latitude and longitude.
  • {lat: 0, lon: 1} object with two keys: lat and lon.
  • {lat: 0, lng: 1} object with two keys: lat and lng.
  • {x: 0, y: 1} object with two keys: x as latitude and y as longitude.
  • {latitude: 0, longitude: 1} object with two keys: latitude and longitude.

Note: Supplying only the center without a radius will bias search results only to that area.

Parameters
Name Description Required Type/Values Default
newValue Latitude and longitude data in one of the supported formats No Number[] | String | L.LatLng | Object None
Throws

If the given argument cannot be converted into a valid value

Returns

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

countrySet([newValue]): String Chainable

Sets or returns the value of the countrySet option.

This option is a list of country codes for limit the search request to those specific political limits.

Parameters
Name Description Required Type/Values Default
newValue Comma separated list of country codes (e.g.: FR,ES) No String None
Throws

If the given argument cannot be converted into a valid value

Returns

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

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.

idxSet([newValue]): String Chainable

Sets or gets the value of the option idxSet.

This option allows specifying the indexes to use for the search.

The predefined indexes are:

  • Addr: Address range interpolation (when there is no PAD)
  • Geo: Geographies
  • PAD: Point Addresses
  • POI: Points of interest
  • Str: Streets
  • Xstr: Cross Streets (intersections)

Parameters
Name Description Required Type/Values Default
newValue List of indexes divided by commas 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

Example
// search Points Of Interest only
tomtom.geometrySearch()
  .query("pizza")
  .idxSet("POI")
  .go()
  .then(handleResults);

// search addresses only
tomtom.geometrySearch()
  .query("pizza")
  .idxSet("PAD,Addr")
  .go()
  .then(handleResults);

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

language([newValue]): String Chainable

Sets or returns the language option value that decides in which language the search results should be returned.

The value should correspond to one of the supported IETF language codes.

The code is case insensitive.

Parameters
Name Description Required Type/Values Default
newValue Language code No String None
Throws

If the given code is not unsupported

Returns

The same service instance or the current language code if no argument was given

limit([newValue]): Number Chainable

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

Represents the maximum number of responses that will be returned per request.

The maximum value is 100.

Parameters
Name Description Required Type/Values Default
newValue Maximum number of responses that will be returned No Number None
Throws

If the given argument cannot be converted to a valid value

Returns

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

offset([newValue]): Number Chainable

Sets or returns the value of the offset option.

Use this option if you want to apply an offset to the results returned by the Search API service. It makes use of the ofs parameter which allows paginate results when it is used alongside with the limit option.

The maximum value is 1900.

Parameters
Name Description Required Type/Values Default
newValue Positive integer value No Number None
Throws

If the given argument cannot be converted into a valid value

Returns

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

protocol([newValue]): String Chainable

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

Represents the type of protocol used to perform service call.

Parameters
Name Description Required Type/Values Default
newValue Protocol type No "http" | "https" 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

radius([newValue]): Number Chainable

Sets or returns the value of the radius option.

This option specify the search radius in meters using the coordinates given to the center option as origin.

Parameters
Name Description Required Type/Values Default
newValue Positive integer value in meters No Number None
Throws

If the given argument cannot be converted into a valid value

Returns

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

typeahead([newValue]): Boolean Chainable

Sets or gets the value of the current typeahead option.

If this option is enabled the query will be interpreted as a partial input and the search will enter predictive mode.

Parameters
Name Description Required Type/Values Default
newValue Enables of disables the option No Boolean 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

unwrapBbox([newValue]): Boolean Chainable

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

It changes the bounding box coordinates allowing longitudes that exceeds 180 degrees when is necessary.

The Search API always returns coordinates with longitudes between -180 and 180 degrees. That could be a problem when you need to set the viewport over a place which area crosses the antimeridian line (e.g. Russia).

Setting the option to true will apply an offset to the bounding box coordinates allowing be used to set the viewport on a leaflet's map.

Parameters
Name Description Required Type/Values Default
newValue Enables or disables the feature No Boolean None
Throws

If a non-boolean value is tried to be setted

Returns

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

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