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.

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 Standard and the conformance classes "TileSetMetadata", "TileMatrixSetLimits", and "JSONTileMatrixSetLimits" of the OGC Two Dimensional Tile Matrix Set and Tile Set Metadata 2.0 Standard.

Operations

Resource	Path	Methods	Media Types	Description
Dataset Tilesets	tiles	GET	HTML, JSON	Access dataset tilesets
Dataset Tileset	tiles/{tileMatrixSetId}	GET	JSON, TileJSON	Access dataset tileset
Dataset Tiles	tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}	GET	JPEG, MVT, PNG, TIFF, WEBP	Access tiles of a dataset.
Collection Tilesets	collections/{collectionId}/tiles	GET	HTML, JSON	Access collection tilesets
Collection Tileset	collections/{collectionId}/tiles/{tileMatrixSetId}	GET	JSON, TileJSON	Access collection tileset
Collection tiles	collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}	GET	JPEG, MVT, PNG, TIFF, WEBP	Access tiles of a collection.

Path Parameters

Name	Resources	Description
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

Name	Resources	Description
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

Name	Default	Description	Type	Since
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
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 TileSetMetadata ("JSON") and TileJSON ("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

Examples

Example of the specifications in the configuration file from the API for Vineyards in Rhineland-Palatinate.

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 Night, 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