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.

Versions

http://api.tiles.mapbox.com/v1
http://api.tiles.mapbox.com/v2
http://api.tiles.mapbox.com/v3
VersionDescription
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.

SSL

https://api.tiles.mapbox.com/v1/{resource}.json?secure=1
https://api.tiles.mapbox.com/v2/{resource}.json?secure=1
https://api.tiles.mapbox.com/v3/{resource}.json?secure=1

All API endpoint URIs support both http and https schemes. URI References in HTML & 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 JSON or HTML response reference HTTPS endpoints.

CORS & JSONP

Request
http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy.json?callback=jsonloaded

Response
jsonloaded({ "id": examples.map-zr0njcqy, ... });

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.