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 module 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. If that building block is not configured, it is automatically enabled if Tiles is enabled.

Storage

The tile cache is located in the data directory under the relative path cache/tiles/{apiId} (old) or in the Store (new) 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
extensionType		Deprecated See buildingBlock.	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	{ "type": "FEATURES", ... }	Deprecated (from v4.0 on you have to use Tile Provider entities) Specifies the data source for the tiles, see Tile provider objects.	object	v3.1
tileProviderId	null	Deprecated (will be renamed to tileProvider in v4.0) Specifies the data source for the tiles, see Tile Providers.	string	v3.3
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
tileLayer	__all__ | {collectionId}	Deprecated See tileProviderTileset.	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
cache	FILES	*Deprecated (from v4.0 on you have to use Tile Provider entities) FILES stores each tile as a file in the file system. MBTILES stores the tiles in an MBTiles file (one MBTiles file per tileset).	string	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 module HTML 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
tileEncodings	[ "MVT" ]	Deprecated (from v4.0 on you have to use Tile Provider entities) List of tile formats to be supported, in general MVT (Mapbox Vector Tiles), PNG, WebP and JPEG are allowed. The actually supported formats depend on the Tile Provider.	array	v3.1
center	[ 0, 0 ]	Deprecated (from v4.0 on you have to use Tile Provider entities)	array	v3.1
zoomLevels	{ "WebMercatorQuad" : { "min": 0, "max": 23 } }	Deprecated (from v4.0 on you have to use Tile Provider entities) Controls the zoom levels available for each active tiling scheme as well as which zoom level to use as default.	object	v3.1
collectionTiles	true	Deprecated (from v4.0 on you have to use Tile Provider entities) Enable vector tiles for each Feature Collection. Every tile contains a layer with the feature from the collection. If a Tile Provider is specified, tiles will always be enabled for a collection, if the tileset is specified in the Tile Provider, independent of the value of this option.	boolean	v3.3
singleCollectionEnabled	true	Deprecated See collectionTiles.	boolean	v3.3
datasetTiles	true	Deprecated (from v4.0 on you have to use Tile Provider entities) Enable vector tiles for the whole dataset. Every tile contains one layer per collection with the features of that collection. If a Tile Provider is specified, tiles will always be enabled for the dataset, if the corresponding tileset is specified in the Tile Provider, independent of the value of this option.	boolean	v3.3
multiCollectionEnabled	true	Deprecated See datasetTiles.	boolean	v3.3
zoomLevelsCache	{}	Deprecated (from v4.0 on you have to use Tile Provider entities)	object	v3.1
seeding	{}	Deprecated (from v4.0 on you have to use Tile Provider entities)	object	v3.1
seedingOptions	{}	Deprecated (from v4.0 on you have to use Tile Provider entities)	object	v3.1
limit	100000	Deprecated (from v4.0 on you have to use Tile Provider entities)	number	v3.1
ignoreInvalidGeometries	false	Deprecated (from v4.0 on you have to use Tile Provider entities)	boolean	v3.1
filters	{}	Deprecated (from v4.0 on you have to use Tile Provider entities)	object	v3.1
rules	{}	Deprecated (from v4.0 on you have to use Tile Provider entities)	object	v3.1
minimumSizeInPixel	0.5	Deprecated (from v4.0 on you have to use Tile Provider entities)	number	v3.1

Tile Provider

Deprecated (from v4.0 on you have to use Tile Provider entities)

There are currently three types of Tile providers supported:

• FEATURES: The tiles are derived from a feature provider.
• MBTILES: The tiles of a tileset in the "WebMercatorQuad" tiling scheme are available in an MBTiles archive.
• TILESERVER: The tiles are retrieved from a TileServer GL instance.

Features

In this tile provider, the tiles in Mapbox Vector Tiles format are derived from the features provided by the API in the area of the tile.

Name	Default	Description	Type	Since
type	FEATURES	Fixed value, identifies the tile provider type.	string	v2.0
tileEncodings	[ "MVT" ]	Controls which formats should be supported for the tiles. Currently only Mapbox Vector Tiles ("MVT") is available.	array	v2.0
zoomLevels	{ "WebMercatorQuad" : { "min": 0, "max": 23 } }	Controls the zoom levels available for each active tiling scheme as well as which zoom level to use as default.	object	v2.0
zoomLevelsCache	{}	Zoom levels for which tiles are cached.	object	v2.0
seedingOptions		Controls how and when tiles are precomputed, see Seeding options.	object	v2.0
seeding	{}	Zoom levels per enabled tile encoding for which the tile cache should be seeded on startup.	object	v2.0
filters	{}	Filters to select a subset of feature for certain zoom levels using a CQL filter expression, see example below.	object	v2.0
rules	{}	Rules to postprocess the selected features for a certain zoom level. Supported operations are: selecting a subset of feature properties (properties), spatial merging of features that intersect (merge), with the option to restrict the operations to features with matching attributes (groupBy). See the example below. For merge, the resulting object will only obtain properties that are identical for all merged features.	object	v2.0
center	[ 0, 0 ]	Longitude and latitude that a map with the tiles should be centered on by default.	array	v2.0
limit	100000	Maximum number of features contained in a single tile per query.	number	v2.0
singleCollectionEnabled	true	Enable vector tiles for each Feature Collection. Every tile contains a layer with the feature from the collection.	boolean	v2.0
multiCollectionEnabled	true	Enable vector tiles for the whole dataset. Every tile contains one layer per collection with the features of that collection.	boolean	v2.0
ignoreInvalidGeometries	false	Ignore features with invalid geometries. Before ignoring a feature, an attempt is made to transform the geometry to a valid geometry. The topology of geometries might be invalid in the data source or in some cases the quantization of coordinates to integers might render it invalid.	boolean	v2.0
minimumSizeInPixel	0.5	Features with line geometries shorter that the given value are excluded from tiles. Features with surface geometries smaller than the square of the given value are excluded from the tiles. The value 0.5 corresponds to half a "pixel" in the used coordinate reference system.	number	v2.0

MbTiles

With this tile provider, the tiles are provided via an MBTiles file. The tile format and all other properties of the tileset resource are derived from the contents of the MBTiles file. Only the "WebMercatorQuad" tiling scheme is supported.

Name	Default	Description	Type	Since
type	MBTILES	Fixed value, identifies the tile provider type.	string	v2.0
filename	null	Filename of the MBTiles file in the api-resources/tiles/{apiId} directory.	string	v2.0
tileMatrixSetId	WebMercatorQuad	Tiling scheme used in the MBTiles file.	string	v2.0

TileServer

With this tile provider, the tiles are obtained from TileServer-GL instance. Only the "WebMercatorQuad" tile scheme is supported.

In the current version, this provider is only supported in the Map Tiles module. Only bitmap tile formats are supported. Seeding or caching are not supported.

This tile provider is experimental and its configuration options may change in future versions.

Name	Default	Description	Type	Since
type	TILESERVER	Fixed value, identifies the tile provider type.	string	v2.0
urlTemplate	null	URL template for accessing tiles. Parameters to use are {tileMatrix}, {tileRow}, {tileCol} and {fileExtension}.	string	v2.0
urlTemplateSingleCollection	null	URL template for accessing tiles for a collection.	string	v2.0
tileEncodings	[]	List of tile formats to be supported, allowed are PNG, WebP and JPEG.	array	v2.0

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