---
title: "TileJSON | Guides | Maps apis | Maps platform"
description: "What TileJSON is and when to use it."
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs-beta-4y5.pages.dev/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# 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](https://docs-beta-4y5.pages.dev/openlayers/examples/raster-layer/).
-   **MapTiler SDK JS and MapLibre GL JS:** a source with a `url` property takes a TileJSON URL. See [Add a vector tile source](https://docs-beta-4y5.pages.dev/sdk-js/examples/vector-source/).

If your tool supports both TileJSON and [XYZ tiles](https://docs-beta-4y5.pages.dev/cloud/api/maps/#tag/maps/GET/maps/{mapId}/{tileSize/}/{z}/{x}/{y}{scale}.{format}), 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](https://docs-beta-4y5.pages.dev/cloud/api/maps/#tag/maps/GET/maps/{mapId}/{tileSize/}/tiles.json) and [tilesets](https://docs-beta-4y5.pages.dev/cloud/api/tiles/#tag/tiles/GET/tiles/{tilesId}/tiles.json).

## What’s in a TileJSON

This is a shortened TileJSON for a raster map:

```json
{
  "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"
  ]
}
```

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](https://docs-beta-4y5.pages.dev/guides/how-maps-work/coordinate-systems/), MapTiler adds projection and tile matrix fields based on the WMTS standard. See the [MapTiler TileJSON specification](https://github.com/maptiler/tilejson-spec) on GitHub.