Maps SDK for Web

Class CrossStreetLookup

It allows to convert geographical coordinates into textual address representation using the TomTom's Search API - CrossStreet lookup.

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.

The final response from service is a JSON object with the following structure:

{
  address: {
    buildingNumber: 19,
    streetNumber: 19,
    street: "N 2nd St",
    streetName: "N 2nd St",
    crossStreet: "E SANTA CLARA ST"
    streetNameAndNumber: "",
    speedLimit: "",
    countryCode: "US",
    countrySubdivision: "CA",
    countrySecondarySubdivision: "Santa Clara",
    countryTertiarySubdivision: "",
    municipality: "San Jose",
    postalCode: "95113",
    municipalitySubdivision: "San Francisco Bay Area",
    freeformAddress: "E SANTA CLARA ST & N 2nd St, San Jose, CA, 95113"
  },
  position: "37.337083, -121.8898"
}

Constructor

CrossStreetLookup([options])

Parameters
Name Description Required Type/Values Default
options Options to be passed to the cross street lookup call, or Array of such options objects to perform batch request. No Object 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
options.key An API Key issued from Developer Portal No String None
options.protocol Protocol's type No "http" | "https" "https"
options.position Specific longitude and latitude of the location where the address is supposed to be found. The possible formats are explained in more detail in the position method. This option is required to make the call. No String | Array | Object None
options.limit Maximum number of responses that should be returned No Number 10
options.spatialKeys If is enable the response will also contain a proprietary geo-spatial key information for a specified location No Boolean false
options.heading The directional heading of the vehicle in degrees, for travel along a segment of roadway. 0 is North, 90 is East and so on, values range from -360 to 360. The precision can include up to one decimal place. No Number None
options.radius The maximum distance in meters from the specified position to consider No Number 10000
options.language Language to use in the response. The list with all the available codes can be found here. No String None
Example
tomtom.crossStreetLookup()
  .position('51.759,19.449')
  .go()
  .then(function(response) {
    console.log(response);
  });

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.

heading([newValue]): Number Chainable

Sets or gets the value of the option heading.

Makes possible to get address information of road keeping in mind the direction.

Parameters
Name Description Required Type/Values Default
newValue The directional heading of the vehicle in degrees, for travel along a segment of roadway. 0 is North, 90 is East and so on, values range from -360 to 360. The precision can include up to one decimal place. 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

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

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

Sets or gets the value of the option position.

This option's value should have the location to be reverse geocoded.

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

The supported formats are listed below:

  • [43.71,-72.48] one-dimensional array with two indexes for latitude and longitude respectively.
  • ["43.71","-72.48"] one-dimensional array with two indexes for latitude and longitude respectively.
  • "43.71,-72.48" string with latitude and longitude divided by a comma.
  • {lat: Number, lon: Number} object with two keys: lat and lon.
  • {latitude: Number, longitude: Number} object with two keys: latitude and longitude.
  • L.LatLng leaflet's L.LatLng object.
  • google.maps.LatLng Google Maps LatLng object.

Parameters
Name Description Required Type/Values Default
newValue Latitude and longitude data in one of the supported formats No String | Number[] | String[] | 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

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

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

spatialKeys([newValue]): Boolean Deprecated Chainable

Sets or gets the value of the option spatialKeys.

Enhances, if possible, the response with proprietary geo-spatial key information.

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