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

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

A low-level interface to the Mapbox Geocoding API, useful for complex uses and reverse-geocoding.

Options Value Description
id or url string Value must be
  • A geocoder index ID, e.g. mapbox.places
  • A geocoder API URL, like https://api.mapbox.com/geocoding/v5/mapbox.places/{query}.json
options Object The second argument is optional. If provided, it may include:

Returns a L.mapbox.geocoder object.

geocoder.query(queryString|options, callback)

Queries the geocoder with a query string, and returns its result, if any. This performs forward geocoding.

Options Value Description
queryString (required) string a query, expressed as a string, like 'Arkansas'
options object an object containing the query and options parameters like { query: 'Austin', proximity: L.latlng(lat, lng) }
callback (required) function a callback

Valid options are:

  • proximity: a L.LatLng object or [latitude, longitude] array that will bias the search results toward a geographical point
  • country: a string or array of strings of ISO country codes likes us or ca which will be included in the search. Ommitting this parameter (the default) includes all countries.
  • autocomplete: whether to include results that only contain the prefix of the search terms rather than the full terms. If you have precise input, set this to false. Otherwise, by default it is true.

The callback is called with arguments

  1. An error, if any
  2. The result. This is an object with the following members:

     {
         results: // raw results
         latlng: // a map-friendly latlng array
         bounds: // geojson-style bounds of the first result
         lbounds: // leaflet-style bounds of the first result
     }
    

Example: Live example of geocoder.query centering a map.

Returns: the geocoder object. The return value of this function is not useful - you must use a callback to get results.

geocoder.reverseQuery(location, callback)

Queries the geocoder with a location, and returns its result, if any. This performs reverse geocoding.

Options Value Description
location (required) object A query, expressed as an object:
  • [lon, lat] // an array of lon, lat
  • { lat: 0, lon: 0 } // a lon, lat object
  • { lat: 0, lng: 0 } // a lng, lat object
The first argument can also be an array of objects in that form to geocode more than one item.
callback (required) function The callback is called with arguments
  • An error, if any
  • The result. This is an object of the raw result from Mapbox.

Returns: the geocoder object. The return value of this function is not useful - you must use a callback to get results.