@maptiler/geocoding-control
Version:
The Javascript & TypeScript Map Control component for MapTiler Geocoding service. Easy to be integrated into any JavaScript mapping application.
270 lines (269 loc) • 8.34 kB
TypeScript
import { BBox, EnableReverse, Feature, ProximityRule, ShowPlaceType, TypeRule, Worldview } from '../types';
export type MaptilerGeocoderOptions = {
/**
* Callback function to adjust the geocoding URL before fetching.
*
* @param url [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) parameter that can be modified.
*
* Default: Empty function.
*/
adjustUrl?: (url: URL) => void;
/**
* MapTiler API key.
*/
apiKey?: string;
/**
* Geocoding API URL.
*
* Default: MapTiler Geocoding API URL.
*/
apiUrl?: string;
/**
* Bounding box in the format `[minX, minY, maxX, maxY]` to limit search results.
*
* Default: `undefined`.
*/
bbox?: BBox;
/**
* Title of the clear button.
*
* Default: `"clear"`.
*/
clearButtonTitle?: string;
/**
* Clears the result list after picking an item.
* Prevents redisplaying the list when the input box is focused.
*
* Default: `false`.
*/
clearListOnPick?: boolean;
/**
* Clears the input value when it loses focus.
*
* Default: `false`.
*/
clearOnBlur?: boolean;
/**
* Collapses the geocoder control until hovered or focused.
*
* Default: `false`.
*/
collapsed?: boolean;
/**
* Limits search to the specified country or countries.
*
* Default: `undefined` (all countries).
*/
country?: string | string[];
/**
* Time delay (in milliseconds) before querying the server after typing in the input box.
* Useful for reducing the number of API calls.
*
* Default: `200`.
*/
debounceSearch?: number;
/**
* Enables reverse geocoding:
* - `"button"`: Enables reverse geocoding button.
* - `"always"`: Reverse geocoding is always active.
*
* Default: `"never"`.
*/
enableReverse?: EnableReverse;
/**
* Custom error message.
*
* Default: `"Something went wrong…"`.
*/
errorMessage?: string;
/**
* Includes all available types except those listed in the `types` option.
*
* See `reverseGeocodingExcludeTypes` for reverse geocoding exclusion.
*
* Default: `false`.
*/
excludeTypes?: 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`.
*/
exhaustiveReverseGeocoding?: boolean;
/**
* Enables fetching the full geometry (polygon etc.) instead of just a point on a picked feature.
*
* Default: `false`.
*/
fetchFullGeometryOnPick?: boolean;
/**
* Additional parameters for fetch requests.
*
* Default: `undefined`.
*/
fetchParameters?: RequestInit;
/**
* 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`.
*/
filter?: (feature: Feature) => boolean;
/**
* Enables fuzzy search.
*
* Default: `true`.
*/
fuzzyMatch?: boolean;
/**
* Base URL for POI icons.
*
* Default: `"https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/"`
*/
iconsBaseUrl?: string;
/**
* Keeps the result list open even if the control is unfocused.
*
* Default: `false`.
*/
keepListOpen?: boolean;
/**
* 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).
*/
language?: string | string[] | null;
/**
* Maximum number of results to display.
*
* See `reverseGeocodingLimit` for reverse geocoding limits.
*
* Default: `5`.
*/
limit?: number;
/**
* Minimum number of characters required to start a search.
*
* Default: `2`.
*/
minLength?: number;
/**
* Custom message for when no results are found.
*
* 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!"
* ```
*/
noResultsMessage?: string;
/**
* Opens the result list above the query input instead of below. Used when mounted at the bottom of a map.
*
* Default: `false`.
*/
openListOnTop?: boolean;
/**
* Custom placeholder for the input box.
*
* Default: `"Search"`.
*/
placeholder?: string;
/**
* 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" } ]`.
*/
proximity?: ProximityRule[] | null;
/**
* Activates reverse geocoding.
*
* Default: `false`.
*/
reverseActive?: boolean;
/**
* Title of the reverse geocoding toggle button.
*
* Default: `"toggle reverse geocoding"`.
*/
reverseButtonTitle?: string;
/**
* Excludes types for reverse geocoding.
*
* Default: Same as `excludeTypes`.
*/
reverseGeocodingExcludeTypes?: boolean;
/**
* 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.
*/
reverseGeocodingLimit?: number;
/**
* 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`.
*/
reverseGeocodingTypes?: TypeRule[];
/**
* Automatically selects the first feature in the result list.
*
* Default: `true`.
*/
selectFirst?: boolean;
/**
* 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"`.
*/
showPlaceType?: ShowPlaceType;
/**
* 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`.
*/
showResultsWhileTyping?: boolean;
/**
* 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).
*/
types?: TypeRule[];
/**
* 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).
*/
worldview?: Worldview;
};