TileJSON for map tiles

You are going to learn about the TileJSON format and its benefits. This article will give you an overview of the most common use cases for TileJSON, show you the general description and specifications, and point you to various examples of its implementations in the MapTIler product ecosystem.

Using TileJSON for map tiles

What is a JSON?

JSON stands for JavaScript Object Notation, it is an open standard file format and interchange format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and arrays. JSON is a language-independent format that was originally derived from JavaScript, however, many modern programming languages use code to generate JSON-format-data. The extension is *.json.

What is a TileJSON?

TileJSON is a lightweight JSON description of all parameters associated with a tileset (web map). It is a shorter alternative to the WMTS GetCapabilities document. It is very easy to use in JavaScript, which is one of the reasons why it is so popular. It was developed by a US company called MapBox. It was not standardized by any institution like OGC but it is often used in web apps.

It stores information such as where to request the tileset, the name of the tileset, the attribution necessary for using the tileset. It is also universally regarded as an open standard for representing map metadata. The description of the latest version is available on GitHub. MapTiler strongly recommends using the TileJSON format instead of the XYZ URL format.

How does MapTiler support the TileJSON in the Products?

TileJSON is widely implemented in the MapTiler product ecosystem. MapTIler Cloud and MapTiler Server have available endpoints for TileJSON for raster and vector tilesets. TileJSONs are used as main source tilesets for StyleJSONs and styling maps. Check out the documentation for TileJSON here.

{
  "tilejson":"2.0.0",
  "name":"Basic",
  "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],
  "format":"png",
  "type":"baselayer",
  "center":[0, 0, 0],
  "tiles":[
    "https://api.maptiler.com/maps/basic/{z}/{x}/{y}.png?key=<your_key>"
  ]
}

Coordinate systems and TileJSON

TileJSON itself is designed only to use tiles in WebMercator projection EPSG:3857. However, standard WMTS allows using tiles in other projections. The MapTIler team filled this hole in the TileJSON and created specifications for the usage of different “SRS”. It requires adding the projection “CRS” or “proj4” field and the “tile_matrix”. These new keys follow the WMTS standard. MapTIler Cloud supports this TileJSON specification for all projections. For more information, see the full documentation on GitHub.

What is a MetadataJSON?

MetadataJSON is a metadata dataset description very similar to TileJSON, only without the mandatory address for the tiles. This file format is created every time when MapTiler Engine renders a folder structure for your maps. You can check further info about MetadataJSON in the documentation.

{
  "name": "555",
  "version": "1.1.0",
  "description": "",
  "attribution": "Rendered with <a href=\"https://www.maptiler.com/engine/\">MapTiler Engine</a>",
  "type": "overlay",
  "format": "png",
  "minzoom": "2",
  "maxzoom": "10",
  "scale": "1.000000",
  "bounds": [12.01552497, 48.49748783, 18.94418131, 51.10266672],
  "profile": "mercator"
}

Conclusion

The TileJSON is a widely used format for storing and transmitting attributes of online (tiled) maps. Due to its broad acceptance and support, it offers probably the best usability and functionality available today….

Useful links

GitHub - TileJSON specification
GitHub - MapTiler TileJSON specification
ViaEuropa - TileJSON specification
Mapbox - TileJSON metadata
Tiled Web Map
Tilejson.io
OpenLayers - TileJSON
MapTiler API - TileJSON Documentation
Wikipedia - JSON