Skip to content

Latest commit

 

History

History
547 lines (327 loc) · 17.9 KB

API.md

File metadata and controls

547 lines (327 loc) · 17.9 KB
Raw

Table of Contents

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? a proximity argument: this is a geographical point given as an object with latitude and longitude properties. Search results closer to this point will be given higher priority.
    • options.trackProximity Boolean If true, the geocoder proximity will automatically update based on the map view. (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, you should specify one type. 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.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)

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

Returns MapboxGeocoder this

setProximity

Set proximity

Parameters

  • proximity Object The new options.proximity value. This is a geographical point given as an object with latitude and longitude properties.

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

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