Latest draft specifications: HTML PDF
Latest draft User's Guide: HTML PDF
See the latest OpenAPI definition with SwaggerUI.
This GitHub repository contains OGC's candidate standard for accessing geospatial data resources on the web as a coverage, 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. CIS RDF, netCDF, GeoTIFF).
The OGC API family of standards is organized by resource type. OGC API - Coverages specifies the fundamental API building blocks for interacting with coverages. The spatial data community uses the term 'coverage' for homogeneous collections of values located in space/time, such as spatio-temporal sensor, image, simulation, and statistics data.
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.
Please note that this Readme holds an informative introduction, the
authoritative specification is contained in the folder standard. There is also
a nightly build.
This OGC API - Coverages standard establishes an access mechanism for coverages as defined by the OGC Abstract Specification Topic 6 / ISO 19123-1 Schema for coverage geometry and functions through a Web API which can be described by an API description language such as the OpenAPI specification.
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.
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. For coverages, a link to the record schema described below will be included.
This resource is comparable to a WCS DescribeCoverage response, with the exception that the schema, corresponding to Coverage Implementation Schema (CIS) range type, needs to be retrieved separately.
{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. This resource is comparable to the CIS range type portion of the WCS DescribeCoverage response, and is retrieved separately from the collection description to accommodate more complex record schemas including several record fields and/or detailed semantic annotations.
{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 of CIS). This resource is comparable to a WCS GetCoverage response.
{root}/collections/{collectionId}/tiles
Returns the list of tilesets available for this coverage.
{root}/collections/{collectionId}/tiles/{tileSetId}
Returns an individual coverage tileset for a particular 2D Tile Matrix Set
{root}/collections/{collectionId}/tiles/{tileSetId}/{tileMatrix}/{tileRow}/{tileCol}
Returns an individual coverage tile for a particular 2D Tile Matrix Set, tile matrix, tile row and tile column
{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
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 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.
The Core Requirements Class is the minimal useful service interface for an OGC Coverages API. The requirements specified in this Requirements Class are mandatory for all implementations of OGC API - Coverages.
The Coverage Tiles Requirements Class defines how to combine the OGC API - Tiles building blocks with the Coverages API to request coverage tiles.
The Scenes Requirements Class defines how to present separate components of a coverage as individual scenes, in addition to an overall coverage of the whole collection.
The Subset Requirements Class defines the subset, bbox and datetime parameters to select a subset of a coverage of any coordinate reference system and any dimension.
The Scaling Requirements Class defines the scale-factor, scale-size and scale-axes parameters for retrieving data from n-dimensional Range Sets at a resolution different than the original.
The Field Selection (Range Subsetting) Requirements Class defines the properties parameter for selecting a subset of the bands (defined in the Range Type) to retrieve from Range Sets.
The Coordinate Reference System Requirements Class defines the crs parameter to request coverage data in an alternate output coordinate reference system.
The Encoding Requirements Classes address support for formats commonly used for encoding coverage data.
The OpenAPI 3.0 Requirements Class defines additonal requirements in addition to those defined in OGC API - Common - Part 1: Core to facilitate identifying coverage resources from an OpenAPI 3.0 API Definition.
Those who want to just see the endpoints and responses can explore generic OpenAPI definitions in this directory (or visualize the bundled definition with SwaggerUI:
Implementations of the draft standard are listed at the link below:
Implementations of the draft specification / demo services
Join the mailing list or
Most of the work on the specification takes place in GitHub issues, so browse there to get a good idea of what is happening, as well as past decisions.
See also OGC API - Processes - Part 3: Workflows and Chaining, "Collection Input" and "Collection Output" requirements class in particular, for how an OGC API - Coverage coverage can be the input and/or the output of an OGC API - Processes process.
The contributor understands that any contributions, if accepted by the OGC Membership, shall be incorporated into OGC API standards documents and that all copyright and intellectual property shall be vested to the OGC.
The Coverages API Standards Working Group (SWG) is the group at OGC responsible for the stewardship of the standard, but is working to do as much work in public as possible.
Pull Requests from contributors are welcomed. However, please note that by sending a Pull Request or Commit to this GitHub repository, you are agreeing to the terms in the Observer Agreement https://portal.ogc.org/files/?artifact_id=92169