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, 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 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.

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.

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.

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.

Every Mapbox API response contains the following rate limit headers:

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

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.

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. Please 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.

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.

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.

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 Tilesets API, which returns created and modified properties as Unix time.

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:

• Datasets API
• Styles API
• Tilesets API
• Tokens API
• Uploads API

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.

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.)

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
• Mapbox Ruby SDK

• Mapbox Swift/Objective-C libraries:

  • MapboxGeocoder.swift
  • MapboxDirections.swift
  • MapboxStatic.swift

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.