Sources

A data source, declared under a block’s sources: map (then referenced from a layer by bare name) or inline as a layer’s source:. The type key selects the variant. For narrative and examples see Data Sources.

One of 6 variants, selected by type: geojson, vector, raster, raster-dem, image, video.

`type: geojson`

`type`

Path: sources.<source-id>.type · Type: "geojson" · Required

Source type

`url`

Path: sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

URL to fetch GeoJSON data

`data`

Path: sources.<source-id>.data · Type: any

Inline GeoJSON object

`prefetchedData`

Path: sources.<source-id>.prefetchedData · Type: any

Pre-fetched data from build time

`fetchStrategy`

Path: sources.<source-id>.fetchStrategy · Type: "runtime" | "build" | "hybrid" · Default: "runtime"

When to fetch data: runtime (default), build, or hybrid

`stream`

Path: sources.<source-id>.stream · Type: object

WebSocket/SSE streaming configuration

`type`

Path: sources.<source-id>.stream.type · Type: "websocket" | "sse" · Required

Streaming connection type

`url`

Path: sources.<source-id>.stream.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

WebSocket or SSE endpoint URL

`reconnect`

Path: sources.<source-id>.stream.reconnect · Type: boolean · Default: true

Automatically reconnect on disconnect

`reconnectMaxAttempts`

Path: sources.<source-id>.stream.reconnectMaxAttempts · Type: number · Default: 10 · Minimum: 0

Maximum number of reconnection attempts

`reconnectDelay`

Path: sources.<source-id>.stream.reconnectDelay · Type: number · Default: 1000 · Minimum: 100

Initial delay in milliseconds before reconnecting

`reconnectMaxDelay`

Path: sources.<source-id>.stream.reconnectMaxDelay · Type: number · Default: 30000 · Minimum: 1000

Maximum delay in milliseconds for exponential backoff

`eventTypes`

Path: sources.<source-id>.stream.eventTypes · Type: string[]

Event types to listen for (SSE only)

`protocols`

Path: sources.<source-id>.stream.protocols · Type: string | string[]

WebSocket sub-protocols (WebSocket only)

`refresh`

Path: sources.<source-id>.refresh · Type: object

Polling refresh configuration

`refreshInterval`

Path: sources.<source-id>.refresh.refreshInterval · Type: number · Minimum: 1000

Polling interval in milliseconds (minimum 1000ms)

`updateStrategy`

Path: sources.<source-id>.refresh.updateStrategy · Type: "replace" | "merge" | "append-window" · Default: "replace"

How to merge incoming data with existing data

`updateKey`

Path: sources.<source-id>.refresh.updateKey · Type: string

Property key for merge strategy (required for merge)

`windowSize`

Path: sources.<source-id>.refresh.windowSize · Type: number · Greater than: 0

Maximum features to keep (append-window)

`windowDuration`

Path: sources.<source-id>.refresh.windowDuration · Type: number · Greater than: 0

Maximum age in milliseconds (append-window)

`timestampField`

Path: sources.<source-id>.refresh.timestampField · Type: string

Property field containing timestamp (append-window)

`refreshInterval`

Path: sources.<source-id>.refreshInterval · Type: number · Minimum: 1000 · Deprecated

Polling interval in milliseconds (legacy, use refresh.refreshInterval)

`updateStrategy`

Path: sources.<source-id>.updateStrategy · Type: "replace" | "merge" | "append-window" · Deprecated

Update strategy (legacy, use refresh.updateStrategy)

`updateKey`

Path: sources.<source-id>.updateKey · Type: string · Deprecated

Update key (legacy, use refresh.updateKey)

`loading`

Path: sources.<source-id>.loading · Type: object

Loading UI configuration

`enabled`

Path: sources.<source-id>.loading.enabled · Type: boolean · Default: false

Enable loading UI overlays

`message`

Path: sources.<source-id>.loading.message · Type: string

Custom loading message to display

`showErrorOverlay`

Path: sources.<source-id>.loading.showErrorOverlay · Type: boolean · Default: true

Show error overlay on fetch failure

`cache`

Path: sources.<source-id>.cache · Type: object

Cache configuration

`enabled`

Path: sources.<source-id>.cache.enabled · Type: boolean · Default: true

Enable HTTP caching

`ttl`

Path: sources.<source-id>.cache.ttl · Type: number · Greater than: 0

Cache TTL in milliseconds (overrides default)

`cluster`

Path: sources.<source-id>.cluster · Type: boolean

Enable point clustering

`clusterRadius`

Path: sources.<source-id>.clusterRadius · Type: integer · Minimum: 0

Cluster radius in pixels (default: 50)

`clusterMaxZoom`

Path: sources.<source-id>.clusterMaxZoom · Type: number · Range: 0 to 24

Maximum zoom level to cluster points

`clusterMinPoints`

Path: sources.<source-id>.clusterMinPoints · Type: integer · Minimum: 2

Minimum points to form a cluster

`clusterProperties`

Path: sources.<source-id>.clusterProperties · Type: map of any

