Sources¶

Source configuration files define geodata providers. Place them in a directory of your choice and reference them via includes in your layer config files, or pass them via --sources.

Source types¶

Source type (type) determines the fetch method — how data is downloaded or accessed. This is separate from the data format (set on layer definitions via format).

Source type is detected automatically from URLs but can be set explicitly with the type field.

WMTS¶

Downloads map tiles from a Web Map Tile Service. URL templates contain per-tile variables (${x}, ${y}, ${z}) that are resolved at download time.

sources:
  my_wmts:
    type: wmts
    defaults:
      layer: default_layer_name
      extension: jpeg
    urls:
      - "https://wmts.example.com/${layer}/default/current/3857/${z}/${x}/${y}.${extension:-jpeg}"
      - "https://wmts1.example.com/${layer}/default/current/3857/${z}/${x}/${y}.${extension:-jpeg}"
    attribution: "© Example"
    rate_limit_ms: 150
    max_threads: 4

Multiple URLs are used as fallback/rotation endpoints (load balancing). All URLs must use the same template.

WMTS Capabilities mode¶

Instead of manually constructing URL templates, you can use a WMTS Capabilities endpoint to auto-discover the URL template, tile grid, and CRS:

sources:
  swisstopo_caps:
    type: wmts
    capabilities_url: "https://wmts.geo.admin.ch/EPSG/3857/1.0.0/WMTSCapabilities.xml"
    layer: ch.swisstopo.pixelkarte-farbe
    tile_matrix_set: 3857
    attribution: "© swisstopo"

When capabilities_url is set, cartoload fetches the Capabilities XML and resolves the URL template, CRS, and tile grid from it. The layer and tile_matrix_set fields select the specific WMTS layer and TileMatrixSet within the Capabilities document. No urls field is needed in this mode.

XYZ¶

The xyz type is an alias for wmts — it uses the same URL template syntax and download mechanism:

sources:
  my_xyz:
    type: xyz
    urls:
      - "https://tile.example.com/${z}/${x}/${y}.png"
    attribution: "© Example"

STAC¶

Queries a STAC API collection endpoint and downloads assets (GeoTIFF or GeoPackage). The ${layer} variable resolves to the collection ID from defaults or source_args.

sources:
  my_stac:
    type: stac
    defaults:
      layer: my_collection_id
    urls:
      - "https://stac.example.com/api/v1/collections/${layer}"
    attribution: "© Example"

The data format is determined by the layer's format field: - format: geotiff — downloads GeoTIFF assets - format: gpkg — downloads GeoPackage (.gpkg.zip) assets, extracts and caches the .gpkg file

Asset filtering¶

When a STAC collection has multiple assets per item (e.g. different variants or resolutions), use asset_filter to select which one to download:

sources:
  swisstopo_stac:
    type: stac
    defaults:
      layer: ch.swisstopo.pixelkarte-farbe-pk25.noscale
      asset_filter:
        geoadmin:variant: komb
    urls:
      - "https://data.geo.admin.ch/api/stac/v1/collections/${layer}"

asset_filter can also be set per-layer via the dict source syntax:

source:
  ref: swisstopo_stac
  asset_filter:
    geoadmin:variant: krel

Layer-level asset_filter overrides the source-level default. When no filter is set, the first asset matching the expected media type is selected.

Path¶

References local files — directories (scanned recursively for matching files), individual file paths, or HTTP URLs that get downloaded to cache.

sources:
  my_local_data:
    type: path
    urls:
      - "/data/geotiffs/"                    # directory, scanned recursively
      - "../cache/my_stac/my_collection/"    # relative path to directory
      - "https://example.com/tile.tif"       # remote URL, downloaded to cache
    attribution: "© Example"

Fields¶

Template variables¶

All URL template variables use ${VAR} syntax. There are two resolution phases:

Config-level variables¶

Resolved once at pipeline start from source defaults and layer source_args:

Variable resolution order (later overrides earlier):

1. Inline defaults (${VAR:-default})
2. Source defaults dict
3. Layer source_args (from layer config)

Common config-level variables include ${layer} (WMTS layer name, STAC collection ID) and ${extension} (tile format), but these are not predefined — they must be set via defaults or source_args.

Per-tile variables¶

Resolved at download time for each tile (WMTS only):

These are the only predefined variables. All other variables (e.g., ${layer}, ${extension}) are config-level and must be provided via defaults or source_args.

Legacy syntax¶

For backward compatibility, {x}, {y}, {z}, {zoom} (without $) are also supported in URL templates.

Source type detection¶

When type is not explicitly set, it is auto-detected from the first URL: