Skip to main content

Search products

Additional Developer Resources

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.

Geocoding demo​

In the demo below, you can type in a location to make a Geocoding API query view then view the response as raw JSON:

The demo uses the Mapbox GL geocoder plugin to add forward geocoding to a web app built with Mapbox GL JS.

Geocoding results are returned in 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 do 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 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 large cities (such as Tokyo and Istanbul) may be categorized as regions rather than places.
  • Country: Refers to generally recognized countries or, in some cases, areas with quasi-national administrative status such as Hong Kong. These areas have been assigned 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).

Customizing your queries​

The Mapbox Geocoding API accepts many 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).

Read 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 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_MAPBOX_ACCESS_TOKEN
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_MAPBOX_ACCESS_TOKEN

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_MAPBOX_ACCESS_TOKEN

Access Mapbox geocoding services​

You can access the Mapbox Geocoding API directly, through Mapbox Studio, or using one of several wrapper libraries to integrate it into applications across platforms.

Use the Mapbox Geocoding API​

You can send requests to the Mapbox Geocoding API via many 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, read the Geocoding API documentation. If you want to use one of our other tools, see the Libraries and plugins section of this guide.

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 the Geocoding API Playground. Besides 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 or proximity.

Visit the Search Playgroundchevron-right

Geocoding in Mapbox Studio​

Mapbox Studio uses geocoding in the dataset editor. When you search for places in the dataset editor's toolbar, you're using the Mapbox Geocoding API to find data to add to your custom dataset. Within the dataset editor, you can search for and add 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:

Here's an example of the Mapbox GL Geocoder in a map created with Mapbox GL JS with the query parameter autocomplete=true:

To build a similar web application using Mapbox GL JS, explore the Set a point after geocoder result example.

Pricing​

Use of the Geocoding API is billed by API requests. For more details, see the Geocoding API pricing page.

Providing geocoding feedback​

If you find an error or want to contribute map data, you can use our Improve the map tool.

Additional Developer Resources
Was this page helpful?