Maps SDK for Web

tt.services.structuredGeocode

Makes a request using the TomTom Search API - Structured Geocode.

Parameters can 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 structured geocode 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.structuredGeocode([options], [additionalOptions])

Example
function callbackFn(result) {
  console.log(result);
};
tt.services.structuredGeocode({
  key: <Your API key>,
  countryCode: 'GB'
});
Parameters
Name Description
options
Object
default:None 		Options to be passed to the structured geocoding call, or an array of such options objects to perform batch request.
options.countryCode
String
default:None 		The two-letter code of the country being targeted.
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.bestResult
Boolean
default:false

Defines whether the geocode service should return the best result.


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 a single result.
options.countrySecondarySubdivision
String
default:None

The county's name.


Represents the county's name for the structured address.
options.countrySubdivision
String
default:None

The state or province.


Represents the state or province's name for the structured address.
options.countryTertiarySubdivision
String
default:None

The name of the area.


Represents the area's name for the structured address.
options.crossStreet
String
default:None

The cross street's name.


Represents the cross street's name for the structured address.
options.entityTypeSet
String | String[]
default:None

A comma-separated string or an array.


List of entity types which can be used to restrict the result to the Geography result of a specific entity type. If entityTypeSet is specified, only a Geography result with a proper entity type will be returned. Available values:
  • Country
  • CountrySubdivision
  • CountrySecondarySubdivision
  • CountryTertiarySubdivision
  • Municipality
  • MunicipalitySubdivision
  • Neighbourhood
  • PostalCodeArea
Example
tt.services.fuzzySearch({
  query: 'Poland',
  entityTypeSet: 'Country'
}).then(handleResults);
options.extendedPostalCodesFor
String
default:None

A comma-separated list of index types or "None" for no indexes.


Indexes for which extended postal codes should be included in the results. By default, extended postal codes are available for all indexes except geographies because extended postal code lists for geographies can be quite long, so they have to be explicitly requested when needed. Availability is region-dependent. The available 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)
Example
tt.services.structuredGeocode({
  query: 'street name',
  extendedPostalCodesFor: 'POI'
}).then(handleResults);

tt.services.structuredGeocode({
  query: 'street name',
  extendedPostalCodesFor: 'PAD,Addr'
}).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.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.limit
Number
default:10

The maximum number of responses that will be returned.


Represents the maximum number of responses that will be returned per request. The maximum value is 100.
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.municipality
String
default:None

The municipality's name (city/town).


Represents the municipality (city/town) for the structured address.
options.municipalitySubdivision
String
default:None

The municipality subdivision (sub/super city).


Represents the municipality subdivision (sub/super city) for the structured address.
options.offset
Number
default:None

A positive integer value.


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 paginated results when used with the limit option. The maximum value is 1900.
options.postalCode
String
default:None

The zip or postal code.


Represents the zip code or postal code for the structured address.
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.streetName
String
default:None

The street's name.


Represents the street's name for the structured address.
options.streetNumber
String
default:None

The street's number.


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