OGC API - Coverages
OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. OpenAPI is used to define the reusable API building blocks with responses available in different representations, such as JSON and HTML, as well as more domain specific formats (e.g. GeoTIFF, CIS RDF, LAS, JPEG XL, netCDF, JPEG 2000 with GMLJP2, etc.).
The OGC API family of standards is organized by resource type. OGC API - Coverages specifies the fundamental API building blocks for interacting with coverages. A coverage is a "function which returns values from its range for any direct position within its domain" (ISO 19123-1:2023).
If you are unfamiliar with the term ‘coverage’, the explanations on the Coverages DWG Wiki provide more detail and links to educational material. Additionally, Coverages: describing properties that vary with location (and time) in the W3C/OGC Spatial Data on the Web Best Practice document may be considered.
Overview of OGC API - Coverages - Part 1: Core
This OGC API - Coverages specification establishes how to access coverages. It integrates with the OGC API family of standards through OGC API - Common by:
- being accessible from an API landing page for a particular dataset,
- enabling the API to be described and documented using OpenAPI as per OGC API - Common - Part 1: Core,
- defining conformance classes specific to coverages,
- providing access to an OGC API collection of geospatial data (as defined in OGC API - Common - Part 2: Geospatial Data), as a coverage.
Resources
Defined in OGC API - Common - Part 1
{root} The root of the API for the dataset.
{root}/api The API definition and documentation.
{root}/conformance The conformance declaration.
Extended from OGC API - Common - Part 2 with additional properties
{root}/collections
The list of all collections available, some or all of which may be accessible using this Coverages API. Each of these collections contains a minimal subset of the object collection resource object described immediately below.
{root}/collections/{collectionId}
Description for the collection with the unique identifier {collectionId}, which may be accessible as a coverage. The resource includes elements such as an id, title, description, available crs and extent. This extent describes the domain of the coverage for each dimension, including the overall envelope, detailed sub-intervals where data is available, and/or a regular or irregular grid. This object also includes links to resources pertaining to this collection.
Defined in Coverages - Part 1
{root}/collections/{collectionId}/schema
Returns the schema for the coverage fields or properties of values available at each direct position. At minimum, a JSON Schema representation of this resource is available.
{root}/collections/{collectionId}/coverage
Returns the coverage data, including any self-describing information (such as the domain set, range type and metadata components in addition to the range set).
Defined in Tiles - Part 1 (Coverage Tiles)
{root}/collections/{collectionId}/coverage/tiles
Returns the list of tilesets available for this coverage.
{root}/collections/{collectionId}/coverage/tiles/{tileSetId}
Returns an individual coverage tileset for a particular 2D Tile Matrix Set
{root}/collections/{collectionId}/coverage/tiles/{tileSetId}/{tileMatrix}/{tileRow}/{tileCol}
Returns an individual coverage tile for a particular 2D Tile Matrix Set, tile matrix, tile row and tile column
Defined in Coverages - Part 1 "Scenes" requirements class
{root}/collections/{collectionId}/scenes
Returns the list of scenes available for this coverage (for multi-scenes coverages, when the Scenes requirement class is supported)
{root}/collections/{collectionId}/scenes/{sceneId}
Returns the scene metadata for an individual scene
{root}/collections/{collectionId}/scenes/{sceneId}/coverage
Returns the coverage data for an individual scene
Examples
GET /collections/myCoverage/coverage
Retrieve the whole coverage (the response may be downsampled if Scaling is supported by the server).
GET /collections/myCoverage/coverage?scale-factor=1
Retrieve the whole coverage at native resolution (the server will likely return a 400 error for large datasets).
GET /collections/myCoverage/coverage?bbox=10,40,20,50
Retrieve coverage spatial subsets between 40 and 50 degrees North, 10 and 20 degrees East, using the bbox query parameter.
GET /collections/myCoverage/coverage?bbox=160.6,-55.95,-170,-25.89
Retrieve coverage spatial subsets using the bbox query parameter, crossing the antimeridian.
GET /collections/myCoverage/coverage?subset=Lat(40:50),Lon(10:20)
Retrieve a coverage spatial subset using the subset query parameter.
GET /collections/myCoverage/coverage?properties=B02,B03,B04
Retrieve bands B02, B03 and B04 (field selection a.k.a. "range subsetting").
GET /collections/myCoverage/coverage?scale-size=Lon(800),Lat(400)
Retrieve a the coverage at a a resolution of 800 cells for the longitude axis and 400 cells for the latitude axis.
GET /collections/myCoverage/coverage?scale-factor=2
Retrieve a the coverage at a downsampled (2x) resolution.
GET /collections/myCoverage/coverage?scale-axes=Lon(2)
Retrieve a the coverage at a downsampled (2x) resolution for the longitude axis.
