Geocoding Control API reference
maptiler/maptiler-geocoding-control
This reference documents every object and method available. Each section describes classes or objects as well as their properties, parameters, methods, and associated events. Many sections also include inline code examples and related resources.
The GeocodingControl
create a graphical component in your map application.
Example (create control with some not default options)
Options
Parameters
options.apiKey | Maptiler API key. Not needed if used with MapTiler SDK. |
---|---|
options.maplibregl
MapLibreGL ?
|
A MapLibre GL JS instance to use when creating Markers.
Used if options.marker is true with MapLibre GL JS library.
If not provided it will be autodetected. Not needed if used with MapTiler SDK.
|
options.debounceSearch
default:
200 |
Sets the amount of time, in milliseconds, to wait before querying the server when a user types into the Geocoder input box. This parameter may be useful for reducing the total number of API calls made for a single query. |
options.proximity
ProximityRule[] |
null |
undefined?
default:
[{ type: "server-geolocation" }] |
Search results closer to the proximity point will be given higher priority.
First matching rule from the array will be used.
Set to null to disable proximity.
|
options.placeholder
default:
"Search" |
Override the default placeholder attribute value. |
options.errorMessage
default:
"Something went wrong…" |
Override the default error message. |
options.noResultsMessage
default:
"Oops! Looks like you're trying to predict something that's not quite right. We can't seem to find what you're looking for. Maybe try double-checking your spelling or try a different search term. Keep on typing - we'll do our best to get you where you need to go!" |
Override the default message if no results are found. |
options.minLength
default:
2 |
Minimum number of characters to enter for results to show. |
options.bbox | A bounding box argument: this is a bounding box given as an array in the format [minX, minY, maxX, maxY]. Search results will be limited to the bounding box. |
options.limit
default:
5 |
Maximum number of results to show. |
options.language | Specify the language(s) to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. Set to empty string or empty array for forcing no language preference. If this parameter is not provided at all the browser's language settings will be used. |
options.showResultsWhileTyping
default:
true |
If false , indicates that search will only occur on enter key press. If true , indicates that the Geocoder will search on the input box being updated above the minLength option.
|
options.fuzzyMatch
default:
true |
Set to false to disable fuzzy search.
|
options.zoom
default:
16 |
On geocoded result what zoom level should the map animate to when a bbox isn't found in the response. If a bbox is found the map will fit to the bbox. |
options.maxZoom
default:
18 |
On geocoded result what max zoom level should the map animate to when a bbox isn't found in the response. Used for small features. If a bbox is found the map will fit to the bbox. |
options.collapsed
default:
false |
If true , the geocoder control will collapse until hovered or in focus.
|
options.clearOnBlur
default:
false |
If true , the geocoder control will clear its value when the input blurs.
|
options.filter
(feature: Feature) => boolean ?
|
A function which accepts a Feature in the Carmen GeoJSON format to filter out results from the Geocoding API response before they are included in the suggestions list.
Return true to keep the item, false otherwise.
|
options.class | Class of the root element. |
options.enableReverse
(boolean |
"always" )?
default:
false |
Set to true to enable reverse geocoding button with title.
Set to "always" to reverse geocoding be always active.
|
options.reverseActive
default:
false |
Set to true to programatically toggle reverse mode.
Useful only if enableReverse is true .
|
options.reverseButtonTitle
default:
"toggle reverse geocoding" |
Reverse toggle button title. |
options.clearButtonTitle
default:
"clear" |
Clear button title. |
options.showPlaceType
(
false |
"always" |
"ifNeeded" )?
default:
"ifNeeded" |
Set to false to hide place/POI type.
If set to "always" then type is shown for all items.
If set to "ifNeeded" then type is shown only for places/POIs not determined from the icon.
|
options.showFullGeometry
default:
true |
Set to true to show full feature geometry of the chosen result. Otherwise only marker will be shown.
|
options.country
default:
undefined (use all countries) |
Limit search to specified country(ies). Specify asalpha-2 ISO 3166 lowercase code. |
options.types
default:
undefined (all available feature types except poi and major_landform are returned) |
Filter of feature types to return. Check out the feature types list. For the poi feature type, it is possible also to add the PoiCategory as part of the query string. For example: coffee Java Hut .
|
options.excludeTypes
default:
false |
Set to true to use all available feature types except those mentioned in types .
|
options.apiUrl
default:
MapTiler Geocoding API URL |
Geocoding API URL. |
options.fetchParameters
default:
undefined |
Extra fetch parameters. |
options.iconsBaseUrl
default:
"icons/" for Svelte apps, otherwise https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/ |
Base URL for POI icons. |
options.adjustUrlQuery
(sp: URLSearchParams) => void default: empty function
|
Function to adjust URL search parameters. The function receives a URLSearchParams as a parameter. |
options.selectFirst
default:
true |
Automatically select the first feature from the result list. |
options.flyToSelected
default:
false |
Fly to selected feature from the result list. |
options.markerOnSelected
default:
true |
Show marker on the selected feature from the result list. |
options.marker
(boolean |
MarkerOptions )?
default:
true |
If true , a Marker
will be added to the map at the location of the user-selected result using a default set of Marker options.
If the value is an object, the marker will be constructed using these options.
If false , no marker will be added to the map. Requires that options.maplibregl also be set.
|
options.showResultMarkers
(boolean |
MarkerOptions )?
default:
true |
If true , a Marker
will be added to the map at the location the top results for the query.
If the value is an object, the marker will be constructed using these options.
If false , no marker will be added to the map. Requires that options.maplibregl also be set.
|
options.flyTo
(boolean |
(
FlyToOptions & FitBoundsOptions ))?
default:
true |
If false , animating the map to a selected result is disabled. If true , animating the map will use the default animation parameters.
If an object, it will be passed as options to the map flyTo or fitBounds method providing control over the animation of the transition.
|
options.fullGeometryStyle | Style of the full feature geometry. |
Methods
Geocoding control available methods.
Set the query and optionally submit it.
If the query string value is a pair of bare numbers, it is interpreted as lat,lng
,
in addition to supporting all coordinate formats supported by [geo-coordinates-parser](https://www.npmjs.com/package/geo-coordinates-parser).
boolean
)
: Submit the query. Defaults true
.
Focus the query input box.
Blur the query input box.
Change one or more options of existing control.
Events
These events are implemented using EventTarget and CustomEvent.
To add a calback function to a event, do the following (Example of the optionsVisibilityChange
event):
Fired on highlighting search result in the dropdown by hovering it or by keyboard selection.
Feature
| undefined
)
: Event value will be set to the highlighted Feature or to undefined if nothing is highlighted.
Fired on picking the result from the dropdown.
Feature
| undefined
)
: Event value will be set to the picked Feature or to undefined if nothing is picked (eg. search input is cleared).
Fired on the dropdown visibility change.
boolean
)
: Fired with true
value if dropdown list appears, false
if it disappears.
Fired after features are retrieved from the server.
array<Feature>
| undefined
)
: Event value contains list of features
or undefined
.
Fired after features are marked on the map.
array<Feature>
| undefined
)
: Event value contains list of features
or undefined
.
Fired after HTTP response of the geocoding server.
object
)
: Event value contains object with requested url
and responded featureCollection
.
Fired if reverse geocoding button is toggled.
boolean
)
: Event value is true
if reverse geocoding mode is active, otherwise false
.