You are viewing documentation for an older version of the Mapbox API. Check out v4 for the latest.


Geocoding requests are queries composed of location text or lat/lon coordinates that can be used to find corresponding place data. Mapbox geocodes using the {mapid} in requests allowing individual maps to include additional custom datasources for use when geocoding. Projects include the following default datasources which can be supplemented by additional uploaded data files:

Country (admin0)Quattroshapes admin0
Province (admin1)Quattroshapes admin1
PostcodeUS Census TIGER, US Census zipcode DB
PlaceUS Census TIGER, US Census zipcode DB, Flickr Shapefiles 2.0
Street nameOpenStreetMap
AddressUS Census TIGER

Forward geocoding{mapid}/geocode/{query}.json

Request feature data that best matches the input {query} text. The response includes one or more results ordered by relevance.

Reverse geocoding{mapid}/geocode/{lon},{lat}.json

Request feature data located at the input {lon},{lat} coordinates. The response includes at most one result from each geocoding index.

Batch requests{mapid}/geocode/{query};{query}; ... ;{query}.json{mapid}/geocode/{lon},{lat};{lon},{lat}; ... ;{lon},{lat}.json

Request multiple forward or reverse geocoding queries to be fulfilled at once. Each input query should be separated by a semicolon. The response is an array of individual geocoder responses matching the format of single geocoding requests. Up to 50 queries may be included in a single batch geocoding request.