In the interest of readability, the following terms will be used as shorthand for more complex text:

• Profile: A Profile is a standard or specification which restricts and/or extends an existing standard. This standard defines the rules for creating a profile of the OGC API — Environmental Data Retrieval Standard. The term “Profile” will be used in this document as shorthand for “profile of the OGC API — Environmental Data Retrieval Standard”.

• OGC API-EDR: The term OGC API-EDR will be used in this document as shorthand for the term “OGC API — Environmental Data Retrieval Standard”

Path = {root}/

Dependencies

• OGC API — Common — Part 1: Core

• OGC API — Environmental Data Retrieval Standard

The landing page provides links that support exploration of the resources offered via the API. The most important component of a landing page is a list of links. The Landing Page resource is initially defined in the Core conformance class of the OGC API — Common — Part 1 Standard. The OGC API — Environmental Data Retrieval Standard does not make any changes to this definition.

The normative JSON Schema for an EDR Landing Page is defined in the LandingPage.yaml document. While this schema provides a rich body of information about the API, only the Links property is required.

Profiles of the OGC API — Environmental Data Retrieval Standard are expected to provide a richer description of the API. The additional content that Profiles should mandate is defined in the following requirements.

Path = {root}/api

Dependencies

• OGC API — Common — Part 1: Core

• OGC API — Environmental Data Retrieval Standard

Every API is required to provide a definition document that describes the capabilities of that API. This definition document can be used by developers to understand the API, by software clients to connect to the server, or by development tools to support the implementation of servers and clients. The API Definition resource is initially defined in the Core conformance class of the OGC API — Common — Part 1 Standard. The OGC API — Environmental Data Retrieval Standard Standard does not make any changes to this definition.

Profiles of the OGC API — Environmental Data Retrieval Standard are required to provide an OpenAPI 3.1 document. This document extends the API definition provided by the OGC API-EDR Standard. These extensions reflect the additional requirements added by the Profile. Implementors of the profile will then build on that document to produce the API definition document for their implementation.

At this time only OpenAPI 3.0 and OpenAPI 3.1 documents are supported by OGC Web API Standards.

Path = {root}/conformance

Dependencies

• OGC API — Common — Part 1: Core

• OGC API — Environmental Data Retrieval Standard

To support “generic” clients that want to access implementations of multiple OGC API Standards and extensions — and not “just” a specific API server, the API has to declare the conformance classes it claims to have implemented. The Conformance Classes resource is initially defined in the Core conformance class of the OGC API — Common — Part 1 Standard. The OGC API — Environmental Data Retrieval Standard does not make any changes to this definition.

Profiles of the OGC API — Environmental Data Retrieval Standard have additional requirements governing which Conformance Classes and identifiers must be included in this resource.

OGC API implementations typically organize their geospatial resources into collections. Information about those Collections is accessed through the /collections path and the link relation.

Path = {root}/collections

Dependencies

• OGC API — Common — Part 2: Geospatial Data

• OGC API — Environmental Data Retrieval Standard

The Collections resource is initially defined in the Collections conformance class of the OGC API — Common — Part 2 Standard. The OGC API — Environmental Data Retrieval Standard Standard does not make any changes to this definition.

An API may support multiple collections. Additional requirements address how the Profile should document requirements at the per-collection level as well as on the landing page (where appropriate)

A service may consist of multiple Collections. While there may be common rules for all Collections, a profile should be able to support different rules depending on the Collection.

Each resource Collection is described by a set of metadata. That metadata can be accessed directly using the /collections/{collectionId} path and as an entry in the Collections property of the /collections response.

Path:

• {root}/collections (returns metadata for every Collection)

• {root}/collections/{collectionId} (returns metadata for the specified Collection)

Dependencies

• OGC API — Common — Part 2: Geospatial Data

• OGC API — Environmental Data Retrieval Standard

The following parameters are supported by all OGC API-EDR queries.

The Area query returns data within the polygon defined by the coords parameter. Logic for identifying the best match for the requested area will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/area

Dependencies: OGC API — Environmental Data Retrieval Standard

The Corridor query returns data along and around the path defined by the coords parameter. Logic for identifying the best match for the requested corridor will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/corridor

Dependencies: OGC API — Environmental Data Retrieval Standard

The Cube query returns a data cube defined by the bbox and z parameters.

Path = {root}/collections/{collectionId}/cube

Dependencies: OGC API — Environmental Data Retrieval Standard

The Locations query returns data for the named location. Logic for identifying the best match for the coordinate will depend on the Collection and is at the discretion of the query service implementer. If a location id is not defined the API SHALL return a GeoJSON features array of valid location identifiers, the schema of the GeoJSON response SHOULD be defined in the OpenAPI definition of the EDR service.

Path = {root}/collections/{collectionId}/locations

Dependencies: OGC API — Environmental Data Retrieval Standard

Having multiple versions or Instances of the same Collection, where the same information is reprocessed or regenerated is not unusal. Although these versions could be described as new Collections the Instance query type allows this data to be described as different views of the same Collection.

Path = {root}/collections/{collectionId}/instances

Dependencies: OGC API — Environmental Data Retrieval Standard

Paths: * {root}/collections/{collectionId}/items * {root}/collections/{collectionId}/items/{itemid}

Dependencies

• GC API — Features — Part 1: Core

• OGC API — Environmental Data Retrieval Standard

The EDR API Items query is like an OGC API — Features Part 1: Core endpoint. It offers some basic compatibility with API-Features for convenience. It may be used to catalog pre-existing EDR sampling features. The pre-existence of an EDR sampling feature may be because a particular query has been cached for later use, such as a monitoring location. Or there may be a catalog of spatio-temporal sampling features such as domains of anomalies in a dataset. A GeoJSON-compatible JSON-Schema is specified to document an EDR API query endpoint and valid query parameters including time range, parameters, and spatial characteristics. A service can define a custom GeoJSON schema in the OpenAPI definition for the service, with the default being the edr-geojson schema if no alternative is documented.

The Position query returns data for the requested coordinate. Logic for identifying the best match for the coordinate will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/positions

Dependencies: OGC API — Environmental Data Retrieval Standard

The Radius query returns data within the defined radius of the requested coordinate.

Path = {root}/collections/{collectionId}/radius

Dependencies: OGC API — Environmental Data Retrieval Standard

The Trajectory query returns data along the path defined by the coords parameter. Logic for identifying the best matches for the requested trajectory will depend on the Collection and is at the discretion of the query service implementer.

Path = {root}/collections/{collectionId}/trajectory

Dependencies: OGC API — Environmental Data Retrieval Standard

HTTP response

• Response status codes

• Response links

While Web protocols typically use request-response operations, there is also support for asychonous operations.

HTTP Asynchrouous — This requirement address the use of HTTP asynchronous operations such as Webhooks and Callbacks.

Publish-Subscribe — This requirement addresses the use of Publish-Subscribe protocols. These are protocols supported in addition to HTTP.