Aggregate cluster properties

`tolerance`

Path: sources.<source-id>.tolerance · Type: number

Douglas-Peucker simplification tolerance (higher = simpler geometry)

`buffer`

Path: sources.<source-id>.buffer · Type: number

Tile buffer size on each side, in pixels at tile scale

`lineMetrics`

Path: sources.<source-id>.lineMetrics · Type: boolean

Calculate line distance metrics (required for line-gradient)

`generateId`

Path: sources.<source-id>.generateId · Type: boolean

Assign feature ids from each feature’s index (enables feature-state)

`promoteId`

Path: sources.<source-id>.promoteId · Type: string | map of string

Feature property to use as the feature id (for feature-state), or a map of source-layer name to property name

`attribution`

Path: sources.<source-id>.attribution · Type: string

Attribution text

`type: vector`

`type`

Path: sources.<source-id>.type · Type: "vector" · Required

Source type

`url`

Path: sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

TileJSON URL

`tiles`

Path: sources.<source-id>.tiles · Type: string[]

Tile URL template array

`minzoom`

Path: sources.<source-id>.minzoom · Type: number · Range: 0 to 24

Minimum zoom level

`maxzoom`

Path: sources.<source-id>.maxzoom · Type: number · Range: 0 to 24

Maximum zoom level

`bounds`

Path: sources.<source-id>.bounds · Type: [number, number, number, number]

Bounding box [west, south, east, north]

`scheme`

Path: sources.<source-id>.scheme · Type: "xyz" | "tms"

Tile coordinate scheme

`attribution`

Path: sources.<source-id>.attribution · Type: string

Attribution text

`promoteId`

Path: sources.<source-id>.promoteId · Type: string | map of string

Feature property to use as the feature id (for feature-state), or a map of source-layer name to property name

`volatile`

Path: sources.<source-id>.volatile · Type: boolean

Skip the tile cache (MapLibre volatile); for frequently changing tiles

`type: raster`

`type`

Path: sources.<source-id>.type · Type: "raster" · Required

Source type

`url`

Path: sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

TileJSON URL

`tiles`

Path: sources.<source-id>.tiles · Type: string[]

Tile URL template array

`tileSize`

Path: sources.<source-id>.tileSize · Type: integer · Default: 512 · Minimum: 1

Tile size in pixels

`minzoom`

Path: sources.<source-id>.minzoom · Type: number · Range: 0 to 24

Minimum zoom level

`maxzoom`

Path: sources.<source-id>.maxzoom · Type: number · Range: 0 to 24

Maximum zoom level

`bounds`

Path: sources.<source-id>.bounds · Type: [number, number, number, number]

Bounding box [west, south, east, north]

`scheme`

Path: sources.<source-id>.scheme · Type: "xyz" | "tms"

Tile coordinate scheme

`attribution`

Path: sources.<source-id>.attribution · Type: string

Attribution text

`volatile`

Path: sources.<source-id>.volatile · Type: boolean

Skip the tile cache (MapLibre volatile); for frequently changing tiles

`type: raster-dem`

`type`

Path: sources.<source-id>.type · Type: "raster-dem" · Required

Source type

`url`

Path: sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

TileJSON URL

`tiles`

Path: sources.<source-id>.tiles · Type: string[]

Tile URL template array

`tileSize`

Path: sources.<source-id>.tileSize · Type: integer · Default: 512 · Minimum: 1

Tile size in pixels

`encoding`

Path: sources.<source-id>.encoding · Type: "terrarium" | "mapbox" | "custom" · Default: "mapbox"

How elevation is encoded in the tile’s RGB channels

`minzoom`

Path: sources.<source-id>.minzoom · Type: number · Range: 0 to 24

Minimum zoom level

`maxzoom`

Path: sources.<source-id>.maxzoom · Type: number · Range: 0 to 24

Maximum zoom level

`bounds`

Path: sources.<source-id>.bounds · Type: [number, number, number, number]

Bounding box [west, south, east, north]

`attribution`

Path: sources.<source-id>.attribution · Type: string

Attribution text

`volatile`

Path: sources.<source-id>.volatile · Type: boolean

Skip the tile cache (MapLibre volatile); for frequently changing tiles

`type: image`

`type`

Path: sources.<source-id>.type · Type: "image" · Required

Source type

`url`

Path: sources.<source-id>.url · Type: string · Required · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

Image URL

`coordinates`

Path: sources.<source-id>.coordinates · Type: [[number, number], [number, number], [number, number], [number, number]] · Required

Four corner coordinates [topLeft, topRight, bottomRight, bottomLeft]

`type: video`

`type`

Path: sources.<source-id>.type · Type: "video" · Required

Source type

`urls`

Path: sources.<source-id>.urls · Type: string[] · Required · Min items: 1

Array of video URLs for browser compatibility

`coordinates`

Path: sources.<source-id>.coordinates · Type: [[number, number], [number, number], [number, number], [number, number]] · Required

Four corner coordinates [topLeft, topRight, bottomRight, bottomLeft]