How To Use

The Protomaps hosted tile API serves MVT vector tiles that conform to Basemap Layers. The three ways to access it are with Style JSON, TileJSON and ZXY URLs.

The hosted API does not serve PMTiles directly, but instead TileJSON and ZXY URLs that you could set up yourself using a CDN integration. To read PMTiles directly in the browser, see the open source documentation.

The hosted API requires an API key. Each key is subject to CORS restrictions set by you. See the usage policy for commercial use.

Styles

Provide a Style JSON to MapLibre GL JS with a chosen theme and label langauge:

import { Map as MaplibreMap } from "maplibre-gl";
...
map = new MaplibreMap({
  container: "map",
  zoom: 0,
  center: [0, 0],
  style: "https://api.protomaps.com/styles/v4/light/en.json?key=MY_KEY"
});

TileJSON

If you’re using a custom Style JSON outside of the five defaults, provide a TileJSON in the url of the source:

"sources": {
  "protomaps": {
    "type": "vector",
    "url": "https://api.protomaps.com/styles/v4.json?key=MY_KEY"
  }
}

Tiles (ZXY)

You can also access the API via the raw ZXY protocol URL.

"sources": {
  "protomaps": {
    "type": "vector",
    "maxzoom": 15,
    "tiles": [
      "https://api.protomaps.com/tiles/v4/{z}/{x}/{y}.mvt?key=MY_KEY",
    ],
    "attribution": "<a href=\"https://osm.org/copyright\">© OpenStreetMap</a>",
  },
},

Note that in the above you need to provide maxzoom and attribution. The Basemap API supports zoom level 15.

If using protomaps-leaflet for rendering vector tiles,

const map = L.map('map')
const URL = "https://api.protomaps.com/tiles/v3/{z}/{x}/{y}.mvt";
const layer = protomapsL.leafletLayer({url:URL + '?key=MY_KEY',theme:'light'})
layer.addTo(map)

Sprites and Glyphs

Sprites and Glyphs for MapLibre are not served through the API, but hosted on GitHub in basemaps-assets.

Escape Hatch

The contents are the same as the daily builds - anything you get through the API can be reproduced by setting up your own CDN-accelerated distribution using one of the Basemaps daily builds. You’re not locked into the hosted API, by design!

The hosted basemap is updated at an irregular, less-than-weekly frequency to improve the cache hit rate.

Usage Policy

The Protomaps Tile API is free for non-commercial use. For commercial use, become a GitHub Sponsor.

See the FAQ for why the API requires a key, and what happens if you go over the limit.

API Keys

Sign up for an account to issue API keys. On the account page, you can view your usage across all keys for the last 90 days. Viewing a single key displays a chart of usage for that key.

CORS

Requests made from a web browser are subject to Cross-Origin Resource Sharing (CORS) limitations. The list of allowed sites can be set per API key at the Account portal.
Requests Must include an Origin header, unless the CORS setting includes *.
Requests made from localhost with a valid API key are not subject to CORS restrictions; this is useful for local development. For domain names used in development and staging environments, set them to allowed on the Account portal, e.g. http://localhost:8080.

Hosted API