Geocoding Control API reference

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 to provide to the GeocodingControl constructor (ControlOptions).

Properties

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
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.

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):