--- title: "MaptilerGeocoderOptions | Geocoding | JavaScript maps SDK" description: "Documentation for Search and Geocoding control" --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # Type Alias MaptilerGeocoderOptions type MaptilerGeocoderOptions \= {     [adjustUrl](#adjusturl)?: (url: URL) \=> void;     [apiKey](#apikey)?: string;     [apiUrl](#apiurl)?: string;     [bbox](#bbox)?: [BBox](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/BBox/);     [clearButtonTitle](#clearbuttontitle)?: string;     [clearListOnPick](#clearlistonpick)?: boolean;     [clearOnBlur](#clearonblur)?: boolean;     [collapsed](#collapsed)?: boolean;     [country](#country)?: string | string\[\];     [debounceSearch](#debouncesearch)?: number;     [enableReverse](#enablereverse)?: [EnableReverse](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/EnableReverse/);     [errorMessage](#errormessage)?: string;     [excludeTypes](#excludetypes)?: boolean;     [exhaustiveReverseGeocoding](#exhaustivereversegeocoding)?: boolean;     [fetchFullGeometryOnPick](#fetchfullgeometryonpick)?: boolean;     [fetchParameters](#fetchparameters)?: RequestInit;     [filter](#filter)?: (feature: [Feature](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/Feature/)) \=> boolean;     [fuzzyMatch](#fuzzymatch)?: boolean;     [iconsBaseUrl](#iconsbaseurl)?: string;     [keepListOpen](#keeplistopen)?: boolean;     [language](#language)?: string | string\[\] | null;     [limit](#limit)?: number;     [minLength](#minlength)?: number;     [noResultsMessage](#noresultsmessage)?: string;     [openListOnTop](#openlistontop)?: boolean;     [placeholder](#placeholder)?: string;     [proximity](#proximity)?: [ProximityRule](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/ProximityRule/)\[\] | null;     [reverseActive](#reverseactive)?: boolean;     [reverseButtonTitle](#reversebuttontitle)?: string;     [reverseGeocodingExcludeTypes](#reversegeocodingexcludetypes)?: boolean;     [reverseGeocodingLimit](#reversegeocodinglimit)?: number;     [reverseGeocodingTypes](#reversegeocodingtypes)?: [TypeRule](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/TypeRule/)\[\];     [selectFirst](#selectfirst)?: boolean;     [showPlaceType](#showplacetype)?: [ShowPlaceType](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/ShowPlaceType/);     [showResultsWhileTyping](#showresultswhiletyping)?: boolean;     [types](#types)?: [TypeRule](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/TypeRule/)\[\];     [worldview](#worldview)?: [Worldview](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/Worldview/); } #### Implemented by - [MaptilerGeocoderElement](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/classes/MaptilerGeocoderElement/) - Defined in [src/geocoder/geocoder-options.ts:3](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L3) ##### Index ### Properties[](#properties) [adjustUrl?](#adjusturl) [apiKey?](#apikey) [apiUrl?](#apiurl) [bbox?](#bbox) [clearButtonTitle?](#clearbuttontitle) [clearListOnPick?](#clearlistonpick) [clearOnBlur?](#clearonblur) [collapsed?](#collapsed) [country?](#country) [debounceSearch?](#debouncesearch) [enableReverse?](#enablereverse) [errorMessage?](#errormessage) [excludeTypes?](#excludetypes) [exhaustiveReverseGeocoding?](#exhaustivereversegeocoding) [fetchFullGeometryOnPick?](#fetchfullgeometryonpick) [fetchParameters?](#fetchparameters) [filter?](#filter) [fuzzyMatch?](#fuzzymatch) [iconsBaseUrl?](#iconsbaseurl) [keepListOpen?](#keeplistopen) [language?](#language) [limit?](#limit) [minLength?](#minlength) [noResultsMessage?](#noresultsmessage) [openListOnTop?](#openlistontop) [placeholder?](#placeholder) [proximity?](#proximity) [reverseActive?](#reverseactive) [reverseButtonTitle?](#reversebuttontitle) [reverseGeocodingExcludeTypes?](#reversegeocodingexcludetypes) [reverseGeocodingLimit?](#reversegeocodinglimit) [reverseGeocodingTypes?](#reversegeocodingtypes) [selectFirst?](#selectfirst) [showPlaceType?](#showplacetype) [showResultsWhileTyping?](#showresultswhiletyping) [types?](#types) [worldview?](#worldview) ## Properties[](#properties-1) ### `Optional`adjustUrl[](#adjusturl) adjustUrl?: (url: URL) \=> void Callback function to adjust the geocoding URL before fetching. #### Type Declaration - - (url: URL): void - #### Parameters - url: URL [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) parameter that can be modified. Default: Empty function. #### Returns void - Defined in [src/geocoder/geocoder-options.ts:11](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L11) ### `Optional`apiKey[](#apikey) apiKey?: string MapTiler API key. - Defined in [src/geocoder/geocoder-options.ts:16](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L16) ### `Optional`apiUrl[](#apiurl) apiUrl?: string Geocoding API URL. Default: MapTiler Geocoding API URL. - Defined in [src/geocoder/geocoder-options.ts:23](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L23) ### `Optional`bbox[](#bbox) bbox?: [BBox](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/BBox/) Bounding box in the format `[minX, minY, maxX, maxY]` to limit search results. Default: `undefined`. - Defined in [src/geocoder/geocoder-options.ts:30](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L30) ### `Optional`clearButtonTitle[](#clearbuttontitle) clearButtonTitle?: string Title of the clear button. Default: `"clear"`. - Defined in [src/geocoder/geocoder-options.ts:37](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L37) ### `Optional`clearListOnPick[](#clearlistonpick) clearListOnPick?: boolean Clears the result list after picking an item. Prevents redisplaying the list when the input box is focused. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:45](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L45) ### `Optional`clearOnBlur[](#clearonblur) clearOnBlur?: boolean Clears the input value when it loses focus. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:52](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L52) ### `Optional`collapsed[](#collapsed) collapsed?: boolean Collapses the geocoder control until hovered or focused. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:59](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L59) ### `Optional`country[](#country) country?: string | string\[\] Limits search to the specified country or countries. Default: `undefined` (all countries). - Defined in [src/geocoder/geocoder-options.ts:66](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L66) ### `Optional`debounceSearch[](#debouncesearch) debounceSearch?: number Time delay (in milliseconds) before querying the server after typing in the input box. Useful for reducing the number of API calls. Default: `200`. - Defined in [src/geocoder/geocoder-options.ts:74](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L74) ### `Optional`enableReverse[](#enablereverse) enableReverse?: [EnableReverse](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/EnableReverse/) Enables reverse geocoding: - `"button"`: Enables reverse geocoding button. - `"always"`: Reverse geocoding is always active. Default: `"never"`. - Defined in [src/geocoder/geocoder-options.ts:83](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L83) ### `Optional`errorMessage[](#errormessage) errorMessage?: string Custom error message. Default: `"Something went wrong…"`. - Defined in [src/geocoder/geocoder-options.ts:90](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L90) ### `Optional`excludeTypes[](#excludetypes) excludeTypes?: boolean Includes all available types except those listed in the `types` option. See `reverseGeocodingExcludeTypes` for reverse geocoding exclusion. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:99](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L99) ### `Optional`exhaustiveReverseGeocoding[](#exhaustivereversegeocoding) exhaustiveReverseGeocoding?: boolean Uses the `limit` option value for reverse geocoding even if the `types` option has multiple elements. Works only if enabled on the server. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:107](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L107) ### `Optional`fetchFullGeometryOnPick[](#fetchfullgeometryonpick) fetchFullGeometryOnPick?: boolean Enables fetching the full geometry (polygon etc.) instead of just a point on a picked feature. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:114](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L114) ### `Optional`fetchParameters[](#fetchparameters) fetchParameters?: RequestInit Additional parameters for fetch requests. Default: `undefined`. - Defined in [src/geocoder/geocoder-options.ts:121](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L121) ### `Optional`filter[](#filter) filter?: (feature: [Feature](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/Feature/)) \=> boolean Callback function to filter results from the Geocoding API response. The function should return `true` to keep an item, or `false` to exclude it. Default: A function that always returns `true`. - Defined in [src/geocoder/geocoder-options.ts:129](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L129) ### `Optional`fuzzyMatch[](#fuzzymatch) fuzzyMatch?: boolean Enables fuzzy search. Default: `true`. - Defined in [src/geocoder/geocoder-options.ts:136](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L136) ### `Optional`iconsBaseUrl[](#iconsbaseurl) iconsBaseUrl?: string Base URL for POI icons. Default: `"https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/"` - Defined in [src/geocoder/geocoder-options.ts:143](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L143) ### `Optional`keepListOpen[](#keeplistopen) keepListOpen?: boolean Keeps the result list open even if the control is unfocused. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:150](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L150) ### `Optional`language[](#language) language?: string | string\[\] | null Language for response text and query weighting. Accepts IETF language tags. Set to `null` or an empty string to disable language-specific searching. Default: `undefined` (uses the browser's language settings). - Defined in [src/geocoder/geocoder-options.ts:159](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L159) ### `Optional`limit[](#limit) limit?: number Maximum number of results to display. See `reverseGeocodingLimit` for reverse geocoding limits. Default: `5`. - Defined in [src/geocoder/geocoder-options.ts:168](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L168) ### `Optional`minLength[](#minlength) minLength?: number Minimum number of characters required to start a search. Default: `2`. - Defined in [src/geocoder/geocoder-options.ts:175](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L175) ### `Optional`noResultsMessage[](#noresultsmessage) noResultsMessage?: string Custom message for when no results are found. Default: ```typescript "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!" ``` - Defined in [src/geocoder/geocoder-options.ts:187](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L187) ### `Optional`openListOnTop[](#openlistontop) openListOnTop?: boolean Opens the result list above the query input instead of below. Used when mounted at the bottom of a map. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:194](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L194) ### `Optional`placeholder[](#placeholder) placeholder?: string Custom placeholder for the input box. Default: `"Search"`. - Defined in [src/geocoder/geocoder-options.ts:201](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L201) ### `Optional`proximity[](#proximity) proximity?: [ProximityRule](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/ProximityRule/)\[\] | null Prioritizes search results closer to a proximity point. The first matching rule in the array is used. Set to `null` to disable proximity. Default: `[ { type: "server-geolocation" } ]`. - Defined in [src/geocoder/geocoder-options.ts:210](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L210) ### `Optional`reverseActive[](#reverseactive) reverseActive?: boolean Activates reverse geocoding. Default: `false`. - Defined in [src/geocoder/geocoder-options.ts:217](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L217) ### `Optional`reverseButtonTitle[](#reversebuttontitle) reverseButtonTitle?: string Title of the reverse geocoding toggle button. Default: `"toggle reverse geocoding"`. - Defined in [src/geocoder/geocoder-options.ts:224](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L224) ### `Optional`reverseGeocodingExcludeTypes[](#reversegeocodingexcludetypes) reverseGeocodingExcludeTypes?: boolean Excludes types for reverse geocoding. Default: Same as `excludeTypes`. - Defined in [src/geocoder/geocoder-options.ts:231](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L231) ### `Optional`reverseGeocodingLimit[](#reversegeocodinglimit) reverseGeocodingLimit?: number Limits results for reverse geocoding. Applied only if value is 1 or effective types contain a single value. See also `reverseGeocodingTypes` option. 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. - Defined in [src/geocoder/geocoder-options.ts:241](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L241) ### `Optional`reverseGeocodingTypes[](#reversegeocodingtypes) reverseGeocodingTypes?: [TypeRule](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/TypeRule/)\[\] Specifies types for reverse geocoding. If effective types are multiple values, the `limit`/`reverseGeocodingLimit` option is ignored. See also `reverseGeocodingLimit` option. Default: Same as `types`. - Defined in [src/geocoder/geocoder-options.ts:252](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L252) ### `Optional`selectFirst[](#selectfirst) selectFirst?: boolean Automatically selects the first feature in the result list. Default: `true`. - Defined in [src/geocoder/geocoder-options.ts:259](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L259) ### `Optional`showPlaceType[](#showplacetype) showPlaceType?: [ShowPlaceType](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/ShowPlaceType/) Indicates when to show place/POI types in the dropdown: - `"never"`: Hide the type. - `"always"`: Always show the type. - `"if-needed"`: Show the type only if it cannot be determined from the icon. Default: `"if-needed"`. - Defined in [src/geocoder/geocoder-options.ts:269](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L269) ### `Optional`showResultsWhileTyping[](#showresultswhiletyping) showResultsWhileTyping?: boolean Displays results while typing: - `false`: Search occurs only on pressing the Enter key. - `true`: Search begins when the input meets the `minLength` requirement. Default: `true`. - Defined in [src/geocoder/geocoder-options.ts:278](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L278) ### `Optional`types[](#types) types?: [TypeRule](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/TypeRule/)\[\] 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. Default: `undefined` (uses server default feature types). - Defined in [src/geocoder/geocoder-options.ts:288](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L288) ### `Optional`worldview[](#worldview) worldview?: [Worldview](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/types/Worldview/) Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country. This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Available options: - `"ch"`: Use the worldview of Switzerland - `"us"`: Use the worldview of US - `"auto"`: Automatically determine the worldview by the location of the client - `undefined`: Do not use any particular worldview (disputed areas are returned without country information, countries with disputed borders are returned without full geometry) Default: `undefined` (no worldview). - Defined in [src/geocoder/geocoder-options.ts:305](https://github.com/maptiler/maptiler-geocoding-control/blob/7abb332debfe243d5d21e0823dd92a94259b6d8e/src/geocoder/geocoder-options.ts#L305)