Introduction

The Mapbox web services APIs allow you to programmatically access Mapbox tools and services. You can use these APIs to retrieve information about your account, upload and change resources, use core Mapbox tools, and more.

Mapbox APIs are divided into four distinct services: Maps, Directions, Geocoding, and Accounts. Each of these services has its own overview page in this documentation. These overview pages are divided into the individual APIs that make up the service. The documentation for each API is structured by endpoints. An endpoint is a specific method within an API that performs one action and is located at a specific URL.

The Mapbox APIs described in this documentation are subject to Mapbox's Terms of Service.

Reading this documentation

Each API endpoint in this documentation is described using several parts:

  • The HTTP method. Includes GET, POST, PUT, PATCH, DELETE.
  • The base path. All URLs referenced in the documentation have the base path https://api.mapbox.com. This base path goes before the endpoint path.
  • The endpoint path. For example, /directions/v5/{profile}/{coordinates}.
  • Required parameters. These parameters must be included in a request. In the example above, {profile} and {coordinates} are required parameters. In a request, you will replace the placeholders with real values.
  • Optional parameters. These parameters can be included in a request to customize the query. Query parameters are added to the end of the URL with query string encoding.
  • A token scope. If an API endpoint requires a token scope that the default access token does not have, this scope will be listed.
  • Code examples. Each endpoint has example requests in cURL format. Mapbox also provides several SDKs and libraries that can be used to integrate with our web service APIs. When applicable, the documentation for an endpoint will link to the relevant tool's documentation, which will include code examples in that language.

Access tokens and token scopes

https://api.mapbox.com/{endpoint}?access_token={your_access_token}

Access to Mapbox API endpoints requires a valid access token, which will connect API requests to your account. You need supply a valid access token by using the access_token query parameter in every request. The example requests in this documentation will include your default access token if you are signed into your Mapbox account.

Your default access token is available on your Account Dashboard. You can also create and manage additional tokens on your Access tokens page or with the Tokens API.

When you create a new access token, you can give it one or more token scopes. Each scope adds a different permission to the token, allowing it to be used to access restricted APIs. Throughout this documentation, we specify the scope required to access each endpoint. If no scope is specified, then your default access token will work to access that endpoint.

API versioning

Each Mapbox API has a version string that is specified in the base URL. The version string for a given Mapbox API can be incremented independently from other Mapbox APIs. We encourage you to use the newest available version of the Mapbox APIs.

Backwards compatible changes

The following changes to a Mapbox API are considered backwards compatible. The version string of an API will not be incremented if we:

  • Add properties to JSON objects.
  • Change the number of items returned in a single listing request.
  • Change rate limiting thresholds.
  • Change the structure or length of identifiers generated by the API.
  • Change error messages.

Backwards incompatible changes

The following changes are considered backwards incompatible. The version string of an API will be incremented if we:

  • Remove properties from JSON objects.
  • Change an API's URL structure.

If we deprecate an API or API endpoint that you are using, we will email you to give you at least 90 days' notice.

Rate limit headers

Every Mapbox API response contains the following rate limit headers:

HeaderDescription
X-Rate-Limit-IntervalThe length of the rate-limiting interval in seconds. This will always be 60.
X-Rate-Limit-LimitThe maximum number of requests you can make in the current interval before reaching the limit. The rate limit for each individual API is listed in the rate limits section.
X-Rate-Limit-ResetA Unix timestamp that shows when the current interval will end and the rate limit counter will reset.

The presence of these headers is expected and does not mean there is an error condition.

Rate limits

Your user plan sets the rate limits that cap the number of requests you can make against an API endpoint. If you exceed a rate limit, your request will be throttled and you will receive a HTTP 429 Too Many Requests response from the API. If you need a rate limit that is higher than the default, contact the Mapbox sales team.

The following table lists the default rate limit for each API. Note that all rate limits are counted per access token, not per account.

