TileJSON Endpoint

Overview

TileJSON is a metadata endpoint that tells map clients how to load your tiles. It includes tile URLs, zoom range, bounds, and layer information - all in a single request.

In Mappinest, TileJSON is exposed from the uploaded tileset Id. That gives you a stable metadata URL for the same tileset you serve through raster or vector tile endpoints. For available map styles such as streets, light, dark, or satellite, use the StyleJSON endpoint instead.

When to use TileJSON

• When you want automatic source configuration - no hardcoded tile XYZ URLs
• When working with MapLibre GL JS or Mapbox GL JS as a vector or raster source
• When you want to inspect vector_layers before choosing a source-layer
• When your tileset may change - the TileJSON URL stays stable even if the tile template is updated

What TileJSON is

TileJSON is a JSON metadata document that describes how a map client should load tiles. It includes the URL template, bounds, zoom range, format, and layer information that map clients like MapLibre GL JS, Mapbox GL JS, OpenLayers, or Leaflet need to configure the source correctly.

How TileJSON is generated

Most tile generation tools embed metadata into MBTiles or PMTiles during export. Mappinest exposes that metadata as a TileJSON endpoint after upload - no extra configuration needed.

Common tools that produce compatible output:

• Tippecanoe - generates MBTiles with embedded metadata
• Planetiler - outputs MBTiles or PMTiles with layer and bounds metadata
• GDAL (3.8+) - exports vector datasets directly to MBTiles or PMTiles
• Tilemaker - builds MBTiles or PMTiles from OpenStreetMap .osm.pbf files

See the Upload Data page for accepted file types and transfer limits.

TileJSON endpoint

The tilesetId is the tileset Identifier used by the raster or vector tile endpoints, typically in the form username.tileset. See Tileset naming on the Upload Data page for the naming rule. For example, a tileset uploaded and published as COUNTIES can be inspected through its TileJSON document before you wire it into a map client.

curl "https://api.mappinest.com/v1/tiles/mappinest.COUNTIES.json?key=YOUR_MAPPINEST_KEY"

The following example shows the TileJSON document a map client would retrieve for the COUNTIES tileset. Exact values depend on the uploaded file, but the structure stays the same.

{
  "tilejson": "2.2.0",
  "name": "COUNTIES",
  "scheme": "xyz",
  "format": "pbf",
  "minzoom": 0,
  "maxzoom": 14,
  "bounds": [-179.15, 17.88, -66.88, 71.39],
  "center": [-98.58, 39.82, 3],
  "tiles": [
    "https://api.mappinest.com/v1/tiles/mappinest.COUNTIES/{z}/{x}/{y}.pbf?key=YOUR_MAPPINEST_KEY"
  ],
  "vector_layers": [
    {
      "id": "COUNTIES",
      "description": "",
      "fields": {}
    }
  ]
}

What metadata it returns

How map clients use TileJSON

Many map clients can consume TileJSON directly through the source url field. The map client reads the metadata first, then uses the returned tile template and zoom constraints when requesting tiles.

const apiKey = 'YOUR_MAPPINEST_KEY';

const response = await fetch(
  `https://api.mappinest.com/v1/tiles/mappinest.COUNTIES.json?key=${apiKey}`
);

if (!response.ok) {
  throw new Error('TileJSON request failed.');
}

const tilejson = await response.json();

console.log(tilejson.tiles);
console.log(tilejson.vector_layers);

When to use TileJSON

Use TileJSON when the map client can consume source metadata from a URL and you do not want to hardcode the tile template, zoom range, or bounds yourself. This is especially useful when you are integrating a tileset produced by a tile-generation workflow and want the map client to read the source definition directly.

• Use TileJSON when you want a map client to discover the tile URL template automatically.
• Use TileJSON when you want to inspect vector_layers before choosing a source-layer in your map style or code.
• Use direct tile URLs when you already know the final tile template and want to define the source manually.

Use TileJSON in a vector source

const apiKey = 'YOUR_MAPPINEST_KEY';

map.addSource('counties', {
  type: 'vector',
  url: `https://api.mappinest.com/v1/tiles/mappinest.COUNTIES.json?key=${apiKey}`
});

map.addLayer({
  id: 'counties-fill',
  type: 'fill',
  source: 'counties',
  'source-layer': 'COUNTIES',
  paint: {
    'fill-color': '#3b82f6',
    'fill-opacity': 0.18
  }
});

Many vector-tile map clients work this way. They read the TileJSON first, then use the returned tile template and metadata to request tiles. For your own tileset, replace COUNTIES and adjust the source-layer if the layer name differs.

Manual source definition without TileJSON

If you do not want to use TileJSON, you can define the source manually with the tile template and any known metadata. This is useful when you want full control or when your integration path expects direct tile URLs.

const apiKey = 'YOUR_MAPPINEST_KEY';

map.addSource('counties', {
  type: 'vector',
  tiles: [
    `https://api.mappinest.com/v1/tiles/mappinest.COUNTIES/{z}/{x}/{y}.pbf?key=${apiKey}`
  ],
  minzoom: 0,
  maxzoom: 14
});

What to read next

• Add vector tileset in MapLibre GL JS>
• Add raster tileset in Mapbox GL JS>
• Add vector tileset in OpenLayers>
• Add raster tileset in Leaflet>