Geocoding

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 -77.050,38.889 into 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.

Here’s an example that uses the mapbox-gl-geocoder plugin to add forward geocoding to a web app built with Mapbox GL JS. Type in a location to view the raw JSON response for that query. Geocoding results are returned in Carmen GeoJSON format and contain both descriptive location information and geographic information. You can use the geographic information returned in the JSON response to show your query on a map, like in this example, or perform additional spatial analysis.

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.

Source data

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:

  • Country.
  • 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 poi type comprised of features that are particularly prominent or long-lasting such as parks, places of worship, and museums.

Tools

The Mapbox Geocoding API is built on top of carmen, an open source project for Mapnik vector tile-based geocoding. For more on carmen and how it works, see How does carmen work?.

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.

Language support

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:

Arabic, Bulgarian, Bengali, Catalan, Chinese, Chinese (Latin alphabet), Chinese (traditional), Czech, Danish, German, Greek, English, Spanish, Persian/Farsi, Finnish, French, Hebrew (modern), Hindi, Croatian, Hungarian, Indonesian, Italian, Japanese, Kazakh, Korean, Lithuanian, Macedonian, Malay, Norwegian, Dutch, Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Serbian, Serbian (Latin alphabet), Serbian (Cyrillic alphabet), Swedish, Thai, Tagalog, Turkish, Ukranian, Urdu, Vietnamese.

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:

In addition, we offer libraries for:

Here’s an example of the Mapbox GL Geocoder in action with the query parameter autocomplete=true:

geocode animation

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.