Describing maps

There are a lot of ways to make mistakes configuring a custom map. You could show countries for a map that is meant show streets. You could center a map of Australia on South America instead. You could omit a critical legend or tooltips for a data overlay. TileJSON provides a consistent way of describing a map -- zoom levels, center point, legend contents, and more -- and in turn provides an easy way to load and display a map the way it is meant to be seen.

The smallest TileJSON

What is the least amount of information needed to show a map? TileJSON's answer to this question is the location of its tiles.

{ "tilejson": "2.0.0",
  "tiles": [ "http://a.tiles.mapbox.com/v3/examples.map-4l7djmvo/{z}/{x}/{y}.png" ] }

Other than the tilejson spec version and the tiles url array, all other values in TileJSON are optional and have sensible defaults. By passing this snippet of json into mapbox.js we can load and display the map examples.map-4l7djmvo.

Conventions keep it simple

Web maps can differ wildly and describing all of the differences can be a gnarly task. For a given web map you could ask any of these questions and get very different answers:

• What zoom levels does it support?
• What areas of the world does it cover?
• Where are the most interesting places to show on the map?
• Who should or must be credited for the map?

By making some common sense assumptions TileJSON simplifies the possible answers to these questions. TileJSON allows a map to define minzoom and maxzoom values to describe the zoom levels it supports. If a map claims minzoom:3 and maxzoom:8 it's assumed that zoom levels 4,5,6,7 are also covered. There are lots of different ways to describe interesting locations on a map but TileJSON allows just one: what is the center where it should start?

Here are some of the keys described by the TileJSON spec:

Custom keys

Most JSON-consumers are tolerant of additional keys passed in with objects. TileJSON takes advantage of this fact and allows additional application-specific keys to be added. For example, the website key is added to TileJSON served by the MapBox API to denote the user facing page for a given map.

TileJSON in action

We've seen what the TileJSON format looks like, but how does it get used in the real world?

1. Any map on MapBox has an ID like example.map-4l7djmvo and a corresponding TileJSON endpoint like a.tiles.mapbox.com/v3/examples.map-4l7djmvo.json. This endpoint is documented in our REST API.
2. By calling L.mapbox.map('map', example.map-4l7djmvo) in the MapBox.js API, the TileJSON for the map is downloaded and parsed.
3. The resulting JSON object is used to display the map tiles and set its center point and appropriate zoom range.

By referencing a map's TileJSON through a short string ID (from which an API URL can be constructed) developing applications that manage multiple maps or switch between dozens of tile layers is fun and easy.