Web Services APIs
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, Navigation, Search, 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 does 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}
To access the Mapbox API endpoints, you need a valid access token, which will connect API requests to your account. You must supply a valid access token by using the access_token query parameter in every request.
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.
The example requests in this documentation will include your default access token if you are signed into your Mapbox account and the API request does not require any secret scopes. If the example API request does require a secret scope, the example will specify which scope is required.
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
Mapbox API responses may contain the following rate limit headers:
| Header | Description |
|---|---|
X-Rate-Limit-Interval | The length of the rate-limiting interval, in seconds. This will always be 60. |
X-Rate-Limit-Limit | The 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-Reset | A 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
Each Mapbox API has rate limits that cap the number of requests you can make against an 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.
| API | Default coordinates per request | Default requests per minute |
|---|---|---|
| Vector Tiles API | N/A | 100,000 requests per minute |
| Raster Tiles API | N/A | 100,000 requests per minute |
| Static Images API | N/A | 1,250 requests per minute |
| Static Tiles API | N/A | 6,000 requests per minute |
| Styles API | N/A | 2,000 requests per minute |
| Tilequery API | N/A | 600 requests per minute |
| Uploads API | N/A | 60 requests per minute |
| Mapbox Tiling Service (Read) | N/A | 3,000 requests per minute |
| Mapbox Tiling Service (Write) | N/A | 100 requests per minute |
| Mapbox Tiling Service (Publish) | N/A | 2 requests per minute |
| Datasets API (Read) | N/A | 480 requests per minute |
| Datasets API (Write) | N/A | 40 requests per minute |
| Directions API | 25 coordinates per request | 300 requests per minute |
| Isochrone API | 1 coordinate per request | 300 requests per minute |
| Map Matching API | 100 coordinates per request | 300 requests per minute |
| Matrix API ( driving, walking, and cycling profiles) | 25 coordinates per request | 60 requests per minute |
| Matrix API ( driving-traffic profile) | 10 coordinates per request | 30 requests per minute |
| Optimization API | 12 coordinates per request | 300 requests per minute |
| Geocoding API | N/A | 600 requests per minute |
| Tokens API | N/A | 100 requests per minute |
URL length limits
The maximum URL length that our APIs accept before returning a HTTP 414 URI too long response status code is an 8,192 byte limit imposed by AWS CloudFront, our CDN. See the AWS CloudFront general limits documentation for more details. Note that some APIs accept POST requests with the query parameters in the request body as a workaround for this limitation. The documentation for each endpoint indicates which HTTP request methods it accepts.
HTTPS and CORS
We recommend that all access to Mapbox is over HTTPS. 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 Images 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 Mapbox Tiling Service (MTS), 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 since the cutoff for pagination is dependent on the size of the query response, 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.
Since the number of items returned per page is dependent on the size of the query response, this means that pagination starts after an undefined number of items. This number will change depending on the query response, and since it is not predictable you should not build expecting a specific number of objects per page. Note that styles are generally quite large, so it's likely that a response to the List styles endpoint will start paginating sooner than other list endpoints.
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:
- Mapbox Python CLI
- Mapbox Java SDK
- Mapbox JavaScript SDK
- Mapbox Ruby SDK
- Mapbox Search SDK for iOS (Swift)
- Mapbox Search SDK for Android (Kotlin)
- Mapbox Swift/Objective-C libraries:
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.