Geocoding API

Overview
  • Billed by requests
  • See rates and discounts per Geocoding API request in the pricing page's Search section

Usage of the Geocoding API is measured in API requests. Details about the number of requests included in the free tier and the cost per request beyond what is included in the free tier are available on the pricing page. You may only use responses from the Geocoding API ("Geocodes") in conjunction with a Mapbox map.

The Geocoding API's autocomplete parameter is enabled by default. The autocomplete parameter is ideal for applications in which you want to suggest search results while a user enters their query. If you are using the API with autocomplete enabled, you will likely accumulate one API request per keystroke. For example, if you have autocomplete turned on and you set up your application to make a Geocoding API request every time a user types a character into a search bar, then a user typing "coff" looking for "coffee shops" will be making four Geocoding API requests, one for each letter.

To reduce the number of requests made while autocomplete is enabled, you can wait to begin making API requests until a specific number of characters are entered. The Geocoding API doesn't have a parameter for limiting requests built in, but you can use the Mapbox GL Geocoder (discussed below in the Geocoding-related libraries and plugins section), which does have that option, or you can write it into your application directly.

Billing for batch geocoding requests

Batch geocoding allows you to have multiple geocoding queries in a single request.

Each individual semicolon-separated search in a batch geocoding request counts as one request. For example, a request that contains three semicolon-separated search strings would count as three requests and be billed as such. These three requests would be reflected on your statistics graph and your bill.

Batch geocoding is only available using the mapbox.places-permanent endpoint. If you're interested in using the mapbox.places-permanent endpoint, contact Mapbox sales.

We have several tools across platforms that allow you to integrate the Mapbox Geocoding API into your existing applications, including:

When using a search-related library or plugin with a Mapbox map, you will be billed for the number of search-related requests made in addition to Maps MAUs for mobile applications or map loads or tile requests for web maps (read the Web maps or Mobile applications section above to see which applies to your application).

For libraries and plugins that include autocomplete, searches are billed as one API call per keystroke. For example, if you have autocomplete turned on and a user types "coff" in your application looking for "coffee shops", you will see four Geocoding API requests reflected on your Statistics page for this interaction, one for each letter.

To reduce the total requests sent (and billed), you should configure your application to only call the API after a specific number of characters are typed — usually 1-3 characters is a good range to reduce requests with limited impact on user experience. If you are using the Mapbox GL Geocoder, you can set this preference using setMinLength.