You are viewing documentation for an older version of the Mapbox API. Check out v4 for the latest.

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.

v1TileJSON 1.0. Uses TMS tile scheme
v2TileJSON 1.0. Uses XYZ tile scheme
v3TileJSON 2.0 (uses template key, drops formatter

Requests should be made with one of the versioned API URLs as the base URL of the request. 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.


All API endpoint URIs support both http and https schemes. 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.



jsonloaded({ "id":, ... });

Mapbox web services return read-only CORS headers with no domain restrictions. Using standard JSON with CORS and a polyfill library like corslite for IE support is the recommended way to make client-side requests to Mapbox web services.

For applications that cannot utilize CORS, JSONP requests are supported by making requests to any json resource with a ?callback querystring. To support legacy implementations requests for UTFGrids default to having a wrapping grid() jsonp function even when no ?callback query parameter is provided. This behavior will be deprecated in the next major API version.