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 ready-to-use 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 URLs
• When working with MapLibre GL 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 client should load tiles. It includes the URL template, bounds, zoom range, format, and layer information that map clients like MapLibre, 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 NATIONAL_COUNTIES can be inspected through its TileJSON document before you wire it into a client.

curl "https://api.mappinest.com/tiles/NATIONAL_COUNTIES.json?key=YOUR_KEY"

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

{
  "tilejson": "2.2.0",
  "name": "NATIONAL_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/tiles/NATIONAL_COUNTIES/{z}/{x}/{y}.pbf?key=**YOUR_KEY**"
  ],
  "vector_layers": [
    {
      "id": "NATIONAL_COUNTIES",
      "description": "",
      "fields": {}
    }
  ]
}

What metadata it returns

How clients use TileJSON

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

const tilejson = await fetch(
  'https://api.mappinest.com/tiles/NATIONAL_COUNTIES.json?key=YOUR_KEY'
).then((response) => response.json());

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

When to use TileJSON

Use TileJSON when the 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 client to read the source definition directly.

• Use TileJSON when you want a 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

map.addSource('counties', {
  type: 'vector',
  url: 'https://api.mappinest.com/tiles/NATIONAL_COUNTIES.json?key=YOUR_KEY'
});

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

Many vector-tile 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 NATIONAL_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.

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