Mapbox.js is no longer in active development. To learn more about our newer mapping tools see Mapbox GL JS.

You are viewing an older version of Mapbox.js. Check out v3.3.1 for the latest.

L.mapbox.geocoderControl(id|url, options)

Adds geocoder functionality as well as a UI element to a map. This uses the Mapbox Geocoding API.

Options Value Description
id or url (required) string Either a
  • An geocoder index ID, e.g. mapbox.places
  • A geocoder API URL, like https://api.mapbox.com/geocoding/v5/mapbox.places/{query}.json
options object An options argument with the same options as the L.Control class, as well as:
  • keepOpen: a boolean for whether the control will stay open always rather than being toggled. Default false. See live example.
  • accessToken: Mapbox API access token. Overrides L.mapbox.accessToken for this control.
  • autocomplete: automatically search and show results as you type. Default: false.

The options object can also include queryOptions which are passed to the geocoder.query method: see that method for full documentation of those options.


var map = L.map('map')
    .setView([37, -77], 5)

Returns a L.mapbox.geocoderControl object.

Class: L.mapbox.GeocoderControl


Set the url used for geocoding.

Options Value Description
url string A geocoding url

Returns: the geocoder control object


Set the map id used for geocoding.

Options Value Description
id string A map id to geocode from

Returns: the geocoder control object


Set the TileJSON used for geocoding.

Options Value Description
tilejson object A TileJSON object

Returns: the geocoder object

geocoderControl.on(event, callback)

Bind a listener to an event emitted by the geocoder control. Supported additional events are

Event Description
found A successful search. The event's results property contains the raw results.
notfound A search request succeeded but didn't find any results.
error A network error. The event's error property contains the raw HTTP error.
select Fired when the user selects a location from a list of options returned from a geocoding request. The event's feature property contains the selected GeoJSON Feature.
autoselect Fired when the control automatically selects the first result of a query that returns only one result, and repositions the map accordingly. The event's feature property contains the selected GeoJSON feature.