Skip to content

Latest commit

 

History

History
698 lines (415 loc) · 22.9 KB

API.md

File metadata and controls

698 lines (415 loc) · 22.9 KB
Raw

Table of Contents

getFooterNode

Don't include this as part of the options object when creating a new MapboxGeocoder instance.

MapboxGeocoder

A geocoder component using the Mapbox Geocoding API

Parameters

  • options Object

    • options.accessToken String Required.
    • options.origin String Use to set a custom API origin. (optional, default https://api.mapbox.com)
    • options.mapboxgl Object? A mapbox-gl instance to use when creating Markers. Required if options.marker is true.
    • options.zoom Number 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. (optional, default 16)
    • options.flyTo (Boolean | Object) 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. (optional, default true)
    • options.placeholder String Override the default placeholder attribute value. (optional, default Search)
    • options.proximity (Object | "ip")? a geographical point given as an object with latitude and longitude properties, or the string 'ip' to use a user's IP address location. Search results closer to this point will be given higher priority.
    • options.trackProximity Boolean If true, the geocoder proximity will dynamically update based on the current map view or user's IP location, depending on zoom level. (optional, default true)
    • options.collapsed Boolean If true, the geocoder control will collapse until hovered or in focus. (optional, default false)
    • options.clearAndBlurOnEsc Boolean If true, the geocoder control will clear it's contents and blur when user presses the escape key. (optional, default false)
    • options.clearOnBlur Boolean If true, the geocoder control will clear its value when the input blurs. (optional, default false)
    • options.bbox Array? 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.countries string? a comma separated list of country codes to limit results to specified country or countries.
    • options.types string? a comma seperated list of types that filter results to match those specified. See https://docs.mapbox.com/api/search/#data-types for available types. If reverseGeocode is enabled and no type is specified, the type defaults to POIs. Otherwise, if you configure more than one type, the first type will be used.
    • options.minLength Number Minimum number of characters to enter before results are shown. (optional, default 2)
    • options.limit Number Maximum number of results to show. (optional, default 5)
    • options.language string? Specify the language 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. Defaults to the browser's language settings.
    • options.filter Function? 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.localGeocoder Function? A function accepting the query string which performs local geocoding to supplement results from the Mapbox Geocoding API. Expected to return an Array of GeoJSON Features in the Carmen GeoJSON format.
    • options.externalGeocoder Function? A function accepting the query string and current features list which performs geocoding to supplement results from the Mapbox Geocoding API. Expected to return a Promise which resolves to an Array of GeoJSON Features in the Carmen GeoJSON format.
    • options.reverseMode (distance | score) Set the factors that are used to sort nearby results. (optional, default distance)
    • options.reverseGeocode boolean If true, enable reverse geocoding mode. In reverse geocoding, search input is expected to be coordinates in the form lat, lon, with suggestions being the reverse geocodes. (optional, default false)
    • options.flipCoordinates boolean If true, search input coordinates for reverse geocoding is expected to be in the form lon, lat instead of the default lat, lon. (optional, default false)
    • options.enableEventLogging Boolean Allow Mapbox to collect anonymous usage statistics from the plugin. (optional, default true)
    • options.marker (Boolean | Object) 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.mapboxgl also be set. (optional, default true)
    • options.render Function? A function that specifies how the results should be rendered in the dropdown menu. This function should accepts a single Carmen GeoJSON object as input and return a string. Any HTML in the returned string will be rendered.
    • options.getItemValue Function? A function that specifies how the selected result should be rendered in the search bar. This function should accept a single Carmen GeoJSON object as input and return a string. HTML tags in the output string will not be rendered. Defaults to (item) => item.place_name.
    • options.mode String A string specifying the geocoding endpoint to query. Options are mapbox.places and mapbox.places-permanent. The mapbox.places-permanent mode requires an enterprise license for permanent geocodes. (optional, default mapbox.places)
    • options.localGeocoderOnly Boolean If true, indicates that the localGeocoder results should be the only ones returned to the user. If false, indicates that the localGeocoder results should be combined with those from the Mapbox API with the localGeocoder results ranked higher. (optional, default false)
    • options.autocomplete Boolean Specify whether to return autocomplete results or not. When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly. (optional, default true)
    • options.fuzzyMatch Boolean Specify whether the Geocoding API should attempt approximate, as well as exact, matching when performing searches, or whether it should opt out of this behavior and only attempt exact matching. (optional, default true)
    • options.routing Boolean Specify whether to request additional metadata about the recommended navigation destination corresponding to the feature or not. Only applicable for address features. (optional, default false)
    • options.worldview String Filter results to geographic features whose characteristics are defined differently by audiences belonging to various regional, cultural, or political groups. (optional, default "us")
    • options.enableGeolocation Boolean If true enable user geolocation feature. (optional, default false)
    • options.addressAccuracy ("address" | "street" | "place" | "country") The accuracy for the geolocation feature with which we define the address line to fill. The browser API returns the user's position with accuracy, and sometimes we can get the neighbor's address. To prevent receiving an incorrect address, you can reduce the accuracy of the definition. (optional, default "street")

Examples

var geocoder = new MapboxGeocoder({ accessToken: mapboxgl.accessToken });
map.addControl(geocoder);

Returns MapboxGeocoder this

addTo

Add the geocoder to a container. The container can be either a mapboxgl.Map, an HTMLElement or a CSS selector string.

If the container is a mapboxgl.Map, this function will behave identically to Map.addControl(geocoder). If the container is an instance of HTMLElement, then the geocoder will be appended as a child of that HTMLElement. If the container is a CSS selector string, the geocoder will be appended to the element returned from the query.

This function will throw an error if the container is none of the above. It will also throw an error if the referenced HTML element cannot be found in the document.body.

For example, if the HTML body contains the element <div id='geocoder-container'></div>, the following script will append the geocoder to #geocoder-container:

var geocoder = new MapboxGeocoder({ accessToken: mapboxgl.accessToken });
geocoder.addTo('#geocoder-container');

Parameters

  • container (String | HTMLElement | mapboxgl.Map) A reference to the container to which to add the geocoder

clear

Clear and then focus the input.

Parameters

  • ev Event? the event that triggered the clear, if available

query

Set & query the input

Parameters

  • searchInput string location name or other search input

Returns MapboxGeocoder this

setInput

Set input

Parameters

  • searchInput string location name or other search input
  • showSuggestions boolean display suggestion on setInput call (optional, default false)

Returns MapboxGeocoder this

setProximity

Set proximity

Parameters

  • proximity (Object | "ip") The new options.proximity value. This is a geographical point given as an object with latitude and longitude properties or the string 'ip'.
  • disableTrackProximity Boolean If true, sets trackProximity to false. True by default to prevent trackProximity from unintentionally overriding an explicitly set proximity value. (optional, default true)

Returns MapboxGeocoder this

getProximity

Get proximity

Returns Object The geocoder proximity

setRenderFunction

Set the render function used in the results dropdown

Parameters

  • fn Function The function to use as a render function. This function accepts a single Carmen GeoJSON object as input and returns a string.

Returns MapboxGeocoder this

getRenderFunction

Get the function used to render the results dropdown

Returns Function the render function

setLanguage

Get the language to use in UI elements and when making search requests

Look first at the explicitly set options otherwise use the browser's language settings

Parameters

  • language String Specify the language 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.

Returns MapboxGeocoder this

getLanguage

Get the language to use in UI elements and when making search requests

Returns String The language(s) used by the plugin, if any

getZoom

Get the zoom level the map will move to when there is no bounding box on the selected result

Returns Number the map zoom

setZoom

Set the zoom level

Parameters

  • zoom Number The zoom level that the map should animate to when a bbox isn't found in the response. If a bbox is found the map will fit to the bbox.

Returns MapboxGeocoder this

getFlyTo

Get the parameters used to fly to the selected response, if any

Returns (Boolean | Object) The flyTo option

setFlyTo

Set the flyTo options

Parameters

  • flyTo (Boolean | Object) 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.

getPlaceholder

Get the value of the placeholder string

Returns String The input element's placeholder value

setPlaceholder

Set the value of the input element's placeholder

Parameters

  • placeholder String the text to use as the input element's placeholder

Returns MapboxGeocoder this

getBbox

Get the bounding box used by the plugin

Returns Array<Number> the bounding box, if any

setBbox

Set the bounding box to limit search results to

Parameters

  • bbox Array<Number> a bounding box given as an array in the format [minX, minY, maxX, maxY].

Returns MapboxGeocoder this

getCountries

Get a list of the countries to limit search results to

Returns String a comma separated list of countries to limit to, if any

setCountries

Set the countries to limit search results to

Parameters

  • countries String a comma separated list of countries to limit to

Returns MapboxGeocoder this

getTypes

Get a list of the types to limit search results to

Returns String a comma separated list of types to limit to

setTypes

Set the types to limit search results to

Parameters

  • types
  • countries String a comma separated list of types to limit to

Returns MapboxGeocoder this

getMinLength

Get the minimum number of characters typed to trigger results used in the plugin

Returns Number The minimum length in characters before a search is triggered

setMinLength

Set the minimum number of characters typed to trigger results used by the plugin

Parameters

  • minLength Number the minimum length in characters

Returns MapboxGeocoder this

getLimit

Get the limit value for the number of results to display used by the plugin

Returns Number The limit value for the number of results to display used by the plugin

setLimit

Set the limit value for the number of results to display used by the plugin

Parameters

  • limit Number the number of search results to return

Returns MapboxGeocoder

getFilter

Get the filter function used by the plugin

Returns Function the filter function

setFilter

Set the filter function used by the plugin.

Parameters

  • filter Function 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.

Returns MapboxGeocoder this

setOrigin

Set the geocoding endpoint used by the plugin.

Parameters

  • origin Function A function which accepts an HTTPS URL to specify the endpoint to query results from.

Returns MapboxGeocoder this

getOrigin

Get the geocoding endpoint the plugin is currently set to

Returns Function the endpoint URL

setAccessToken

Set the accessToken option used for the geocoding request endpoint.

Parameters

Returns MapboxGeocoder this

setAutocomplete

Set the autocomplete option used for geocoding requests

Parameters

  • value Boolean The boolean value to set autocomplete to

getAutocomplete

Get the current autocomplete parameter value used for requests

Returns Boolean The autocomplete parameter value

setFuzzyMatch

Set the fuzzyMatch option used for approximate matching in geocoding requests

Parameters

  • value Boolean The boolean value to set fuzzyMatch to

getFuzzyMatch

Get the current fuzzyMatch parameter value used for requests

Returns Boolean The fuzzyMatch parameter value

setRouting

Set the routing parameter used to ask for routable point metadata in geocoding requests

Parameters

  • value Boolean The boolean value to set routing to

getRouting

Get the current routing parameter value used for requests

Returns Boolean The routing parameter value

setWorldview

Set the worldview parameter

Parameters

  • code String The country code representing the worldview (e.g. "us" | "cn" | "jp", "in")

getWorldview

Get the current worldview parameter value used for requests

Returns String The worldview parameter value

on

Subscribe to events that happen within the plugin.

Parameters

  • type String name of event. Available events and the data passed into their respective event objects are:* clear Emitted when the input is cleared
    • loading { query } Emitted when the geocoder is looking up a query
    • results { results } Fired when the geocoder returns a response
    • result { result } Fired when input is set
    • error { error } Error as string
  • fn Function function that's called when the event is emitted.

Returns MapboxGeocoder this;

off

Remove an event

Parameters

  • type String Event name.
  • fn Function Function that should unsubscribe to the event emitted.

Returns MapboxGeocoder this

transformFeatureToGeolocationText

This function transforms the feature from reverse geocoding to plain text with specified accuracy

Parameters

getAddressInfo

This function transforms the feature from reverse geocoding to AddressInfo object

Parameters

Returns object