# Integrations: Leaflet, OpenLayers, deck.gl, Cesium, QGIS
MapMap's map surface is made of formats other people's software already
reads: Mapbox Vector Tiles, TileJSON 3.0, MapLibre GL style JSON, PMTiles
archives, and SDF glyph ranges. Nothing on it is a MapMap file format. So
the map renders in clients that have never heard of MapMap, and this page is
the copy-pasteable version of that for the five asked about most.
For MapLibre GL JS itself, and for the `@mapmap/maps` wrapper around it, see
[Maps, tiles & Studio](/docs/maps). For MapLibre Native on iOS and Android,
see [Mobile maps](/docs/mobile). This page is everything else.
Set up your shell once; the snippets below use the same two values:
```sh
export BASE=https://api.mapmap.ai # or your self-host gateway
export API_KEY=snk_… # issued by POST /v1/keys; see the quickstart
```
## What MapMap serves, and what each client can read
| Surface | URL | Key | Read by |
|---|---|---|---|
| Vector tiles (MVT) | `$BASE/tiles/{territory}/{z}/{x}/{y}.mvt` | yes | Everything on this page |
| TileJSON 3.0 | `$BASE/tiles/{territory}/tiles.json` | yes | Leaflet (via MapLibre), OpenLayers, deck.gl, QGIS |
| Compiled MapLibre style | `$BASE/tiles/{territory}/style.json` | yes | Leaflet (via MapLibre), OpenLayers (via ol-mapbox-style) |
| House styles, keyless | `$BASE/styles/mapmap-light-76ef8d@2.json` | no | Leaflet, via MapLibre with the `pmtiles` protocol registered |
| PMTiles archive | `https://tiles.mapmap.ai/{territory}.pmtiles` | no | MapLibre, deck.gl, GDAL and QGIS |
| SDF glyphs | `https://fonts.mapmap.ai/{fontstack}/{range}.pbf` | no | MapLibre only |
`.pbf` is accepted as a tile extension wherever `.mvt` is, which matters for
clients whose URL templates assume it (QGIS is one). The key goes on as
`?api_key=snk_…` or as `Authorization: Bearer snk_…`; both are verified to
work on the tile route, and the query form exists because a style document
referenced by bare URL cannot attach a header.
### Four things that decide every snippet below
**1. There are no raster tiles.** MapMap serves vector tiles and expects the
client to render them. Server-side raster or PNG tile rendering is not
offered, and neither is a `{z}/{x}/{y}.png` endpoint. Any client that can
only consume raster tiles (Leaflet's own `L.tileLayer`, Cesium's
`UrlTemplateImageryProvider`) cannot show a MapMap basemap. That is a real
limit, not a configuration you have missed. The one raster surface is
[static map images](/docs/api-reference#static-map-images), which renders a
whole picture rather than a tile pyramid.
**2. The key travels the way you sent it.** `GET
/tiles/{territory}/style.json?api_key=snk_…` returns a style whose source
points at `https://api.mapmap.ai/tiles/uk/tiles.json?api_key=snk_…`, and that
TileJSON in turn lists `…/{z}/{x}/{y}.mvt?v=…&api_key=snk_…`. So a client
that follows the document verbatim stays authenticated all the way down to
the tiles, and the style-based snippets below need no request hook.
Send the key as `Authorization: Bearer snk_…` instead and the URLs come back
keyless, which is right for that client: it is attaching the header itself on
every fetch, and a key it kept out of the URL is not going to be written into
one for it. Pick one form per client rather than mixing them. A hook that
puts the key on is still the answer when the document was fetched some other
way, out of a build step or from a proxy of your own, but it is no longer
load-bearing for the snippets here.
**3. An in-range tile with no data is `204`, not `404`.** Ocean, and the
sparse edges of a territory. Treat an empty body as an empty tile; a client
that logs `204` as a failure will look broken over the sea.
**4. `tiles.mapmap.ai` gates browser origins.** The PMTiles CDN is our own
surface, and a request declaring an `Origin` or `Referer` it does not
recognise is refused:
```json
{
"error": "hosted basemap tiles require an API key from this origin",
"tiles_api": "https://api.mapmap.ai/tiles/:territory/:z/:x/:y.pbf",
"signup": "https://mapmap.ai/signup"
}
```
`localhost` and `127.0.0.1` are allowed, so the keyless snippets here run on
a development server. A request declaring neither header, which is what
QGIS, GDAL, curl and a native app send, is served. A request from your own
deployed site is not: ship the keyed tile API for anything on a domain of
your own. This is the same gate described in
[Mobile maps](/docs/mobile#hosted-house-styles-keyless).
## Leaflet
Leaflet has no vector-tile renderer of its own. The working combination is
[`@maplibre/maplibre-gl-leaflet`](https://github.com/maplibre/maplibre-gl-leaflet),
which puts a MapLibre GL canvas inside a Leaflet layer: Leaflet keeps the
map object, the controls, the markers and the plugin ecosystem, MapLibre
does the drawing. The library is small and the integration is one call.
> **Pin MapLibre 5 for this recipe.** `@maplibre/maplibre-gl-leaflet` is a
> classic script that reads the `maplibregl` **browser global**. MapLibre 6 is
> ESM-only and creates no global, and the plugin has shipped no ESM build, so
> the working combination is still MapLibre 5.x. Pin it explicitly rather than
> floating: `maplibre-gl@5` on a CDN will stop resolving the UMD file the day
> the tag moves.
```html
```
If you are already on MapLibre 6 elsewhere in the app, the plugin still works
provided you put the namespace on the global **before** the plugin script
evaluates, but you then own two MapLibre majors on one page, which is exactly
the `[duplicate-maplibre]` failure. Prefer MapLibre GL JS directly.
Notes that save an hour:
- Leaflet takes `[lat, lon]`; MapLibre and every MapMap API take
`[lon, lat]`. The two coordinate orders sit in the same file here.
- The container needs an explicit height, as it does for plain MapLibre. No
height means a canvas zero pixels tall and a page that looks blank with no
error. See [troubleshooting a blank map](/docs/maps#troubleshooting-a-blank-map).
- Leaflet's own zoom, pan and inertia drive the MapLibre camera, so bearing
and pitch are not available through this layer. If you need a tilted or
rotated map, you want MapLibre GL JS directly.
- `L.tileLayer` cannot be pointed at MapMap. It wants raster tiles and there
are none.
For evaluation without a key, swap the `style` for a house style. It reads
the PMTiles archive over range requests, so register the protocol first:
```html
```
That path is subject to the origin gate above, so it is for local work and
demos rather than for a site you ship.
## OpenLayers
[`ol-mapbox-style`](https://github.com/openlayers/ol-mapbox-style) reads a
MapLibre or Mapbox GL style document and configures OpenLayers layers from
it, which means the MapMap style is the whole integration: colours, zoom
ranges, filters and label placement all come across.
```html
```
Notes:
- **Fonts are the one thing that does not carry over.** MapLibre renders
labels from the SDF glyph ranges at `fonts.mapmap.ai`; OpenLayers draws
text with the browser's own font engine and ignores them. `ol-mapbox-style`
tries to resolve the style's fontstack name (`MapMap Sans Regular`) against
the Fontsource CDN, finds nothing, and falls back to a system font. Pass
`webfonts` as a template string, as above, to choose the fallback
deliberately. It is a template, not a function: passing a function throws
`t.replace is not a function` and the map paints nothing.
- `webfonts` is a string with `{font-family}`, `{fontweight}` and
`{-fontstyle}` placeholders. The example pins one family for every stack,
which is usually what you want when the style names a font you do not
license.
- OpenLayers collapses the attribution into an `i` button by default. The
`collapsible: false` control above keeps the OpenStreetMap and
OpenMapTiles credits on screen, which is a licence condition rather than a
style preference.
- Terrain, hillshade and 3D building extrusions in a MapMap theme have no
OpenLayers equivalent and are dropped. The 2D map is complete.
## deck.gl
deck.gl is the right client when the map is a substrate for your own data
and you want the road network as geometry rather than as a picture.
`MVTLayer` reads our tiles directly.
```html
```
Notes:
- **Either the tile template or the TileJSON URL works**, as long as the key
is on the URL you hand over. `MVTLayer` accepts both, and a TileJSON
fetched with `?api_key=` lists tile templates that carry the key on, so
the tiles it goes on to fetch are authenticated. Handing it a TileJSON URL
with no key on it still ends in `401` on every tile.
- `loadOptions.mvt.layers` is worth setting. A MapMap tile carries up to
sixteen source layers (`aerodrome_label`, `aeroway`, `boundary`,
`building`, `housenumber`, `landcover`, `landuse`, `mountain_peak`, `park`,
`place`, `poi`, `transportation`, `transportation_name`, `water`,
`water_name`, `waterway`); without a filter every one of them is parsed
and styled by the same accessors.
- deck.gl draws no attribution of its own. The credit above is plain HTML
over the canvas, and it is not optional.
- There is no MapMap style to hand deck.gl. You write the accessors. If you
want the MapMap cartography underneath your data, run MapLibre as a base
map and deck.gl as an overlay (`MapboxOverlay` in interleaved mode), which
is the standard deck.gl and MapLibre pairing and needs nothing specific to
MapMap.
### deck.gl over a PMTiles archive
For an unmetered read of a whole territory, point deck.gl at the PMTiles
archive through `@loaders.gl/pmtiles`. Pin it to a 4.x that matches the
loaders.gl your deck.gl release bundles; `@loaders.gl/pmtiles@4.3.4` against
`deck.gl@9.1.14` is the pairing checked here:
```html
```
`MVTLayer` does not accept a PMTiles source object as its `data` (it treats
`data` as a URL and throws `Invalid URL`), which is why this uses `TileLayer`
with an explicit `getTileData`. The `loadOptions.mvt` block is where the
coordinate mode and the tile index go; without `coordinates: "wgs84"` and
`tileIndex` the features come back with null coordinates and nothing draws.
Remember the origin gate: this reads `tiles.mapmap.ai`, so it works from
`localhost` and from a native context, and not from your own domain.
## Cesium
Be plain about this one: **MapMap has no basemap for Cesium.**
- Our tiles are Mapbox Vector Tiles. Cesium's 3D basemap format is 3D Tiles.
They are different formats for different things, and MapMap publishes no
3D Tiles tileset.
- Cesium's imagery providers want raster tiles, and MapMap serves none.
Rendering our vector tiles to raster in a headless browser and feeding
Cesium the result is a thing people do; it is not something MapMap offers,
supports or prices, so nothing here describes how.
What does work is using MapMap as the *data* layer over whatever imagery
your Cesium scene already has. A route with `geometries=geojson`, and an
isochrone's contours, are ordinary GeoJSON, and Cesium draws them without any
adapter:
```html