Mapbox Geocoding API 101

geocode animation

The Mapbox Geocoding API provides access to a collection of tools used to perform address matching that we call geocoding web services. The API can produce both forward (addresses and POIs) and reverse (longitude and latitude) results. This page provides an overview of how the Geocoding API works, how to access the tools, and other details for its use in your applications. For in depth details, see the Geocoding API documentation.

How it works

The Mapbox Geocoding API has two distinct parts: the tools we use for geocoding and the source data we use to feed those tools.


Our main tool for geocoding is called carmen, an open source project for Mapnik vector tile-based geocoding with support for swappable data sources. For more on carmen and how it works, see How does carmen work?

Source data

Licensed under our Terms of Service, the Geocoding API includes place data from a number of sources worldwide. For the most current list of sources, please refer to our data sources page.

General info


Mapbox has extensive global coverage for countries, regions, and populated places. Because each country uses a unique system for managing places and addresses, we’ve developed categorization that captures each system as efficiently as possible. For a complete list of coverage, see our coverage page.

When entering a search query, the geocoder can recognize the following:

  • Country
  • Region: Also variously termed a state, province, or prefecture, this is typically the largest sub-national administrative unit of a country. Note that some very large cities (such as Tokyo, Istanbul, and Greater London) may be located in the Region layer rather than in the Place layer.
  • District: Only present in some countries, this is an administrative unit that is typically larger than a Place, but smaller than a Region.
  • Place: Most cities, towns, and villages, this is generally the name used in postal addresses. Note that some very large cities may be located in the region layer rather than in the Place layer.
  • Locality: Only present in some countries, this is an administrative unit more specific than Place.
  • Postcode: Geographic area generally corresponding to the address component used for sorting mail.
  • Address: A specific mailing address, including the address number if applicable.
  • Neighborhood: Only present in some countries, this is a colloquial name for a smaller area within a Place. Does not necessarily have specific, legally defined borders.
  • POI (point of interest): A named place, can include commercial businesses, public buildings, monuments, and parks, among other features.
  • POI.landmark (landmark): A subset of the POI type designed to only include features that are particularly prominent or long-lasting. Includes features like parks, places of worship, and museums.

Language support

Multilingual geocoding support is available for 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.

If you are interested in multi-lingual geocoding support, please contact support.

Terms of Service

For the most recent Terms of Service that relate to Geocoding, please refer to our Terms of Service page.


Geocoding is included in all plan levels.

For all plans, you can:

  • Display results on any Mapbox map
  • Make up to 600 requests per minute
  • Cache results in your app

For Enterprise plans, you can:

  • Display and use results anywhere
  • Increase rate limits, from 2,400 requests per minute to 30,000 requests per minute
  • Store results permanently

See our pricing page for the most up to date pricing details.

How to provide feedback

From time to time, results may not return as expected. If you find an error or would like to provide feedback, you can submit feedback through our Geocoder Feedback form. You can also provide your email if the data team has follow up questions.

How to use it

Using the Geocoding API in an app

If you would like to add a search tool to your application to find addresses, POIs, or longitude and latitude pairs, you can add plugins to your application.

  • Mapbox GL JS:
  • Mapbox.js:
  • Java (Android, Java SE):
  • Swift or Objective-C (iOS, macOS, tvOS, watchOS):

Using the Geocoding API directly

API responses can be set to a particular language using the language= parameter in an API request.

A sample request for geocoding results in Russian in the Pittsburgh, PA area would look like:<your_token>&language=ru

Geocoding API documentation and sandbox

For complete documentation on our Geocoding API and example requests, see the Geocoding API documentation page. For testing purposes, we also provide a Geocoding Playground that allows you to test queries, filtering, proximity, and more.


Additional questions? Ask our support team or learn more about How Mapbox Works.