TileJSON

TileJSON is a small JSON file that describes a tileset. It holds the tile URL template, the zoom range, the map bounds, and the required attribution. A map library reads it and sets up the layer from a single URL, so you don’t have to configure each value by hand.

MapTiler provides a TileJSON for every map and every tileset, both raster and vector.

When to use TileJSON

Use the TileJSON URL when your library or tool asks for it. For example:

• OpenLayers: the ol.source.TileJSON source loads a map from its TileJSON URL. See the OpenLayers raster example.
• MapTiler SDK JS and MapLibre GL JS: a source with a url property takes a TileJSON URL. See Add a vector tile source.

If your tool supports both TileJSON and XYZ tiles, we recommend TileJSON. The library learns the tileset’s bounds and zoom range from the TileJSON format, so it only requests tiles that exist. This matters most for tilesets that cover a specific area: with a plain XYZ URL, the library also requests tiles for the empty area around it.

To get the URL for your map, open the sharing dialog and select the TileJSON tab under Use map in other ways. For the full list of TileJSON endpoints and parameters, see the API reference for maps and tilesets.

What’s in a TileJSON

This is a shortened TileJSON for a raster map:

{
  "tilejson": "2.2.0",
  "name": "Streets",
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
  "minzoom": 0,
  "maxzoom": 22,
  "bounds": [-180, -85.0511, 180, 85.0511],
  "center": [0, 0, 0],
  "format": "png",
  "tiles": [
    "https://api.maptiler.com/maps/streets-v4/{z}/{x}/{y}.png?key=YOUR_MAPTILER_API_KEY_HERE"
  ]
}

The tiles array holds the XYZ URL template that the library uses to request each tile.

Maps in other projections

Standard TileJSON only supports the Web Mercator projection (EPSG:3857). For maps in other coordinate systems, MapTiler adds projection and tile matrix fields based on the WMTS standard. See the MapTiler TileJSON specification on GitHub.