Maps SDK for Web - ReverseGeocode

Class ReverseGeocode

Reverse geocode service implementation.

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

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 SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.

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

{
  "summary": {
      "queryTime": 172,
      "numResults": 1
  },
  "addresses": [
      {
          "address": { // Structured Address for the result
              "buildingNumber": "2515",
              "streetNumber": "2515",
              "routeNumbers": [],
              "street": "Soquel Dr",
              "streetName": "Soquel Dr",
              "streetNameAndNumber": "2515 Soquel Dr",
              "countryCode": "US",
              "countrySubdivision": "CA",
              "countrySubdivisionName": "California",
              "municipality": "Santa Cruz",
              "sideOfStreet": "R",
              "offsetPosition": "36.988240,-121.974790",
              "country": "United States of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "2515 Soquel Dr\nSanta Cruz CA 95065",
              "boundingBox": {
                  "northEast": "36.99265,-121.96917",
                  "southWest": "36.98365,-121.98043",
                  "entity": "position"
              },
          },
          "position": "36.98815,-121.97480",
          "matchType": "HouseNumberRange",
          "roadUse": [
              "LocalStreet"
          ]
      }
  ],
  "spatialKeys": []
}

Constructor

ReverseGeocode([options])

Parameters

Name	Description	Required	Type/Values	Default
options	Options to be passed to the reverse geocode 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.	Yes	String \| Array \| Object	None
options.key	API Key valid for requested service.	No	String	None
options.spatialKeys	DEPRECATED! If is enable the response will also contain a proprietary geo-spatial key information for a specified location	No	Boolean	false
options.returnSpeedLimit	To enable return of the posted speed limit (where available).	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.number	If a street number is sent in along with the request, the response may include the side of the street (Left/Right) and also an offset position for that street number.	No	String	None
options.returnRoadUse	Requires to include a road use array for reversegeocodes at street level	No	Boolean	false
options.roadUse	To restrict the result to one or a group of the following road uses: `LimitedAccess`, `Arterial`, `Terminal`, `Ramp`, `Rotary`, `LocalStreet`.	No	String[] \| String	None
options.language	Preferred language and script in which search results (including place names) are returned. If language is not specified, the default official name will be returned in response. Supported languages are listed in the documentation of the service. If requested language is not supported, a special error code will be returned.	No	String	None
options.returnMatchType	Include information on the type of match the geocoder achieved in the response.	No	Boolean	None
options.allowFreeformNewline	Format of newlines in the formatted address. If true, the address will contain newlines. If false, newlines will be converted to commas.	No	Boolean	false
options.view	The geopolitical view used in subsequent calls	No	String	Unified

Example

function callbackFn(response) {
  console.log(response);
}
tomtom.reverseGeocode()
  .position("51.759,19.449")
  .go()
  .then(callbackFn);

Methods

allowFreeformNewline([newValue]): Boolean Chainable

Sets or gets the value of the option allowFreeformNewline.

Format of newlines in the formatted address.

If true, the address will contain newlines.
If false, newlines will be converted to commas.

Parameters

Name	Description	Required	Type/Values	Default
newValue	Enable or disable the feature.	No	Boolean	None

Throws

TypeError If the given argument cannot be converted to a valid value

Returns

Boolean 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

TypeError If the given argument is not a function

Returns

Function 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

TypeError If the given argument is not a function

Returns

Function 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

Promise | Null 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

TypeError if the given argument cannot be converted into a valid value

Returns

Number 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

TypeError If the given argument cannot be converted to a valid value

Returns

String 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

TypeError If the given code is not unsupported

Returns

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

number([newValue]): String Chainable

Sets or gets the value of the option number.

If a street number is sent in along with the request, the response may include the side of the street (Left/Right) and also an offset position for that street number.

Parameters

Name	Description	Required	Type/Values	Default
newValue	Street number as a string	No	String	None

Throws

TypeError If the given argument cannot be converted into a valid value

Returns

String The same service instance or the current option value 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

TypeError if the given argument cannot be converted into a valid value

Returns

String | Number[] | String[] | Object 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

TypeError If the given argument cannot be converted to a valid value

Returns

String 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

TypeError If the given argument cannot be converted into a valid value

Returns

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

returnMatchType([newValue]): Boolean Chainable

Sets or gets the value of the option returnMatchType.

If set, response will contain additional field with one of the values:

AddressPoint (exact house number location)
HouseNumberRange (interpolated house number location)
Street (street location without house number)

Parameters

Name	Description	Required	Type/Values	Default
newValue	Enable or disable the feature	No	Boolean	None

Throws

TypeError If the given argument cannot be converted into a valid value

Returns

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

returnRoadUse([newValue]): Boolean Chainable

Sets or gets the value of the option returnRoadUse.

Requires to include a road use array for reversegeocodes at street level.

Parameters

Name	Description	Required	Type/Values	Default
newValue	Enable or disable the feature	No	Boolean	None

Throws

TypeError if the given argument cannot be converted into a valid value

Returns

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

returnSpeedLimit([newValue]): Boolean Chainable

Sets or gets the value of the option returnSpeedLimit.

Allows, if possible, to receive the speed limit information at the given location.

Parameters

Name	Description	Required	Type/Values	Default
newValue	Enable or disable the feature	No	Boolean	None

Throws

TypeError If the given argument cannot be converted into a valid value

Returns

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

roadUse([newValue]): String[] | String Chainable

Sets or gets the value of the option roadUse.

Use this option if you want to restrict the result to one or a group of the following road uses:

"LimitedAccess"
"Arterial"
"Terminal"
"Ramp"
"Rotary"
"LocalStreet"

Parameters

Name	Description	Required	Type/Values	Default
newValue	An array of strings or just one string with comma separated values	No	String[] \| String	None

Throws

TypeError if the given argument cannot be converted into a valid value

Returns

String[] | String The same service instance or the current option value if no argument was given

spatialKeys([newValue]): Boolean Deprecated Chainable

Announcement date: March 1, 2018. The spatialKeys parameter has been deprecated and will be withdrawn following a 12 month deprecation period. The planned withdrawal date is March 1, 2019.

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

TypeError if the given argument cannot be converted into a valid value

Returns

Boolean 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

String When is used as setter this method is chainable