Map tiles

ChibiGeo serves individual vector tiles in Mapbox Vector Tile (MVT) format. Use them as a source in a map renderer such as MapLibre. The production API is available at https://app.chibigeo.com with a ChibiGeo production API key. Staging at https://stage.chibigeo.com uses separate accounts and test allowances.

The API provides tile data and TileJSON metadata. It does not provide a ready-made map style, fonts, sprites, raster tiles, or a downloadable PMTiles archive. Your application supplies its own style and renderer.

Endpoints

Endpoint	Response	Counts toward tile allowance?
`GET /v1/tiles/tiles.json`	TileJSON 3.0 with the ChibiGeo tile URL, vector layers, coverage, and attribution	No
`GET /v1/tiles/{z}/{x}/{y}.mvt`	One binary vector tile (`application/x-protobuf`)	Yes, for a successful `200` response

Coordinates use the standard XYZ scheme. The service accepts zoom levels 0–15, with 0 <= x,y < 2^z. A renderer may visually overzoom a level-15 tile, but requesting z=16 from the API returns 400.

Authentication

Send your API key with each TileJSON and tile request. Prefer a header:

X-Api-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY also works. If both headers are present, X-Api-Key takes precedence. A ?key= query parameter is supported for clients that cannot send headers, but it places the key in URLs and is best avoided. When TileJSON is requested with ?key=, its returned tile URL also contains that key.

For a browser map, the key is visible to the browser user. Create a dedicated key and restrict its Allowed origins to your site's exact origin, such as https://example.com. ChibiGeo supports CORS preflight for the API-key headers and checks the key's origin restriction on the actual request. For a server-side client with a stable outbound IP, you can instead restrict Allowed IPs. A key with an origin allowlist cannot be used by a client that sends no Origin header.

Try it

export CHIBIGEO_API_KEY='YOUR_API_KEY'

curl -fS 'https://app.chibigeo.com/v1/tiles/tiles.json' \
  -H "X-Api-Key: $CHIBIGEO_API_KEY"

# Berlin at zoom 12. The response is binary MVT, not JSON.
curl -fS 'https://app.chibigeo.com/v1/tiles/12/2200/1343.mvt' \
  -H "X-Api-Key: $CHIBIGEO_API_KEY" \
  -D tile-headers.txt -o berlin.mvt

The TileJSON tiles template points back to ChibiGeo. Clients using header authentication must send the same header when fetching the individual tiles.

Display a simple map with MapLibre GL JS

Install maplibre-gl and add <div id="map" style="height: 400px"></div> to your page. This small style draws water and roads to demonstrate the vector source; a complete basemap needs additional layers and styling.

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const origin = 'https://app.chibigeo.com';
const apiKey = 'YOUR_API_KEY';

new maplibregl.Map({
  container: 'map',
  center: [13.405, 52.52],
  zoom: 11,
  style: {
    version: 8,
    sources: {
      chibigeo: {
        type: 'vector',
        url: `${origin}/v1/tiles/tiles.json`,
      },
    },
    layers: [
      {id: 'background', type: 'background', paint: {'background-color': '#e8ece9'}},
      {
        id: 'water', type: 'fill', source: 'chibigeo', 'source-layer': 'water',
        paint: {'fill-color': '#9bc7e8'},
      },
      {
        id: 'roads', type: 'line', source: 'chibigeo', 'source-layer': 'roads',
        paint: {'line-color': '#ffffff', 'line-width': 1.5},
      },
    ],
  },
  transformRequest: (url) =>
    url.startsWith(`${origin}/v1/tiles/`)
      ? {url, headers: {'X-Api-Key': apiKey}}
      : {url},
});

The TileJSON metadata lists the available source-layer names, including water, roads, buildings, landuse, landcover, earth, boundaries, places, and pois. Keep the required OpenStreetMap and Protomaps attribution visible in your map.

Allowances, caching, and errors

Tiles have a separate allowance from geocoding. One successfully delivered tile counts as one tile request for the account; TileJSON, missing tiles, and upstream failures do not consume that allowance. Hobby resets daily at 00:00 UTC. Paid plans reset on the subscription's monthly billing anniversary. Current production allowances are:

Plan	Tile allowance	Reset
Hobby	1,000	Daily at 00:00 UTC
Builder	100,000	Monthly billing anniversary
Scale	1,000,000	Monthly billing anniversary
Self-Hoster	100,000	Monthly billing anniversary

These limits are included in the existing subscription; there is no automatic overage charge. The dashboard shows your current usage. Staging has separate, smaller test allowances.

Successful tile responses include X-Tile-Quota-Limit and X-Tile-Quota-Remaining. They permit private HTTP caching for five minutes. TileJSON is not cached. Ordinary short-lived browser caching is supported; the API does not offer offline archive downloads or a mirroring endpoint.

Status	`error`	Meaning
`400`	`invalid_coordinates`	Zoom or XYZ coordinates are outside the supported range.
`401`	`missing_api_key` or `invalid_api_key`	Supply a valid API key for this environment.
`402`	`subscription_past_due`	The account's subscription needs attention.
`403`	`origin_not_allowed` or `ip_not_allowed`	The key's restrictions reject this client.
`404`	`tile_not_found`	No tile exists at these coordinates.
`429`	`rate_limited` or `tile_limit_exceeded`	Slow down, or wait for the next allowance window. Rate limiting includes `Retry-After`.
`502`	`tile_upstream_unavailable`	The tile source could not serve this request.
`503`	`tiles_not_configured`	The tile service is not enabled in this environment.

For an account-level usage view, check the ChibiGeo dashboard. See the geocoding API documentation for address search and reverse geocoding; those endpoints have their own allowance.

Endpoints​

Authentication​

Try it​

Display a simple map with MapLibre GL JS​

Allowances, caching, and errors​

Endpoints

Authentication

Try it

Display a simple map with MapLibre GL JS

Allowances, caching, and errors