Skip to content

About Maps

Maps serves the vector basemap behind Woosmap's mapping products. It turns planetiler-built MBTiles into the styles, vector tiles, fonts and sprites a map client needs to render a map, plus satellite and static map images.

The only supported client is maps-js (Woosmap's Map JS SDK), which descends from the Mapbox GL JS lineage. The styles follow the Mapbox GL style spec, but other renderers are not supported.

A client loads a style (/maps/style/streets.json), which points it at a TileJSON (/maps/tiles.json), which lists the tile URL template (/maps/tiles/{tile_set}/{z}/{x}/{y}). The client then fetches vector tiles, glyphs and sprites as it pans and zooms.

sequenceDiagram
    actor Client
    Client->>+Maps: GET /maps/style/streets.json
    Maps-->>-Client: style JSON (sources, sprite, glyphs)
    Client->>+Maps: GET /maps/tiles.json
    Maps-->>-Client: TileJSON (tile URL template)
    loop pan / zoom
        Client->>+Maps: GET /maps/tiles/{tile_set}/{z}/{x}/{y}
        Maps->>+MBTiles: read tile (optional landcover merge)
        MBTiles-->>-Maps: gzipped MVT
        Maps-->>-Client: vector tile
    end
    Client->>Maps: GET /maps/assets/{fontstack}/{range}.pbf (glyphs)
    Client->>Maps: GET /maps/assets/styles/streets-vN/sprites/sprite (sprite)

What it serves

  • Styles (/maps/style/{name}.json): MapLibre style documents, with on-the-fly label localization. See Styles.
  • Vector tiles (/maps/tiles/{tile_set}/{z}/{x}/{y}): gzipped MVT read from MBTiles. The tile_set is an MBTiles filename served from the catalog. See Serving tiles.
  • Satellite tiles (/maps/satellite/{z}/{x}/{y}): raster imagery, gated by the MAP_SATELLITE product.
  • Static maps (/maps/static): a rendered map image for a given viewport.
  • Assets (/maps/assets/...): sprites, glyphs and other style assets.

Key ideas

  • Catalog-driven tiles. MBTILES_CATALOG lists every MBTiles a deploy downloads and serves; any container can serve any entry by name, which makes rolling deploys safe. See Serving tiles and Deploying.
  • Landcover overlay. Splitted OSM-only tilesets are merged with a landcover-* overlay at read time, by filename prefix.
  • Auth and products. Every request is authenticated against a project token; satellite and static maps require their respective products.

REST API

The full endpoint reference is the OpenAPI doc (hidden in prod):