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. 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.

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

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).

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?.

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.

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. 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 country, region, and prominent place features.
  • Local coverage. These languages may lack global coverage, but they are almost always present for country, region, and prominent place features 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.

Textual relevance

When the geocoder sorts and prioritizes results, the first filter that is applied is relevance. 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 relevance of 0.875. Other results in other cities, since they don’t match the search text as closely, have a relevance score of 0.2.

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>
Prominence score

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 address, poi, or postcode will return first in the response before feature types like region or 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 address and poi) and features that contain the query point (in the case of polygon features like place or 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.

Visit the API Playground

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

If you find an error, would like to provide general feedback, or want to request new features, you can use the Geocoding Feedback tool.