The Mapbox Geocoding API performs two main tasks: forward geocoding and reverse geocoding. Forward geocoding converts text into geographic coordinates, for example, turning
2 Lincoln Memorial Circle NW into
-77.050,38.889. Reverse geocoding converts geographic coordinates into a text description, for example, turning
2 Lincoln Memorial Circle NW.
All geocoding requests require you to submit a query, or what you’re trying to find. When you make a query, you get a response, a JSON-formatted document of the most relevant results from your query. This guide provides an overview of how the Geocoding API works, how to use it, how to provide feedback, and links to relevant documentation to get you started.
How geocoding works
The Mapbox Geocoding API has two distinct parts: the source data we use to define locations and the tools we use to search for and return those locations.
The Mapbox Geocoding API contains data sources from governments, open data projects, and private companies. In some cases, results from the Geocoding API may differ from Mapbox Streets or OpenStreetMap data.
The Mapbox Geocoding API source data contains the following types of geographic information, ordered from the most granular to the largest:
- Points of interest (POI): A named place including commercial businesses, public buildings, monuments, and parks, among other features.
- Address: A specific mailing address, including the address number if applicable.
- Neighborhood: A colloquial name for a smaller area within a place. Neighborhoods do not necessarily have specific, legally defined boundaries. Only present in some countries.
- Locality: An administrative unit that is smaller than a place. Only present in some countries.
- Postcode: A geographic area of the address component used for sorting mail.
- Place: Cities, towns, and villages. Note that some very large cities (such as Tokyo and Istanbul) may be categorized as regions rather than places.
- District: An administrative unit that is larger than a place but smaller than a region. Only present in some countries.
- Region: States, provinces, and prefectures. This is typically the largest sub-national administrative unit of a country. Note that some very large cities (such as Tokyo and Istanbul) may be categorized as regions rather than places.
- Country: Generally recognized countries or, in some cases like Hong Kong, an area of quasi-national administrative status that has been given a designated country code under ISO 3166-1.
This hierarchy of feature types is also used to determine what will be returned as the encompassing parent features in a Geocoding API response object’s
context property. For example, if the returned feature is a
place (like Detroit), then the encompassing parent features in the
context property will be the
region (the state of Michigan) and the
country (United States).
Customize your queries
The Mapbox Geocoding API accepts a number of optional parameters. You can use these optional parameters to customize your queries so that the most relevant results are returned. These parameters can be specified using URL query parameters, or they can be specified as options with one of our client-side libraries or plugins. These parameters allow you to view results as you type, filter results by geographic feature type, and limit or bias results to a specified area. For example, to limit your search results to addresses in the Washington DC Metro area, you could set the
type parameter to
address and the
bbox parameter to
-77.08,38.90,-76.99,38.95. With those parameters set, your query for
Constitution Ave will only return street addresses in the DC Metro area, and will not include features you’re not interested in (like
Constitution Ave, El Paso, Texas 79908, United States).
Check out the Geocoding API documentation for more information on available features.
The Mapbox Geocoding API accepts a
language query parameter, which allows you to specify the language in which you would like to search. One or more languages can be specified using ISO 639-1 codes. Translation availability varies by language and region, and you can expect more consistent results for areas where the specified language is most widely used. Language support has three different levels:
- Global coverage. These languages are almost always present for
region, and prominent
- Local coverage. These languages may lack global coverage, but they are almost always present for
region, and prominent
placefeatures where they are widely used.
- Limited coverage. These languages are sometimes present, but coverage tends to be inconsistent or geographically constrained.
For a current list of the languages covered at each level, see the Geocoding API documentation.
Search result prioritization
Results from geocoding queries are prioritized differently depending on whether the request was a forward geocode or a reverse geocode.
Result prioritization in forward geocoding
When a forward geocoding query (human-readable text like “San Francisco”) is submitted to the Mapbox Geocoding API, the geocoder uses Carmen, a text search engine, to search our spatial indexes for features that match the user’s query. (For a more detailed description of how the Carmen text search engine works, check out the Carmen documentation.) The geocoder applies filters on the backend to sort the results that match, or partially match, the searched text. These filters are textual relevance and prominence score.
When the geocoder sorts and prioritizes results, the first filter that is applied is
relevance is a value that indicates how well a feature in our dataset matches the query. This property is surfaced in the Geocoding API response, and is a numerical score from
0 (the result does not match the queried text at all) to
1 (the result matches the queried text most completely). You can use the
relevance property to remove results that don’t fully match the query.
In this example query for the address “515 15th St NW, Washington, DC 20004”, the expected result is first in the response with a
0.875. Other results in other cities, since they don’t match the search text as closely, have a
relevance score of
https://api.mapbox.com/geocoding/v5/mapbox.places/515%2015th%20St%20NW%2C%20Washington%2C%20DC%2020004.json?types=address&access_token=<your access token here>
In the case that multiple features have the same
relevance score, a second filter called
score is applied. This is based on the popularity or prominence of a feature. For example, a search for “Paris” will equally match “Paris, France” and “Paris, Texas” — they’ll have the same
relevance score. The
score filter helps break this tie on the backend, and surfaces “Paris, France” first since it is a more popular feature:
https://api.mapbox.com/geocoding/v5/mapbox.places/paris.json?access_token=<your access token here>
Result prioritization in reverse geocoding
For reverse geocodes, results at a given set of coordinates are sorted by order of spatial hierarchy. For example, a more granular feature such as an
postcode will return first in the response before feature types like
country. The full spatial hierarchy, ordered from the most granular to the largest, is: point of interest (POI), address, neighborhood, locality, postcode, place, district, region, and country. (For more details about these geographic information types, see the Source data section.)
This reverse geocoding query example returns features closest to the query point (in the case of point features like
poi) and features that contain the query point (in the case of polygon features like
region), in order of hierarchy from the most granular (address or POI) to the largest feature (country):
https://api.mapbox.com/geocoding/v5/mapbox.places/-122.463%2C%2037.7648.json?access_token=<your access token here>
Access Mapbox geocoding services
You can access the Mapbox Geocoding API directly, through Mapbox Studio, or using one of several wrapper libraries integrate it into applications across platforms.
Use the Geocoding API
You can send requests to the Mapbox Geocoding API via a number of Mapbox mapping tools and plugins, but you can also make calls to the API directly using your preferred HTTP client. If you would like to make calls directly, check out our full API documentation. If you would prefer to use one of our other tools, read on!
Test the Geocoding API
If you would like to get a feel for how the Mapbox Geocoding API works without building a whole application, we also provide an API Playground that works very similarly to the live example at the beginning of this guide. In addition to providing a convenient user interface to test queries, the API playground allows you to test the API’s URL and query parameters, such as autocomplete, proximity, and mode.
Geocoding in Mapbox Studio
The Mapbox Studio dataset editor allows you to create your own custom datasets by importing data, drawing it manually, or searching for it in the Search places toolbar. When you search for places in the toolbar, you’re using the Mapbox Geocoding API to find data to add to your custom dataset. Note that within the dataset editor you can search for and add for countries, regions, districts, postcodes, places, localities, neighborhoods, and addresses, but not POIs.
Libraries and plugins
If you would like to add a search tool to your application to find addresses, POIs, or features near your user’s location, we have several wrapper libraries that allow you to integrate the Mapbox Geocoding API into your existing application seamlessly:
- Web: Mapbox GL Geocoder for Mapbox GL JS and both geocoderControl and geocoder for Mapbox.js
- Android: Mapbox Java SDK
- iOS: MapboxGeocoder.swift
In addition, we offer libraries for:
Here’s an example of the Mapbox GL Geocoder in action with the query parameter
To build a similar web application using Mapbox GL JS, check out the Set a point after Geocoder result example.
Providing geocoding feedback
If you find an error, would like to provide general feedback, or want to request new features, you can use the Geocoding Feedback tool.