APIDefault coordinates per requestDefault requests per minute
Datasets API
(Read)
N/A480 requests per minute
Datasets API
(Write)
N/A40 requests per minute
Maps APIN/A100,000 requests per minute
Static API
(Static maps)
N/A600 requests per minute
Static API
(Raster tiles)
N/A2,000 requests per minute
Styles APIN/A2,000 requests per minute
Tilequery APIN/A300 requests per minute
Tilesets APIN/A50 requests per minute
Uploads APIN/A30 requests per minute
Directions API
(driving, walking, and cycling profiles)
25 coordinates per request300 requests per minute
Directions API
(driving-traffic profile)
3 coordinates per request300 requests per minute
Isochrone API1 coordinate per request300 requests per minute
Map Matching API100 coordinates per request300 requests per minute
Matrix API
(driving, walking, and cycling profiles)
25 coordinates per request300 requests per minute
Matrix API
(driving-traffic profile)
10 coordinates per request300 requests per minute
Optimization API12 coordinates per request300 requests per minute
Geocoding APIN/A600 requests per minute
Tokens APIN/A100 requests per minute

HTTPS and CORS

We recommend that all access to Mapbox is over HTTPS. Except for the Maps API, requests initiated over HTTP are automatically upgraded to HTTPS.

Mapbox web services support Cross-Origin Requests with no domain restrictions. To support Internet Explorer 8 and 9, use a library that falls back to XDomainRequest, like corslite.

Coordinate format

When you provide geographic coordinates to a Mapbox API, they should be formatted in the order longitude, latitude and specified as decimal degrees in the WGS84 coordinate system. This pattern matches existing standards, including GeoJSON and KML. Mapbox APIs use GeoJSON formatting wherever possible to represent geospatial data.

The only exception to this longitude, latitude order is the polyline format, which is supported in Static API overlays and Directions API, Map Matching API, and Optimization API responses. When polyline input or output is specified, the polyline content should follow the Google Encoded Polyline format, which specifies latitude, longitude ordering.

Date and time format

Unless otherwise specified, dates and times returned by Mapbox APIs are represented in RFC 3339 format, which can be parsed by many libraries and languages.

The only exception to this rule is the Retrieve TileJSON metadata endpoint of the Maps API, which returns created and modified properties as Unix time.

Pagination

Pagination lets you list many objects from an API by using more than one request. Pagination is supported in the list endpoints for the following APIs:

After receiving a page of objects, you can request the next page of objects using the next link relation in the Link header of the response. This process can be repeated until the server sends a response without a Link header or without a next link relation, which signals the end of the collection.

Link: <https://api.mapbox.com/uploads/v1/1454024795582?start=cijywvxlm004rtikohhqf99jv&limit=100>; rel="next"

In the Mapbox API endpoints that support pagination, the optional limit parameter specifies the maximum number of objects to return. The API will try to return the requested number of objects, but receiving fewer objects does not necessarily signal the end of the collection. Receiving a response with no Link header or no next link relation is the only way to tell that you are at the end of a collection.

Your application must use the Link header for pagination instead of constructing your own URLs, since the specific URLs used for pagination may change at any time. The Python requests library and the link-header-parser module for JavaScript can parse Link headers. Link headers follow the RFC 5988 specifications.

High DPI images

Mapbox supports high DPI image output on all the Maps Service APIs that serve images. Add @2x before the file extension on a URL to request an image at double scale. For instance, a map tile that is 256×256 pixels will be 512×512 pixels with @2x, but will show the same content. When displayed on a page, the image will still be sized to 256×256 pixels, but four pixels of the original will represent one pixel in screen units.

The @2x part of the URL goes before the entire format, so a URL that ends in .png would end with @2x.png as a high DPI image. (Note that tilesets uploaded as MBTiles are not available at this scale.)

SDK and library support

Mapbox provides the following SDKs and libraries to help you access and integrate with our web services APIs:

Support for Mapbox API endpoints varies among these libraries. If a library supports a specific endpoint, the endpoint's Request section in this documentation will contain a link to the relevant method in the library's documentation. Each library’s documentation provides information on installing and using the library.

If you are interested in incorporating Mapbox maps and web services APIs into a Qt application, contact the Mapbox sales team.