tilegroxy docs
GitHub Issues Get tilegroxy
Edit this page Report an issue

Vector Basemap

Serves Overture Maps themes as separate layers and combines them into a single basemap layer, without any tile preparation.

MVT
Overture Maps publishes its data as PMTiles archives on S3, one per theme. The archives are dated releases. Check the Overture documentation for the current one and update the date in each URL.

Configuration

  • YAML

  • JSON

server:
  production: false
  cors:
    enabled: true
    wildcardorigin: true (1)
  tilejson: (2)
    enabled: true
client:
  maxlength: 52428800 (3)
cache:
  name: memory
  maxsize: 10000
  ttl: 86400
layers:
  - id: overture_base
    provider:
      name: pmtiles
      url: https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles/2026-10-21.0/base.pmtiles (4)
  - id: overture_transportation
    provider:
      name: pmtiles
      url: https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles/2026-10-21.0/transportation.pmtiles
  - id: overture_buildings
    provider:
      name: pmtiles
      url: https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles/2026-10-21.0/buildings.pmtiles
  - id: overture_basemap
    provider:
      name: compositemvt (5)
      providers:
        - name: fallback (6)
          primary:
            name: ref (7)
            layer: overture_base
          secondary:
            name: static
            image: embedded:empty.mvt (8)
        - name: fallback
          primary:
            name: ref
            layer: overture_transportation
          secondary:
            name: static
            image: embedded:empty.mvt
        - name: fallback
          primary:
            name: ref
            layer: overture_buildings
          secondary:
            name: static
            image: embedded:empty.mvt
1 Any website can use these tiles, which suits public data. See CORS to restrict it.
2 Serves a TileJSON document for each layer, such as /tiles/overture_basemap.json. MapLibre can be pointed straight at it. See TileJSON.
3 Dense tiles, such as buildings in a city center, decompress to more than the 10 MiB default. This raises the limit to 50 MiB. Don’t raise it further than you need, as it bounds how much memory a single tile can take.
4 Zoom range, bounds, and vector_layers come from the archive’s header and metadata, so the layer doesn’t need to declare them. See PMTiles.
5 Merges the layers inside each child’s tile into one tile without changing them. See Composite MVT.
6 A theme with no tile at a location returns an error. Without the fallback, one empty theme would fail the whole composite tile.
7 Reuses the theme layers defined above rather than repeating their URLs. Each theme is cached individually as well as the combined tile.
8 A built-in, valid vector tile with no layers in it. 
{
  "server": {
    "production": false,
    "cors": {
      "enabled": true,
      "wildcardorigin": true (1)
    },
    "tilejson": { (2)
      "enabled": true
    }
  },
  "client": {
    "maxlength": 52428800 (3)
  },
  "cache": {
    "name": "memory",
    "maxsize": 10000,
    "ttl": 86400
  },
  "layers": [
    {
      "id": "overture_base",
      "provider": {
        "name": "pmtiles",
        "url": "https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles/2026-10-21.0/base.pmtiles" (4)
      }
    },
    {
      "id": "overture_transportation",
      "provider": {
        "name": "pmtiles",
        "url": "https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles/2026-10-21.0/transportation.pmtiles"
      }
    },
    {
      "id": "overture_buildings",
      "provider": {
        "name": "pmtiles",
        "url": "https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles/2026-10-21.0/buildings.pmtiles"
      }
    },
    {
      "id": "overture_basemap",
      "provider": {
        "name": "compositemvt", (5)
        "providers": [
          {
            "name": "fallback", (6)
            "primary": {
              "name": "ref", (7)
              "layer": "overture_base"
            },
            "secondary": {
              "name": "static",
              "image": "embedded:empty.mvt" (8)
            }
          },
          {
            "name": "fallback",
            "primary": {
              "name": "ref",
              "layer": "overture_transportation"
            },
            "secondary": {
              "name": "static",
              "image": "embedded:empty.mvt"
            }
          },
          {
            "name": "fallback",
            "primary": {
              "name": "ref",
              "layer": "overture_buildings"
            },
            "secondary": {
              "name": "static",
              "image": "embedded:empty.mvt"
            }
          }
        ]
      }
    }
  ]
}
1 Any website can use these tiles, which suits public data. See CORS to restrict it.
2 Serves a TileJSON document for each layer, such as /tiles/overture_basemap.json. MapLibre can be pointed straight at it. See TileJSON.
3 Dense tiles, such as buildings in a city center, decompress to more than the 10 MiB default. This raises the limit to 50 MiB. Don’t raise it further than you need, as it bounds how much memory a single tile can take.
4 Zoom range, bounds, and vector_layers come from the archive’s header and metadata, so the layer doesn’t need to declare them. See PMTiles.
5 Merges the layers inside each child’s tile into one tile without changing them. See Composite MVT.
6 A theme with no tile at a location returns an error. Without the fallback, one empty theme would fail the whole composite tile.
7 Reuses the theme layers defined above rather than repeating their URLs. Each theme is cached individually as well as the combined tile.
8 A built-in, valid vector tile with no layers in it.

Try it

tilegroxy serve -c vector-basemap.yml

Open http://127.0.0.1:8080/preview/overture_basemap for the layer preview, or point MapLibre at http://127.0.0.1:8080/tiles/overture_basemap.json. The preview is only available while server.production is false.

To add more themes, such as places or divisions, add another pmtiles layer and another fallback entry under the composite.

Edit this page Report an issue