Maps SDK for Web
Class StructuredGeocode
Allows to make request using the TomTom's Search API - Structured 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:
The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.
Constructor
StructuredGeocode([options])
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
options | Options to be passed to the structured geocoding 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.protocol | Protocol's type | No | "http" | "https" | "https" |
options.bestResult | Return only one result, the best match result | No | Boolean | false |
options.key | An API Key issued from Developer Portal | No | String | None |
options.countryCode | 2 or 3 country code letters (e.g.: FR, ES). This option is required to be defined here or by using the countryCode method. | Yes | String | None |
options.limit | Maximum number of responses that will be returned | No | Number | 10 |
options.offset | Starting offset of the returned results within the full result set | No | Number | 0 |
options.language | Language to use in the response. The list with all the available codes can be found here. | No | String | None |
options.streetNumber | Street Number | No | String | None |
options.streetName | Street name | No | String | None |
options.crossStreet | Cross street name | No | String | None |
options.municipality | Municipality (city/town) | No | String | None |
options.municipalitySubdivision | Municipality subdivision (sub/super city) | No | String | None |
options.countryTertiarySubdivision | Named area | No | String | None |
options.countrySecondarySubdivision | County | No | String | None |
options.countrySubdivision | State or province | No | String | None |
options.postalCode | Zip or postal code | No | String | None |
Example
function callbackFn(result) {
console.log(result);
};
tomtom.structuredGeocode()
.countryCode("GB")
.callback(callbackFn)
.go();
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
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();
countryCode([newValue]): String Chainable
Sets or returns the value of the countryCode
option.
Represents the country's code.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | 2 or 3 country code letters | 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
countrySecondarySubdivision([newValue]): String Chainable
Sets or returns the value of the countrySecondarySubdivision
option.
Represents the county's name for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | County's name | 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
countrySubdivision([newValue]): String Chainable
Sets or returns the value of the countrySubdivision
option.
Represents the state or province's name for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | State or province | 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
countryTertiarySubdivision([newValue]): String Chainable
Sets or returns the value of the countryTertiarySubdivision
option.
Represents the area's name for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Name of the area | 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
crossStreet([newValue]): String Chainable
Sets or returns the value of the crossStreet
option.
Represents the cross street's name for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Cross street's name | 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.
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
municipality([newValue]): String Chainable
Sets or returns the value of the municipality
option.
Represents the municipality (city/town) for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Municipality's name (city/town) | 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
municipalitySubdivision([newValue]): String Chainable
Sets or returns the value of the municipalitySubdivision
option.
Represents the municipality subdivision (sub/super city) for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Municipality subdivision (sub/super city) | 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
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
postalCode([newValue]): String Chainable
Sets or returns the value of the postalCode
option.
Represents the zip code or postal code for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Zip or postal code | 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
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
streetName([newValue]): String Chainable
Sets or returns the value of the streetName
option.
Represents the street's name for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Street's name | 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
streetNumber([newValue]): String Chainable
Sets or returns the value of the streetNumber
option.
Represents the street's number for the structured address.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Street's number | 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