TileJSON Endpoint

What TileJSON is

TileJSON is a JSON metadata document for a tileset. It describes how a client should access the tiles, including the URL template, bounds, zoom range, format, and other metadata needed to configure the source correctly.

In Mappinest, TileJSON is exposed from the uploaded dataset id. That gives you a stable metadata URL for the same dataset you serve through raster or vector tile endpoints.

Use TileJSON for uploaded datasets and tilesets. For ready-to-use map styles such as streets, light, dark, or satellite, use the StyleJSON endpoint from the Map Styles API instead.

How TileJSON fits into tile-generation workflows

Tile-generation tools typically embed metadata alongside the tile data itself. When your dataset is uploaded to Mappinest, this metadata is exposed through a TileJSON document, allowing map clients to automatically discover the tile URL template, zoom range, bounds, and available vector layers from a single URL.

• Tippecanoe usually generates MBTiles archives with embedded metadata that can be exposed as TileJSON after upload.
• Planetiler is commonly used to generate MBTiles or PMTiles, and those outputs usually contain enough metadata for a useful TileJSON document.
• GDAL (3.8+) can export vector datasets directly to MBTiles or PMTiles archives.

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

TileJSON endpoint

The datasetId is the same identifier used by the raster and vector tile endpoints, typically in the form username.dataset. See Dataset naming on the Upload Data page for the naming rule. For example, a dataset 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"

What metadata it returns

How clients use TileJSON

Many vector-tile 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 dataset 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 dataset, 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
});

Sample TileJSON

The following example shows the kind of TileJSON document a client would retrieve for the NATIONAL_COUNTIES dataset. Exact values depend on the uploaded file, but the overall 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": {}
    }
  ]
}