Skip to content

Allows to provide links to web maps for visualization purposes

License

Notifications You must be signed in to change notification settings

stac-extensions/web-map-links

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Web Map Links Extension Specification

This document explains the Web Map Links Extension to the SpatioTemporal Asset Catalog (STAC) specification. It allows to provide links to web map services for visualization purposes.

The following services are supported:

Important resources in this extension:

Link Object Fields

This extension only extends the Link Object used in all STAC entities (Catalogs, Collections, Items). It requires specific relation types to be set for the rel field in the Link Object.

An attribution field is not defined as part of this extension, but it is RECOMMENDED to provide an attribution in via the attribution field as defined the Attribtion Extension.

3D Tiles

Links to a 3D Tiles implementation (versions 1.x).

Field Name Type Description
rel string REQUIRED. Must be set to 3d-tiles.
href string REQUIRED. Link to a tileset.
type string Recommended to be set to application/json.

OGC WMS

Links to a OGC Web Map Service (WMS) implementation (versions 1.3.0). Only (tiled) "Basic WMS" is supported at this time.

Field Name Type Description
rel string REQUIRED. Must be set to wms.
href string REQUIRED. Link to the WMS, without any WMS specific query parameters.
type string The media type to be used for the tile requests, e.g. image/png or image/jpeg.
wms:layers [string] REQUIRED. The layers to show on the map by default. Can't be empty.
wms:styles [string] The styles to show on the map by default. If not provided or empty, an empty string will be used for the query parameter.
wms:dimensions Map<string, string> Any additional dimension parameters to add to the request as query parameters (e.g. the dimensions TIME or ELEVATION).
wms:transparent boolean Sets whether the layers should be rendered transparent or not. Default: false

If you provide multiple array elements in wms:layers (e.g. ["layerA", "layerB"]), each should occur in a separate layer in the mapping library so that requests for the layers are sent. If you want to send multiple layers in a single request, provide them as a string with comma-separated values: ["layerA,layerB"]. wms:layers and wms:styles work in parallel, so the first style in the array will be used for the first layer, etc.

OGC WMTS

Links to a OGC Web Map Tile Service (WMTS) implementation (versions 1.x).

Field Name Type Description
rel string REQUIRED. Must be set to wmts.
href string REQUIRED. Link to the WMTS, without any WMTS specific query parameters.
type string The media type to be used for the tile requests, e.g. image/png or image/jpeg.
href:servers [string] See href:servers below for details.
wmts:layer string|[string] REQUIRED. The layers to show on the map by default, either a list of layer names or a single layer name.
wmts:dimensions Map<string, string> Any additional dimension parameters to add to the request as key-value-pairs, usually added as query parameters.

If you provide multiple array elements in wmts:layer (e.g. ["layerA", "layerB"]), each should occur in a separate layer in the mapping library so that individual requests for the layers are sent.

href

For WMTS, the href is pointing to the URL of the Capabilities document, but without the query parameters for the Capabilities request. So if your Capabilities can be requested from https://example.com/geoserver/service/wmts?service=wmts&request=GetCapabilities you'd provide https://example.com/geoserver/service/wmts as href.

The href can contain an optional server placeholder {s}. If {s} is used, the field href:servers MUST be provided.

PMTiles

Links to a PMTiles file (versions 3.x).

Field Name Type Description
rel string REQUIRED. Must be set to pmtiles.
href string REQUIRED. Link to a PMTiles file (usually ends with .pmtiles).
type string Recommended to be set to application/vnd.pmtiles.
pmtiles:layers [string] For vector tiles, the layers to show on the map by default. If not provided, it's up to the discretion of the implementation to choose a layer from the vector_layers in the PMTiles metadata.

The Tile Type of the PMTiles data source can be read from the first 127 bytes of the the binary header.

It is typical to assume a tile size of 256x256 display (CSS) pixels for raster tiles and 512x512 display pixels for vector tiles. Tile sizes are not guaranteed to be uniform across an entire archive.

XYZ

Links to a XYZ, also known as slippy map.

Field Name Type Description
rel string REQUIRED. Must be set to xyz.
href string REQUIRED. Link to the XYZ as a templated URI.
type string Recommended to be set to the image file type the XYZ returns by default, usually image/png or image/jpeg.
href:servers [string] See href:servers below for details.

href

For XYZ, the href is a templated URI. It MUST include the following placeholders: {x}, {y} and {z} and MAY include a placeholder for the server: {s}. If {s} is used, the field href:servers MUST be provided. All other parameters should be hard-coded with specific values, e.g. the {r} parameter in Leaflet could be replaced by 2x.

TileJSON

Links to a TileJSON document.

Field Name Type Description
rel string REQUIRED. Must be set to tilejson.
href string REQUIRED. Link to the valid TileJSON document.
type string Recommended to be set to application/json.

General

The following field applies to multiple types of web mapping services:

Field Name Type Description
href:servers [string] A list of replacement values for {s} in hrefs.

href:servers

This field is used to specify a set of URLs for a web mapping library so that requests can be sent to multiple servers, which can avoid request limits in web browsers.

The field is used across multiple types of web mapping services and applies currently to XYZ and WMTS.

It is REQUIRED if {s} is used in the href and then a list of at least 2 allowed values for the placeholder {s} must be provided. If you only have a single value don't provide href:servers and instead hard-code the value into the href.

The implementations can expand the given values into multiple URLs. For example, if you provide https://{s}/example as href and href:servers is ["a.com", "b.eu"] you can expand that to ["https://a.com/example", "https://b.eu/example"].

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples

About

Allows to provide links to web maps for visualization purposes

Resources

License

Stars

Watchers

Forks

Packages

No packages published