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)

Add to the map & change position

If you use MapTiler SDK or MapLibre GL, it’s as easy as:

If you want to adjust the position, see the options.

For Leaflet and OpenLayers refer to Usage guide for Leaflet and Usage guide for OpenLayers

Options

Parameters

options (ControlOptions)
Options to provide to the GeocodingControl constructor (ControlOptions).

Properties

options.apiKey
string?
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
number?
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
string?
default: "Search"
 Override the default placeholder attribute value.
options.errorMessage
string?
default: "Something went wrong…"
 Override the default error message.
options.noResultsMessage
string?
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
number?
default: 2
 Minimum number of characters to enter for results to show.
options.bbox
[number, number, number, number]?
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
number?
default: 5
 Maximum number of results to show.
options.language
(string | Array<string>)?
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
boolean?
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
boolean?
default: true
 Set to false to disable fuzzy search.
options.zoom
number?
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
number?
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
boolean?
default: false
 If true, the geocoder control will collapse until hovered or in focus.
options.clearOnBlur
boolean?
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
string?
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
boolean?
default:false
 Set to true to programatically toggle reverse mode. Useful only if enableReverse is true.
options.reverseButtonTitle
string?
default: "toggle reverse geocoding"
 Reverse toggle button title.
options.clearButtonTitle
string?
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
boolean?
default: true
 Set to true to show full feature geometry of the chosen result. Otherwise only marker will be shown.
options.country
(string | Array<string>)?
default: undefined (use all countries)
 Limit search to specified country(ies). Specify asalpha-2 ISO 3166 lowercase code.
options.types
Array<string>?
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
boolean?
default: false
 Set to true to use all available feature types except those mentioned in types.
options.apiUrl
string?
default: MapTiler Geocoding API URL
 Geocoding API URL.
options.fetchParameters
RequestInit?
default: undefined
 Extra fetch parameters.
options.iconsBaseUrl
string?
default: "icons/" for Svelte apps, otherwise https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/
 Base URL for POI icons.
options.adjustUrlQuery
Function?
(sp: URLSearchParams) => void
default: empty function
 Function to adjust URL search parameters. The function receives a URLSearchParams as a parameter.
options.selectFirst
boolean?
default: true
 Automatically select the first feature from the result list.
options.flyToSelected
boolean?
default: false
 Fly to selected feature from the result list.
options.markerOnSelected
boolean?
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
Object?
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):