Tiles

specstableimplmature

Publish geographic data as tiles.

Scope

This building block supports tiles derived from feature data or tiles that are provided by an external source.

The supported tile formats are:

  • MVT (Mapbox Vector Tile)
  • PNG
  • WebP
  • JPEG
  • TIFF

For tiles that are derived from feature data, only Mapbox Vector Tiles are supported as a file format plus PNG map tiles derived from these vector tiles using one or more MapLibre styles.

All tiles of an API are sourced from a single tile provider.

Conformance Classes

The building block implements the conformance classes "Core", "TileSet", "TileSets List", "Dataset TileSets", "GeoData TileSets", "Collections Selection", "DateTime", "OpenAPI Specification 3.0 API definition", "Mapbox Vector Tiles", "PNG", "JPEG", and "TIFF" of the OGC API - Tiles - Part 1: Core 1.0 Standardopen in new window and the conformance classes "TileSetMetadata", "TileMatrixSetLimits", and "JSONTileMatrixSetLimits" of the OGC Two Dimensional Tile Matrix Set and Tile Set Metadata 2.0 Standardopen in new window.

Operations

ResourcePathMethodsMedia TypesDescription
Dataset Vector Tilesets
tiles
GET
Access dataset vector tilesets
Dataset Vector Tileset
tiles/{tileMatrixSetId}
GET
Access a vector tileset of a dataset.
Dataset Vector Tiles
tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}
GET
Access vector tiles of a dataset.
Collection Vector Tilesets
collections/{collectionId}/tiles
GET
Access collection vector tilesets
Collection Vector Tileset
collections/{collectionId}/tiles/{tileMatrixSetId}
GET
Access collection vector tileset
Collection Vector Tiles
collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}
GET
Access tiles of a collection.

Path Parameters

NameResourcesDescription
collectionId
Collection Tilesets, Collection Tileset, Collection Tile
The identifier of the feature collection.
tileMatrixSetId
Dataset Tilesets, Dataset Tileset, Dataset Tile, Collection Tilesets, Collection Tileset, Collection Tile
The identifier of the tiling scheme.
tileMatrix
Dataset Tile, Collection Tile
The zoom level of the tile in the tiling scheme.
tileRow
Dataset Tile, Collection Tile
The row of the tile at the zoom level in the tiling scheme.
tileCol
Dataset Tile, Collection Tile
The column of the tile at the zoom level in the tiling scheme.

Query Parameters

NameResourcesDescription
collections
Dataset Tile
The collections of the dataset that should be included in the tile. The parameter value is a comma-separated list of collection identifiers.
datetime
Dataset Tile, Collection Tile
Include only features in the tile that have a primary instant or interval that intersects the provided instant or interval.
f
Dataset Tile
Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f
Collection Tile
Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f
Dataset Tileset, Collection Tileset
Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f
Dataset Tilesets, Collection Tilesets
Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
limit
Dataset Tile, Collection Tile
The parameter restricts the number of features that are included in the tile.

Configuration

Prerequisites

The building block Tile Matrix Sets must be enabled

Storage

The tile cache is located in the Store as resource with path tiles/{apiId}.

If the data for an API or tile configuration has been changed, then the cache directory for the API should be deleted so that the cache is rebuilt with the updated data or rules.

Options

NameDefaultDescriptionTypeSince
buildingBlock
Always TILES.
string
v3.1
enabled
false
Enable the building block?
boolean
v3.1
transformations
{}
Property transformations do not affect data sources, they are applied on-the-fly as part of the encoding. Filter expressions do not take transformations into account, they have to be based on the source values. That means queryable properties (see queryables in Features) should not use transformations in most cases. The exception to the rule is the HTML encoding, where readability might be more important than filter support.
object
v3.1
defaultProfiles
{}
Allows to change the default value of the profile parameter for a specific format. The key is the kind of profile, e.g. rel or val. The value is the default profile value, e.g. rel-as-uri or val-as-title. If only some or no profile kinds are set, the application defaults apply.
object
v4.2
maxMultiplicity
3
If the feature schema includes array properties, maxMultiplicity properties will be created for each array property. If an instance has more values in an array, only the first values are included in the data.
number
v3.2
caching
{}
Sets fixed values for HTTP Caching Headers for the resources.
object
v3.1
tileProvider
null
Specifies the data source for the tiles, see Tile Providers.
string
v4.0
tileProviderId
null
Deprecated See tileProvider.
string
v4.0
tileProviderTileset
__all__ | {collectionId}
Specifies the tileset from the tile provider that should be used. The default is __all__ for dataset tiles and {collectionId} for collection tiles.
string
v3.3
tileSetEncodings
[ "JSON", "TileJSON" ]
Controls which formats are supported for the tileset resources. Available are OGC TileSetMetadataopen in new window ("JSON") and TileJSONopen in new window ("TileJSON").
array
v3.1
mapClientType
MAP_LIBRE
Selection of the map client to be used in the HTML output. The default is MapLibre GL JS, only the "WebMercatorQuad" tiling scheme is supported. Alternatively 'OPEN_LAYERS' is supported as well (OpenLayers). The support of Open Layers only makes sense if other of the predefined tiling schemes should be supported in the HTML output. With OPEN_LAYERS no styles are supported.
string
v3.1
style
DEFAULT
A style in the style repository to be used in maps with tiles by default. With DEFAULT the defaultStyle from the HTML building block is used. If the map client is MapLibre, the style must be available in the Mapbox format. If the style is set to NONE, a simple wireframe style will be used with OpenStreetMap as a basemap. If the map client is Open Layers, the setting is ignored.
string
v3.1
removeZoomLevelConstraints
false
If true is selected, the minzoom and maxzoom specifications for the layer objects are removed from the style specified in style so that the features are displayed at all zoom levels. This option should not be used if the style provides different presentations depending on the zoom level, otherwise all layers will be displayed at all zoom levels at the same time.
boolean
v3.1
wmts
NONE
Adds support for OGC WMTS 1.0.0 (HTTP RESTful binding) for tilesets. NONE disables support, ALL adds all dataset and collection raster tilesets. DATASET publishes all dataset raster tilesets, COLLECTION all collection raster tilesets.
string
v3.1

