> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/api/llms.txt) # 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. [Maps service](https://docs.mapbox.com/api/api/maps/) [Navigation service](https://docs.mapbox.com/api/api/navigation/) [Search service](https://docs.mapbox.com/api/api/search/) [Accounts service](https://docs.mapbox.com/api/api/accounts/) The Mapbox APIs described in this documentation are subject to Mapbox's [Terms of Service](https://www.mapbox.com/tos/). Mapbox provides MCP servers and Agent Skills to help AI assistants work with Mapbox APIs through the [**Model Context Protocol**](https://modelcontextprotocol.io/introduction), an open standard for AI tools to connect with external services: - **Mapbox MCP Server** - Exposes Mapbox web services APIs for geocoding, routing, search, and map generation. See the [MCP Server documentation](https://docs.mapbox.com/api/guides/mcp-server/) for more information. - **Mapbox DevKit MCP Server** - Provides AI assistants with direct access to Mapbox developer APIs for style management, token creation, and feedback access. See the [DevKit MCP Server documentation](https://docs.mapbox.com/api/guides/devkit-mcp-server/) for more information. - **Mapbox Docs MCP Server** - Gives AI assistants direct access to Mapbox documentation through full-text search and page retrieval. No access token required. See the [Docs MCP Server documentation](https://docs.mapbox.com/api/guides/docs-mcp-server/) for more information. - **Mapbox Agent Skills** - Pre-built knowledge modules that teach AI assistants best practices, integration patterns, and development workflows for building Mapbox applications. See the [Agent Skills documentation](https://docs.mapbox.com/api/guides/mapbox-agent-skills/) for more information. ## 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](https://en.wikipedia.org/wiki/Query_string). - **A token scope.** If an API endpoint requires a [token scope](#access-tokens-and-token-scopes) that the default access token does not have, this scope will be listed. - **Code examples.** Each endpoint has example requests in [cURL](http://curl.haxx.se/) format. Mapbox also provides [several SDKs and libraries](#sdk-and-library-support) 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 ```http https://api.mapbox.com/{endpoint}?access_token={your_access_token} ``` To access the Mapbox API endpoints, you need a valid [access token](https://docs.mapbox.com/help/glossary/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 the right side of your [Developer Console homepage](https://console.mapbox.com/). You can also create and manage additional tokens on your [Access tokens page](https://console.mapbox.com/account/access-tokens/) or with the [Tokens API](https://docs.mapbox.com/api/accounts/tokens/). When you create a new access token, you can give it one or more [token scopes](https://docs.mapbox.com/help/glossary/access-token/#public-vssecret-tokens). 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](#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](https://www.mapbox.com/contact/sales/). The following table lists the default rate limit for each API. Note that all rate limits are counted per [access token](#access-tokens-and-token-scopes), not per account.
APIDefault coordinates per requestDefault requests per minute
Vector Tiles APIN/A100,000 requests per minute
Raster Tiles APIN/A100,000 requests per minute
Static Images APIN/A1,250 requests per minute
Static Tiles APIN/A6,000 requests per minute
Styles API
(Read)		N/A2,000 requests per minute
Styles API
(Write)		N/A50 requests per minute
Tilequery APIN/A600 requests per minute
Uploads APIN/A60 requests per minute
Mapbox Tiling Service (Read)N/A3,000 requests per minute
Mapbox Tiling Service (Write)N/A100 requests per minute
Mapbox Tiling Service (Publish)N/A2 requests per minute
Datasets API
(Read)		N/A480 requests per minute
Datasets API
(Write)		N/A40 requests per minute
Directions API25 coordinates per request300 requests per minute
Isochrone API1 coordinates per request300 requests per minute
Map Matching API100 coordinates per request300 requests per minute
Matrix API
(driving, walking, and cycling profiles)		25 coordinates per request60 requests per minute
Matrix API
(driving-traffic profile)		10 coordinates per request30 requests per minute
Optimization API12 coordinates per request300 requests per minute
Geocoding APIN/A1000 requests per minute
Geocoding v5 APIN/A600 requests per minute
Tokens APIN/A100 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](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html#limits-general) 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) with no domain restrictions. To support Internet Explorer 8 and 9, use a library that falls back to `XDomainRequest`, like [corslite](https://github.com/mapbox/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](https://en.wikipedia.org/wiki/World_Geodetic_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](https://docs.mapbox.com/api/maps/static-images/) and [Directions API](https://docs.mapbox.com/api/navigation/directions/), [Map Matching API](https://docs.mapbox.com/api/navigation/map-matching/), and [Optimization API](https://docs.mapbox.com/api/navigation/optimization/) 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](https://tools.ietf.org/html/rfc3339) format, which can be parsed by many libraries and languages. The only exception to this rule is the [Retrieve TileJSON metadata](https://docs.mapbox.com/api/maps/mapbox-tiling-service#retrieve-tilejson-metadata) endpoint of Mapbox Tiling Service (MTS), which returns `created` and `modified` properties as [Unix time](https://en.wikipedia.org/wiki/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: - [Datasets API](https://docs.mapbox.com/api/maps/datasets/#list-datasets) - [Styles API](https://docs.mapbox.com/api/maps/styles/#list-styles) - [Mapbox Tiling Service](https://docs.mapbox.com/api/maps/mapbox-tiling-service/#list-tilesets) - [Tokens API](https://docs.mapbox.com/api/accounts/tokens/#list-tokens) - [Uploads API](https://docs.mapbox.com/api/maps/uploads/#retrieve-recent-upload-statuses) After receiving a page of objects, you can request the next page of objects using the `next` link relation in the [`Link` header](http://tools.ietf.org/html/rfc5988) 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: ; 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](https://docs.mapbox.com/api/maps/styles/#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](https://requests.readthedocs.io/en/master/user/advanced/#link-headers) and the [link-header-parser](https://github.com/thlorenz/parse-link-header) module for JavaScript can parse `Link` headers. `Link` headers follow the [RFC 5988 specifications](http://tools.ietf.org/html/rfc5988). ## 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](https://docs.mapbox.com/help/glossary/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](https://www.github.com/mapbox/mapbox-cli-py) - [Mapbox Java SDK](https://www.github.com/mapbox/mapbox-java) - [Mapbox JavaScript SDK](https://www.github.com/mapbox/mapbox-sdk-js) - [Mapbox Ruby SDK](https://github.com/mapbox/mapbox-sdk-rb) - [Mapbox Search SDK for iOS (Swift)](https://github.com/mapbox/mapbox-search-ios) - [Mapbox Search SDK for Android (Kotlin)](https://github.com/mapbox/mapbox-search-android) - Mapbox Swift/Objective-C libraries: - [Mapbox Directions for Swift](https://github.com/mapbox/mapbox-directions-swift/) - [MapboxStatic.swift](https://github.com/mapbox/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.