Documentation / Authenticated raster and vector tile API

Authenticated raster and vector tile API

Display CARTO raster tiles, render any Mapsource preset or saved style as PNG tiles, or style OpenMapTiles vector data in the client.

On this page

Retrieve a raster, custom styled raster, or vector basemap tile

Read /tiles/catalog for tile templates, zoom ranges, snapshot dates, and attribution. Send a Bearer header with each tile request. Styled raster tiles render vector presets or a saved profile into 256 × 256 PNGs. Add ?revision=N to pin a saved profile revision. Vector tiles contain features for client-side styling and inspection.

curl --fail-with-body https://api.mapsource.io/tiles/catalog

curl --fail-with-body https://api.mapsource.io/tiles/dark/0/0/0.png \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" --output dark.png

curl --fail-with-body https://api.mapsource.io/tiles/light/0/0/0.png \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" --output light.png

curl --fail-with-body https://api.mapsource.io/tiles/styles/mapsource/12/652/1465.png -H "Authorization: Bearer $MAPSOURCE_API_KEY" --output mapsource.png

curl --fail-with-body https://api.mapsource.io/tiles/vector/14/2620/6332.pbf \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" --output tile.pbf

Tile coordinates, styles, and formats

Parameter	Accepted values
`style`	dark (CARTO Dark Matter) or light (CARTO Positron)
`z`	Integer zoom 0–20 for raster; 0–14 for vector
`x`, `y`	Integers from 0 to 2^z − 1; XYZ, not TMS
Raster format	256 × 256 PNG, EPSG:3857 / Web Mercator tile grid
Vector format	Mapbox Vector Tile (protobuf) in the OpenMapTiles schema, same tile grid
Vector path	`/tiles/vector/{z}/{x}/{y}.pbf`

The tile catalog provides templates, source snapshots, and zoom ranges. Tile and Overpass datasets have independent update schedules. Empty vector tiles return HTTP 204; non-empty vector responses contain uncompressed protobuf data.

Style switching, overlays, and caching

After the map source has loaded, replace its tile template to change style without resetting the camera. This uses the mapsource source from the quickstart MapLibre example.

// Call after map load; nextStyle must be "dark" or "light".
function setBasemap(nextStyle) {
  if (!["dark", "light"].includes(nextStyle)) return;
  const source = map.getSource("mapsource");
  source.setTiles([
    "https://api.mapsource.io/tiles/" + nextStyle + "/{z}/{x}/{y}.png"
  ]);
}

Vector source layers include water, landcover, building, transportation, and boundary. Style and inspect these features in the client. Raster PNGs contain rendered pixels. To display selectable Overpass results on either basemap, convert the response to GeoJSON and add overlay layers. See the map example.

Successful tile responses use private caching with a one-day max age and a stale-if-error window. A browser cache hit need not fetch another paid tile. Do not turn private authenticated responses into a public cache or relay without your own access controls.

For HTTP 401 responses, verify that each tile request includes a valid Bearer header. Configure authentication with MapLibre transformRequest.

Access and limits

Raster tiles are 256 × 256 PNGs with a maximum zoom of 20. Styled raster tiles render vector presets and saved profiles on demand and have a higher quota weight than pre-rendered tiles. Vector tiles use the OpenMapTiles schema. Read nativeMaxZoom and per-layer zoom ranges from the catalog; requests above the supported range return HTTP 400. Client-side overzooming does not add source detail.

Tile responses include x-mapsource-tileset and x-mapsource-native-max-zoom. Valid coordinates without data return HTTP 204 with an empty body. Tile snapshot dates are independent of the Overpass dataset timestamp.

Each fetched tile consumes subscription quota. Use a header-capable client or an authenticated server-side proxy. Keep API keys out of public tile URLs and respect private-cache headers.

See plan limits for request allowances and error handling for quota and retry behavior.

Responses and examples

Raster responses contain PNG images. Vector responses contain uncompressed Mapbox Vector Tile protobuf data. Vector features can be styled and inspected in the client. For selectable features over a raster basemap, request Overpass geometry and add a separate overlay.

Example responses and timing measurements · Current service status

Attribution

Display © OpenStreetMap contributors and CARTO attribution with the map. The API catalog carries the current attribution text and snapshot information.

Source and reference · Mapsource attribution guide

Questions about this guide? Contact support.