The MapBox API just got a fresh coat of paint and much-improved documentation to make it easier build new applications with fast, custom maps hosted with MapBox. To show it off I wrote a quick demo called Scope that uses the API in combination with Easey and Modest Maps to do a whole new kind of map browser for MapBox’s maps.

We’ve already used the API to build custom sites for NPR, the World Food Programme, and others, providing an established version api.tiles.mapbox.com/v2 that will continue to work as development on the API continues. We’ve also added extensive documentation on how to work with the API.

API Documentation

So what does the API provide? One example is that you can grab a listing of your maps and information about each one as TileJSON, which you can then turn into an interactive map using Wax.

For instance, here’s the Baltimore Retro map described by the API:

{ "id":"mapbox.baltimore-retro",
  "scheme":"xyz",
  "basename":"baltimore-retro.mbtiles",
  "filesize":446557184,
  "name":"Baltimore Retro",
  "type":"baselayer",
  "description":"",
  "version":"1.0.0",
  "formatter":null,
  "bounds":[
    -76.74498303380417, 39.17336668704772,
    -76.49504406900537, 39.39976653736744
  ],
  "minzoom":8,
  "maxzoom":17,
  "center":[
    -76.62001355140478, 39.28656661220758,
    12
  ],
  "legend":null,
  "tiles":[
    "https://a.tiles.mapbox.com/v2/mapbox.baltimore-retro/{z}/{x}/{y}.png",
    "https://b.tiles.mapbox.com/v2/mapbox.baltimore-retro/{z}/{x}/{y}.png",
    "https://c.tiles.mapbox.com/v2/mapbox.baltimore-retro/{z}/{x}/{y}.png",
    "https://d.tiles.mapbox.com/v2/mapbox.baltimore-retro/{z}/{x}/{y}.png"
  ],
  "download":"https://a.tiles.mapbox.com/v2/mapbox.baltimore-retro.mbtiles"
}

It’s super easy to use this with Wax and Modest Maps:

wax.tilejson('http://api.tiles.mapbox.com/v2/mapbox.baltimore-retro.jsonp'
  function(tilejson) {
    var map = new com.modestmaps.Map(
      'map',
      new wax.mm.connector(tilejson));
});

The API speaks JSON, a format that has parsers in nearly every programming environment and is especially friendly with JavaScript. Every API endpoint is also accessible with JSONP, which lets you pull it from MapBox without the need for messy proxies or cross-domain restrictions. For Flash users, we provide a crossdomain.xml file as well, and for those on the cutting edge, the service supports CORS.

MapBox Scope

The API is open source and is only tied to MapBox’s account in one place

  • so everyone is welcome to tinker with changes or use it as their own map browser.

While we’re busy making TileMill and MapBox Hosting amazing, there’s so much more that is still waiting to be built. Hopefully this API brings those ideas closer to reality.