The Mapbox Geocoding API lets you convert location text into geographic coordinates (1600 Pennsylvania Ave NW → -77.0366,38.8971).


>>> import geocoder
>>> g = geocoder.mapbox('San Francisco, CA', key='<TOKEN>')
>>> g.json

Reverse Geocoding

>>> import geocoder
>>> latlng = [45.3, -105.1]
>>> g = geocoder.mapbox(latlng, method='reverse')
>>> g.json

Geocoding with Proximity

Request feature data that best matches input and is biased to the given {latitude} and {longitude} coordinates. In the above example, a query of “200 Queen Street” returns a subset of all relevant addresses in the world. By adding the proximity option, this subset can be biased towards a given area, returning a more relevant set of results.

>>> import geocoder
>>> latlng = [45.3, -66.1]
>>> g = geocoder.mapbox("200 Queen Street", proximity=latlng)
>>> g.address
"200 Queen St, Saint John, E2L 2X1, New Brunswick, Canada"
>>> g = geocoder.mapbox("200 Queen Street")
"200 Queen St W, Toronto, M5T 1T9, Ontario, Canada"

For consistency purpose, geocoder also accepts other formats for the ‘proximity’ parameter, which could be a bbox, bounds or a dictionnary with all directions. Please refer to teh page ‘Access to geocoder results‘ for more details.

Command Line Interface

$ geocode 'San Francisco, CA' --provider mapbox --out geojson
$ geocode '45.15, -75.14' --provider mapbox --method reverse

Environment Variables

To make sure your API key is store safely on your computer, you can define that API key using your system’s environment variables.

$ export MAPBOX_ACCESS_TOKEN=<Secret Access Token>


  • location: Your search location you want geocoded.
  • proximity: Search nearby [lat, lng].
  • key: Use your own access token from Mapbox.
  • country: Filtering by country code {cc} ISO 3166 alpha 2.
  • proximity: Search within given area (bbox, bounds, or around latlng)
  • method: (default=geocode) Use the following:
    • geocode
    • reverse