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
Mapbox APIs have rate limits that cap the number of requests that can be made 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. The rate limit for each individual API is listed in its documentation.
Header | Description |
---|---|
X-Rate-Limit-Interval | The length of the rate-limiting interval in seconds. |
X-Rate-Limit-Limit | The maximum number of requests you can make in the current interval before reaching the limit. |
X-Rate-Limit-Reset | A Unix timestamp that indicates when the current interval will end and the rate limit counter will reset. |
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:
- Mapbox CLI SDK
- Mapbox Java SDK
- Mapbox JavaScript SDK
- Mapbox Python SDK
- Qt Location Mapbox GL Plugin
- Mapbox Ruby SDK
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.