Maps SDK for Web
Class GeometrySearch
Allows to make search request using the TomTom's Search API - Geometry Search.
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:
Constructor
GeometrySearch([options])
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
options | Options to be passed to the geometry search call, or Array of such options objects to perform batch request. | No | Object | None |
options.key | An API Key issued from Developer Portal | No | String | None |
options.protocol | Protocol's type | No | "http" | "https" | "https" |
options.unwrapBbox | Changes the bounding box coordinates allowing longitudes that exceeds 180 degrees when is necessary. More | No | Boolean | false |
options.limit | Maximum number of responses that will be returned | No | Number | 10 |
options.language | Language to use in the response. The list with all the available codes can be found here. | No | String | null |
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.query | Text that will be searched. This parameter is required to be defined either in the options passed to the constructor or using the query() method. | Yes | String | None |
options.geometryList | Represents the list of geometries for the geometry search | No | Array | None |
options.idxSet | Specify which indexes to utilize for the search | No | String | None |
options.extendedPostalCodesFor | Represent the indexes for which extended postal codes should be included in the results | No | String | None |
options.view | Sets the geopolitical view used in the service | No | String | None |
Example
var geometryList = [
{
type: "POLYGON",
vertices: [
"37.7524152343544,-122.43576049804686",
"37.70660472542312,-122.43301391601562",
"37.712059855877314,-122.36434936523438",
"37.75350561243041,-122.37396240234374"
]
},
{
type: "CIRCLE",
position: "37.71205,-121.36434",
radius: 6000
},
{
type: "CIRCLE",
position: "37.31205,-121.36434",
radius: 1000
}
];
function callbackFn(results) {
console.log(results);
}
// Using a callback function
tomtom.geometrySearch()
.key(<Your API key>) // this is optional if you defined a global key earlier
.geometryList(geometryList)
.query('pizza')
.callback(callbackFn)
.go();
// Or using a Promise
tomtom.geometrySearch()
.key(<Your API key>) // this is optional if you defined a global key earlier
.geometryList(geometryList)
.query('pizza')
.go()
.then(callbackFn);
The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.
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();
extendedPostalCodesFor([newValue]): String Chainable
Sets or gets the value of the option extendedPostalCodesFor
.
Represent the indexes for which extended postal codes should be included in the results.
The available indexes codes are:
Addr
: Address rangesGeo
: GeographiesPAD
: Point AddressesPOI
: Points of InterestStr
: StreetsXStr
: Cross Streets (intersections)
The value should be a comma separated list of index types (in any order) or just the string "None"
for no indexes.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | List of indexes, divided by commas. | 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
Example
tomtom.geometrySearch()
.query("pizza")
.extendedPostalCodesFor("PAD,Addr,POI")
.go()
.then(handleResults);
tomtom.geometrySearch()
.query("pizza")
.extendedPostalCodesFor("None")
.go()
.then(handleResults);
The extended postal code will be returned as an extendedPostalCode
property of an address.
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();
geometryList([newValue]): Object[] Chainable
Sets or gets the current value of the option "geometryList".
Its a list of geometries to search in.
Currently only two types of geometries are being supported:
- Polygons: Groups of coordinates that describes an enclosed area
- Circles: Describe a circular area using an unique coordinate and a radius in meters
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | List of geometries | No | Object[] | 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
Example
// A polygon area
[
{
type: "POLYGON",
vertices: [
"37.7524152343544,-122.43576049804686",
"37.70660472542312,-122.43301391601562",
"37.712059855877314,-122.36434936523438",
"37.75350561243041,-122.37396240234374"
]
}
];
// A couple of circle areas
var geometryList = [
{
type: "CIRCLE",
position: "37.71205,-121.36434",
radius: 6000 // Unit is in meters
},
{
type: "CIRCLE",
position: "37.31205,-121.36434",
radius: 1000 // Unit is in meters
}
];
// Mixing polygons and circles areas
var geometryList = [
{
type: "POLYGON",
vertices: [
"37.7524152343544,-122.43576049804686",
"37.70660472542312,-122.43301391601562",
"37.712059855877314,-122.36434936523438",
"37.75350561243041,-122.37396240234374"
]
},
{
type: "CIRCLE",
position: "37.71205,-121.36434",
radius: 6000
},
{
type: "CIRCLE",
position: "37.31205,-121.36434",
radius: 1000
}
];
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.
idxSet([newValue]): String Chainable
Sets or gets the value of the option idxSet
.
This option allows specifying the indexes to use for the search.
The predefined indexes are:
Addr
: Address range interpolation (when there is no PAD)Geo
: GeographiesPAD
: Point AddressesPOI
: Points of interestStr
: StreetsXstr
: Cross Streets (intersections)
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | List of indexes divided by commas | 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
Example
// search Points Of Interest only
tomtom.geometrySearch()
.query("pizza")
.idxSet("POI")
.go()
.then(handleResults);
// search addresses only
tomtom.geometrySearch()
.query("pizza")
.idxSet("PAD,Addr")
.go()
.then(handleResults);
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
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
query([newValue]): String Chainable
Sets or gets the value of the query
option.
This option represents the text that will be searched.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | The query string. This value will be properly encoded during the creation of the request. | 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
unwrapBbox([newValue]): Boolean Chainable
Sets or returns the unwrapBbox
option value to be used in the calls.
It changes the bounding box coordinates allowing longitudes that exceeds 180
degrees when is necessary.
The Search API always returns coordinates with longitudes between -180
and 180
degrees. That
could be a problem when you need to set the viewport over a place which area crosses the antimeridian
line (e.g. Russia).
Setting the option to true
will apply an offset to the bounding box coordinates allowing be used to
set the viewport on a leaflet's map.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Enables or disables the feature | No | Boolean | None |
Throws
If a non-boolean value is tried to be setted
Returns
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
When is used as setter this method is chainable