Examples

Example of the specifications in the configuration file from the API for Vineyards in Rhineland-Palatinateopen in new window.

At API level (since there is only a single feature type, the dataset tileset is the same as the tileset of the single collection):


- buildingBlock: TILES
  enabled: true
  tileProviderTileset: vineyards

The tile provider, includes configuration for caches (two caches, an immutable cache up to level 12 and an unseeded dynamic cache for the other levels) adjacent features are aggregated up to zoom level 9:


id: vineyards-tiles
providerType: TILE
providerSubType: FEATURES
caches:
- type: IMMUTABLE
  storage: MBTILES
  levels:
    WebMercatorQuad:
      min: 5
      max: 12
- type: DYNAMIC
  storage: MBTILES
  seeded: false
  levels:
    WebMercatorQuad:
      min: 13
      max: 18
tilesets:
  vineyards:
    id: vineyards
    levels:
      WebMercatorQuad:
        min: 5
        max: 18
    transformations:
      WebMercatorQuad:
      - min: 5
        max: 7
        merge: true
        groupBy:
        - region
      - min: 8
        max: 8
        merge: true
        groupBy:
        - region
        - subregion
      - min: 9
        max: 9
        merge: true
        groupBy:
        - region
        - subregion
        - cluster

Seeding example (no seeding at startup, rebuilding the cache every hour) in a Features tile provider:


providerType: TILE
providerSubType: FEATURES
seeding:
  runOnStartup: false
  runPeriodic: '0 * * * *'
  purge: true

Example of using four threads for seeding:


providerType: TILE
providerSubType: FEATURES
seeding:
  maxThreads: 4

For this, at least 4 threads must be configured for background processes in the global configuration (cfg.yml), for example:


backgroundTasks:
  maxThreads: 4

These settings make multiple background processes possible in the first place. So, even without changes to the seeding options, this would allow parallel execution of seeding for 4 APIs.

If maxThreads in the seeding options is greater than 1, it means that the seeding will be split into n parts, where n is the number of threads available when the seeding starts, bounded by seedingOptions.maxThreads.

So, for example, setting seeding.maxThreads to 2 with the specified cfg.yml will split the seeding into 2 parts if at least 2 of the 4 threads are available. If 3 threads are used by other services, it will not be split. And if all 4 threads are busy, it will wait until at least 1 thread becomes available.

Example of the specifications in the configuration file from the API Earth at Nightopen in new window, which has an MBTiles tile provider..

At API level, only the TILES building block needs to be enabled and the tileset in the tile provider is referenced:


- buildingBlock: TILES
  enabled: true
  tileProviderTileset: earthatnight

The tile provider defines a single tileset and references the MBTiles file:


id: earthatnight-tiles
providerType: TILE
providerSubType: MBTILES
tilesets:
  earthatnight:
    id: earthatnight
    source: earthatnight/dnb_land_ocean_ice.2012.54000x27000_geo.mbtiles

The tile provider defines two raster tilesets (style: "default", tile matrix set: "WebMercatorQuad" and "AdV_25832"):


id: vineyards-tiles
providerType: TILE
providerSubType: FEATURES
seeding:
  runOnStartup: true
  maxThreads: 8
caches:
- type: IMMUTABLE
  storage: PER_JOB
  levels:
    WebMercatorQuad:
      min: 5
      max: 16
    AdV_25832:
      min: 0
      max: 11
rasterTilesets:
  vineyards:
    styles:
      - vineyards/default.json
tilesets:
  vineyards:
    id: vineyards
    center:
      lon: 7.35
      lat: 49.8
    levels:
      WebMercatorQuad:
        min: 5
        max: 16
        default: 8
      AdV_25832:
        min: 0
        max: 11
        default: 3
    transformations:
      WebMercatorQuad:
      - min: 5
        max: 7
        merge: true
        groupBy:
        - region
      - min: 8
        max: 8
        merge: true
        groupBy:
        - region
        - subregion
      - min: 9
        max: 9
        merge: true
        groupBy:
        - region
        - subregion
        - cluster
      AdV_25832:
      - min: 0
        max: 2
        merge: true
        groupBy:
        - region
      - min: 3
        max: 3
        merge: true
        groupBy:
        - region
        - subregion
      - min: 4
        max: 4
        merge: true
        groupBy:
        - region
        - subregion
        - cluster