TileJSON
TileJSON is an open standard for representing tileset metadata. This JSON format defines important information about a tileset, such as its name, description, version, attribution, bounds, center, minzoom and maxzoom levels, and the URL templates used to request individual tiles.
TileJSON is commonly used in web mapping applications to provide clients with the necessary information to access and display tiles from a tileset. For example, a mapping client can know the available zoom levels for a tileset via its TileJSON and will not try to request tiles outside of those levels.
You can retrieve TileJSON metadata for a tileset via an API call to Mapbox Tiling Service (MTS).
TileJSON usage in the Mapbox ecosystem
Developers often do not need to interact directly with TileJSON when building with Mapbox, because Mapbox SDKs automatically fetch and parse it when a tileset URL is provided. Understanding TileJSON can be useful for developers who want to customize map based on provided source data or work with tilesets directly.
When you add a source with a Mapbox tileset ID, the SDK retrieves the corresponding TileJSON metadata behind the scenes to determine how to access and display the tiles. These sources come in different varieties such as vector, raster, or rasterarray and determine how the tiles will be displayed.
For example, adding a vector source in Mapbox GL JS using a tileset ID will automatically fetch the TileJSON for that tileset.
A similar pattern applies when building with other Mapbox SDKs, such as the Mapbox Maps SDKs for Android, iOS, and Flutter:
map.addSource('my-vector-source', {
type: 'vector',
url: 'mapbox://mapbox.mapbox-streets-v8'
});
// The SDK fetches the TileJSON for 'mapbox.mapbox-streets-v8' to get tile URLs and other metadata.
If you are self-hosting tiles you can provide a URL to a TileJSON resource when adding a source. This allows the SDK to retrieve the necessary metadata for the tileset:
// retrieving TileJSON from a custom URL
map.addSource('my-vector-source', {
type: 'vector',
url: 'https://example.com/path/to/tileset.json'
});
If you are using a tileset that does not have a TileJSON available, you can specify the required properties found in TileJSON directly when adding the source. In the example below, url is not provided, but the tiles, minzoom, maxzoom, and attribution properties are specified directly:
map.addSource('my-vector-source', {
type: 'vector',
tiles: [ 'https://example.com/{z}/{x}/{y}.vector.pbf'],
minzoom: 0,
maxzoom: 14,
attribution: '© Mapbox © OpenStreetMap'
});
Any custom tilesets you create with Mapbox Tiling Service or via Mapbox Studio will also have associated TileJSON metadata that can be accessed via the MTS API.
Sample TileJSON
The following example shows a TileJSON response for the mapbox.mapbox-terrain-v2 tileset. This TileJSON is available at https://api.mapbox.com/v4/mapbox.mapbox-terrain-v2.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN.
{
"attribution": "<a href=\"https://www.mapbox.com/about/maps\" target=\"_blank\" title=\"Mapbox\" aria-label=\"Mapbox\">© Mapbox</a> <a href=\"https://www.openstreetmap.org/copyright/\" target=\"_blank\" title=\"OpenStreetMap\" aria-label=\"OpenStreetMap\">© OpenStreetMap</a> <a class=\"mapbox-improve-map\" href=\"https://www.mapbox.com/contribute/\" target=\"_blank\" title=\"Improve this map\" aria-label=\"Improve this map\">Improve this map</a>",
"bounds": [
-180,
-85,
180,
85
],
"cacheControl": "max-age=43200,s-maxage=7200",
"center": [
0,
0,
3
],
"created": 1396562400000,
"filesize": 0,
"fillzoom": 9,
"format": "pbf",
"id": "mapbox.mapbox-terrain-v2",
"mapbox_logo": true,
"maskLevel": 9,
"maxzoom": 15,
"minzoom": 0,
"modified": 1594153892000,
"name": "Mapbox Terrain v2",
"private": false,
"scheme": "xyz",
"tilejson": "3.0.0",
"tiles": [
"https://a.tiles.mapbox.com/v4/mapbox.mapbox-terrain-v2/{z}/{x}/{y}.vector.pbf?access_token=pk.eyJ1IjoiZXhhbXBsZXMiLCJhIjoiY203eXd1a3ZzMGV1ejJrcHRvdnVoYng0NCJ9.NzlqpAcLHejzezQqazzI-w",
"https://b.tiles.mapbox.com/v4/mapbox.mapbox-terrain-v2/{z}/{x}/{y}.vector.pbf?access_token=pk.eyJ1IjoiZXhhbXBsZXMiLCJhIjoiY203eXd1a3ZzMGV1ejJrcHRvdnVoYng0NCJ9.NzlqpAcLHejzezQqazzI-w"
],
"vector_layers": [
{
"description": "Generalized landcover classification",
"fields": {
"class": "One of: wood, scrub, grass, crop, snow"
},
"id": "landcover",
"maxzoom": 22,
"minzoom": 0,
"source": "mapbox.mapbox-terrain-v2",
"source_name": "Mapbox Terrain v2"
},
{
"description": "",
"fields": {
"class": "One of: shadow, highlight",
"level": "Brightness %. One of: 94, 90, 89, 78, 67, 56"
},
"id": "hillshade",
"maxzoom": 22,
"minzoom": 0,
"source": "mapbox.mapbox-terrain-v2",
"source_name": "Mapbox Terrain v2"
},
{
"description": "Elevation contour polygons",
"fields": {
"ele": "Integer. The elevation of the contour in meters",
"index": "Indicator for every 2nd, 5th, or 10th contour. Coastlines are given -1. One of: 2, 5, 10, -1, null"
},
"id": "contour",
"maxzoom": 22,
"minzoom": 0,
"source": "mapbox.mapbox-terrain-v2",
"source_name": "Mapbox Terrain v2"
}
],
"webpage": "https://studio.mapbox.com/tilesets/mapbox.mapbox-terrain-v2"
}
Related resources: