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, and get a response, or a JSON-formatted document of the most relevant results from your query, in return. 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.
Our Geocoding API relies on a variety of data sources from governments, open data projects, and private companies. Because the Geocoding API relies on a variety of sources, results from the Geocoding API cannot be matched to OpenStreetMap sources.
We’re constantly improving our data and expanding our geographic reach; if you’d like to learn more about our where we currently support geocoding, check out our coverage map.
The Mapbox Geocoding API source data contains the following types of geographic information:
- 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.
- District. An administrative unit that is larger than a place but smaller than a region. Only present in some countries
- Place: Cities, towns, and villages. Note that some very large cities (such as Tokyo and Istanbul) may be categorized as regions rather than places.
- 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.
- 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.
- Points of interest (POI): A named place including commercial businesses, public buildings, monuments, and parks, among other features.
- Landmarks. A subset of the
poitype comprised of features that are particularly prominent or long-lasting such as parks, places of worship, and museums.
Customizing your queries
The Mapbox Geocoding API can accept a number of optional parameters you can use to customize your queries in order to return the most relevant results possible. These parameters can be specified using URL query parameters or as options when building your application 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, if you wanted 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, such as
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. Multilingual geocoding coverage varies and you can expect more consistent results for areas where the specified language is most widely used. We currently support the following languages:
Using 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.
Using the Mapbox 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!
Testing the 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:
- Mapbox GL JS: Mapbox GL Geocoder
- Mapbox.js: geocoderControl and geocoder
- Mapbox Android SDK: Mapbox Android Services
- Mapbox iOS SDK: 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
Occasionally, results may not return as expected. If you find an error, would like to provide general feedback, or want to request new features, you can use the Geocoding Feedback tool.