Maps SDK for Web

tt.services.reverseGeocode

Reverse geocode service implementation.

It converts geographical coordinates into a textual address representation using the TomTom Search API - Reverse Geocode.

Parameters need to be passed to the constructor.

Response

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

{
  address: {
    buildingNumber: 19,
    streetNumber: 19,
    landmark: '',
    street: 'N 2nd St',
    streetName: 'N 2nd St',
    streetNameAndNumber: '',
    speedLimit: '',
    countryCode: 'U',
    countrySubdivision: 'CA',
    countrySecondarySubdivision: 'Santa Clara',
    countryTertiarySubdivision: '',
    municipality: 'San Jose',
    postalCode: '95113',
    municipalitySubdivision: 'San Francisco Bay Area',
    freeformAddress: '19 N 2nd St, San Jose, CA, 95113'
  },
   position: {
    lng: -121.8898',
    lat: '37.337083
  },
  roadUse: ['LocalStreet']
}

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

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

Constructor

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

Example
function callbackFn(response) {
  console.log(response);
}
tt.services.reverseGeocode({
  key: <Your API key>,
  position: '19.449: 51.759'
}).then(callbackFn);
Parameters
Name Description
options
Object
default:None 		Options to be passed to the reverseGeocode call, or an array of such options objects to perform a batch request.
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.allowFreeformNewline
Boolean
default:None

Format of newlines in the formatted address.


If true, the address will contain newlines (line breaks). Otherwise, newlines will be converted to spaces.
options.dateTime
String
default:None

The date and time used to return time zone information.


  • It allows the service to decide whether the Daylight Saving Time time zone should be used or not.
  • It must conform to RFC 3339.
options.entityType
String | String[]
default:None

A comma-separated string. One or more of: - Country - CountrySubdivision - CountrySecondarySubdivision - CountryTertiarySubdivision - Municipality - MunicipalitySubdivision - Neighbourhood - PostalCodeArea


This parameter specifies the level of filtering performed on geographies. Providing the parameter narrows the search for the specified geography entity types. The resulting response will contain the geography ID as well as the entity type matched. This ID is a token that can be used to get the geometry of that geography. The following parameters are ignored when entityType is set: heading, number, returnRoadUse, returnSpeedLimit, roadUse, and returnMatchType.
options.heading
Number
default:None

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.


Makes it possible to get the address information of the road, keeping in mind the direction.
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.language
String
default:null

Language code that decides in which language the results should be returned.


The value should correspond to one of the supported IETF language codes. The list is available here. The code is case insensitive.
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.number
String
default:None

Street number as a string.


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.
options.position
String | Number[] | String[] | Object
default:None

Longitude and latitude data in one of the supported formats.


This option's value should have the location to be reverse geocoded. This option is able to convert a number of popular formats into a geographic coordinate. The supported formats are listed below:
  • Maps.LngLat Class instance.
  • [0, 0] A one-dimensional array with two indexes for longitude and latitude respectively.
  • ["0", "0"] A one-dimensional array with two indexes for longitude and latitude respectively.
  • "0,1" A string with longitude and latitude divided by a comma.
  • {lng: Function, lat: Function} An object with two functions returning longitude and latitude.
  • {lon: 0, lat: 1} An object with two keys: lat and lon.
  • {lng: 0, lat: 1} An object with two keys: lat and lng.
  • {x: 0, y: 1} An object with two keys: x as longitude and y as latitude.
  • {longitude: 0, latitude: 1} An object with two keys: longitude and latitude.
options.protocol
"http" | "https"
default:"https"

The protocol type to be used in the calls.


Represents the type of protocol used to perform a service call.
options.radius
Number
default:None

A positive integer value in meters.


This option specifies the search radius in meters using the coordinates given to the center option as origin.
options.returnMatchType
Boolean
default:None

Type of match.


Includes information on the type of match the geocoder achieved in the response.
options.returnRoadUse
Boolean
default:None

Enable or disable the feature.


Requires including a road use array for reversegeocodes at street level.
options.returnSpeedLimit
Boolean
default:None

Enable or disable the feature.


Allows, if possible, the receiving of speed limit information at the given location.
options.roadUse
String[] | String
default:None

An array of strings, or just one string with comma-separated values.


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"
options.streetNumber
String
default:None

The street's number.


Represents the street's number for the structured address.
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