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.

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 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 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
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
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, 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}. 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
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
tileLayer
{collectionId}
Specifies the tile provider layer.
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
cache
FILES
Deprecated 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" ]
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 See Tile-Provider Features.
array
v3.1
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
v3.1
collectionTiles
true
Enable vector tiles for each Feature Collection. Every tile contains a layer with the feature from the collection.
boolean
v3.3
singleCollectionEnabled
true
Deprecated See collectionTiles.
boolean
v3.3
datasetTiles
true
Enable vector tiles for the whole dataset. Every tile contains one layer per collection with the features of that collection.
boolean
v3.3
multiCollectionEnabled
true
Deprecated See datasetTiles.
boolean
v3.3
zoomLevelsCache
{}
Deprecated See Tile-Provider Features.
object
v3.1
seeding
{}
Deprecated See Tile-Provider Features.
object
v3.1
seedingOptions
{}
Deprecated (will be renamed to seeding in v4.0) Controls how and when tiles are precomputed, see Seeding options.
object
v3.1
limit
100000
Deprecated See Tile-Provider Features.
number
v3.1
ignoreInvalidGeometries
false
Deprecated See Tile-Provider Features.
boolean
v3.1
filters
{}
Deprecated See Tile-Provider Features.
object
v3.1
rules
{}
Deprecated See Tile-Provider Features.
object
v3.1
minimumSizeInPixel
0.5
Deprecated See Tile-Provider Features.
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.

NameDefaultDescriptionTypeSince
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 fileopen in new window. 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.

NameDefaultDescriptionTypeSince
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 instanceopen in new window. 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.

NameDefaultDescriptionTypeSince
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-Palatinateopen in new window.

At API level:


- buildingBlock: TILES
  enabled: true
  zoomLevels:
    WebMercatorQuad:
      min: 5
      max: 16
      default: 8
  seedingOptions:
    maxThreads: 1

For the vineyard features (aggregation of adjacent features up to zoom level 9):


    - buildingBlock: TILES
      rules:
        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

The tile provider, includes configuration for caches and seeding:


id: vineyards-tiles
providerType: TILE
providerSubType: FEATURES
caches:
- type: IMMUTABLE
  storage: MBTILES
  levels:
    WebMercatorQuad:
      min: 5
      max: 11
- type: DYNAMIC
  storage: MBTILES
  seeded: false
  levels:
    WebMercatorQuad:
      min: 12
      max: 16
layerDefaults:
  levels:
    WebMercatorQuad:
      min: 5
      max: 16
layers:
  __all__:
    id: __all__
    combine: ['*']
  vineyards:
    id: vineyards

Seeding example (no seeding at startup, rebuilding the cache every hour):


- buildingBlock: TILES
  seedingOptions:
    runOnStartup: false
    runPeriodic: '0 * * * *'
    purge: true

Example of using four threads for seeding:


- buildingBlock: TILES
  seedingOptions:
    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 seedingOptions.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 configuration (from the API Earth at Nightopen in new window):


- buildingBlock: TILES
  enabled: true
  tileProvider:
    type: MBTILES
    filename: dnb_land_ocean_ice.2012.54000x27000_geo.mbtiles