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

adjustUrl
(url: URL) => void?
default: empty function
 Callback function to adjust the geocoding URL before fetching.
apiKey
string?
Maptiler API key. Not needed if used with MapTiler SDK.
apiUrl
string?
default: MapTiler Geocoding API URL
 Geocoding API URL.
bbox
[number, number, number, number]?
Bounding box in the format [minX, minY, maxX, maxY] to limit search results.
class
string?
CSS class for the root element.
clearButtonTitle
string?
default: "clear"
 Title of the clear button.
clearListOnPick
boolean?
default: false
 Clears the result list after picking an item. Prevents redisplaying the list when the input box is focused.
clearOnBlur
boolean?
default: false
 Clears the input value when it loses focus.
collapsed
boolean?
default: false
 Collapses the geocoder control until hovered or focused.
country
(string | string[])?
default: undefined (use all countries)
 Limits search to the specified country or countries. Specify as alpha-2 ISO 3166 lowercase code.
debounceSearch
number?
default: 200
 Time delay (in milliseconds) before querying the server after typing in the input box. Useful for reducing the number of API calls.
enableReverse
EnableReverse?
default: "never"
 Enables reverse geocoding. See EnableReverse for all options.
errorMessage
string?
default: "Something went wrong…"
 Custom error message.
excludeTypes
boolean?
default: false
 Includes all available types except those listed in the types option. See reverseGeocodingExcludeTypes for reverse geocoding exclusion.
exhaustiveReverseGeocoding
boolean?
default: false
 Uses the limit option value for reverse geocoding even if the types option has multiple elements. Works only if enabled on the server.
fetchParameters
RequestInit?
default: undefined
 Additional parameters for fetch requests.
filter
(feature: Feature) => boolean?
default: A function that always returns true
 Callback function to filter results from the Geocoding API response. The function should return true to keep an item, or false to exclude it.
flyTo
(boolean | null | (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.
flyToSelected
boolean?
default: false
 Animates the map to the selected feature from the result list.
fullGeometryStyle
Object?
Style of the full feature geometry.
fuzzyMatch
boolean?
default: true
 Enables fuzzy search.
iconsBaseUrl
string?
default: "icons/" for Svelte apps, otherwise https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/
 Base URL for POI icons.
keepListOpen
boolean?
default: false
 Keeps the result list open even if the control is unfocused.
language
(string | string[] | null)?
default: undefined (uses the browser's language settings)
 Language for response text and query weighting. Accepts IETF language tags. Set to null or an empty string to disable language-specific searching.
limit
number?
default: 5
 Maximum number of results to display. See reverseGeocodingLimit for reverse geocoding limits.
marker
(boolean | null | MarkerOptions | (map: Map, feature?: Feature) => undefined | null | Marker )?
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 or null, no marker will be added to the map. Requires that options.maplibregl also be set. If the value is a function then it can return instance of the Marker
markerOnSelected
boolean?
default: true
 Displays a marker on the selected feature from the result list.
minLength
number?
default: 2
 Minimum number of characters required to start a search.
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!"
 Custom message for when no results are found.
pickedResultStyle
PickedResultStyle?
default: "full-geometry"
 Style of the picked result on the map. See PickedResultStyle for all options.
placeholder
string?
default: "Search"
 Custom placeholder for the input box.
proximity
ProximityRule[] | null | undefined?
default: [{ type: "server-geolocation" }]
 Prioritizes search results closer to a proximity point. The first matching rule in the array is used. Set to null to disable proximity.
reverseActive
boolean?
default:false
 Activates reverse geocoding.
reverseButtonTitle
string?
default: "toggle reverse geocoding"
 Title of the reverse geocoding toggle button.
reverseGeocodingExcludeTypes
boolean?
default: Same as excludeTypes
 Excludes types for reverse geocoding.
reverseGeocodingLimit
number?
default: The value of the limit option if set. If effective types contain a single value, the default is 1. In all other cases, this option is not used.
Limits results for reverse geocoding. Applied only if value is 1 or effective types contain a single value. See also reverseGeocodingTypes option.
reverseGeocodingTypes
TypeRule[]?
default: Same as types
 Specifies types for reverse geocoding. If effective types are multiple values, the limit/reverseGeocodingLimit option is ignored. See also reverseGeocodingLimit option.
selectFirst
boolean?
default: true
 Automatically selects the first feature in the result list.
showPlaceType
ShowPlaceType?
default: "if-needed"
 Indicates when to show place/POI types in the dropdown.
showResultMarkers
(boolean | null | MarkerOptions | (map: Map, feature?: Feature) => undefined | null | Marker )?
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.
showResultsWhileTyping
boolean?
default: true
 Displays results while typing
  • false: Search occurs only on pressing the Enter key.
  • true: Search begins when the input meets the minLength requirement.
types
TypeRule[]?
default: undefined (uses server default feature types)
 Types to query, either as an array or [minZoom, maxZoom, type] format. minZoom is inclusive, maxZoom is exclusive, and either can be null or undefined for unbounded values. See reverseGeocodingTypes option for reverse geocoding types. Check out the feature types list.
zoom
Record<string, number>?
default: ZOOM_DEFAULTS
 Specifies the zoom level to animate the map to for a geocoded result when no bounding box is present or when the result is a point. If a bounding box is present and not a point, the map will fit to the bounding box. Values are key-value pairs where the key is a <type> or <type>.<category> and the value is the zoom level.

Methods

Geocoding control available methods.

Events

These events are implemented using EventTarget and CustomEvent.

Universal example for MapLibre GL, MapTiler SDK, Leaflet and Openlayers:

For vanilla JS EventTarget API is used.