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 (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 `undefined` or `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.trackProximity
boolean?
default: true
 If true, the geocoder proximity will automatically update based on the map view.
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.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.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.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.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.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.reverseButtonTitle
string?
default: "toggle reverse geocoding"
 Reverse toggle button title.
options.reverseActive
boolean?
default:false
 Set to true to programatically toggle reverse mode. Useful only if enableReverse is true.
options.clearButtonTitle
string?
default: "clear"
 Clear button title.
options.showFullGeometry
boolean?
default: true
 Set to true to show full feature geometry of the chosen result. Otherwise only marker will be shown.
options.fullGeometryStyle
Object?
Style of the full feature geometry.
options.fuzzyMatch
boolean?
default: true
 Set to false to disable fuzzy search.
options.limit
number?
default: 5
 Maximum number of results to show.
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 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.

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