Web services for building great apps.


Maps

Static maps

Geocoding

Directions

Web services

Mapbox web services accept GET requests and support both HTTP and HTTPS. If there is an error processing the request, the API will respond with an appropriate HTTP error code. The body of an error response will be text (not JSON) which describes the error.

Access Tokens

Access to Mapbox web services requires an access token, which connects API requests to your account. Supply the access token using the access_token query parameter:

https://api.mapbox.com/v4/{resource}.json?access_token=<your access token here>

There are two types of access tokens:

  • Public access tokens should be used in situations where they can be easily rotated, like scripts on a web page.
  • Secret access tokens should be used in places where it is more difficult to rotate, like mobile apps which require an approval process.

If you are logged in, your default public access token is visible above and will automatically be embedded in example code on mapbox.com. To view your default secret access token, create new tokens, or revoke tokens, visit your account settings.

Versions

The current version of the Mapbox web services is v4. The base URL is:

https://api.mapbox.com/v4

Attributes may be added to returned JSON objects without changing the version number. If any attributes are removed or any breaking changes made to the URL schema the version will be incremented. For documentation for previous versions, see here.

HTTPS

All API endpoints support HTTPS and using it is strongly recommended. Some endpoints require HTTPS and HTTP requests to these endpoints will return a 301 Moved Permanently redirect to the HTTPS version.

URI References in TileJSON response bodies default to HTTP regardless of the protocol used in the request. Include the ?secure querystring in the request to have resources in the response reference HTTPS endpoints.

https://api.mapbox.com/v4/{resource}.json?secure=1

CORS

Mapbox web services support cross-origin requests with no domain restrictions. To make client-side requests to Mapbox web services, use standard XMLHttpRequests with CORS. To support Internet Explorer 8 and 9, use a library that falls back to XDomainRequest, like corslite.

Pagination

Some Mapbox APIs, including uploads, support pagination for listing large quantities of objects. After receiving a page of objects, the next page can requested by taking the id property of the last object on the page and passing it as the start argument of the next request. This process can be repeated until an empty page is received, which signals the end of the collection.

Argument Description
reverse Set to true to reverse the default sort order of the listing.
limit The maximum number of objects to return. This value must be between 1 and 100. The API will attempt to return the requested number of objects, but receiving fewer objects does not necessarily signal the end of the collection. Receiving an empty page of results is the only way to determine when you are at the end of a collection.
start The object id that acts as the cursor for pagination and defines your location in the collection. This argument is exclusive so the object associated with the id provided to the start argument will not be included in the response.