The OGC API - Environmental Data Retrieval (EDR) standards define lightweight query interfaces for retrieving spatio-temporal data. A client requests data at a position, within an area, along a trajectory, and so on, and gets back only the data for that query.
EDR is part of the OGC API family of standards, which define modular API building blocks to spatially enable Web APIs in a consistent way. The building blocks are defined using OpenAPI.
This repository is where the OGC EDR API Standards Working Group (SWG) develops and maintains the EDR standards.
| Part | Latest version | Status | OGC doc | Read |
|---|---|---|---|---|
| Part 1: Core | 1.2 | Approved standard, published 2026-09-08 | 19-086r9 | HTML · PDF |
| Part 2: Publish-Subscribe Workflow | 1.0 | Approved standard, published 2024-09-23 | 23-057r1 | HTML · PDF |
| Part 3: Service Profiles | 1.0 (draft) | Public comment open until 2026-10-21 | 25-014r1 | Draft for comment |
All published EDR documents are also listed on the OGC API - EDR standard page.
Part 1 defines the core EDR API: how a server describes its data collections, and the query patterns clients use to retrieve data from them (see Query patterns). Versions up to and including 1.2 are published as OGC API - Environmental Data Retrieval Standard. The name "Part 1: Core" is used to distinguish it from Parts 2 and 3.
Published versions
| Version | OGC doc | Published | Read |
|---|---|---|---|
| 1.2 (current) | 19-086r9 | 2026-09-08 | HTML · PDF |
| 1.1 | 19-086r6 | 2023-07-27 | HTML · PDF |
| 1.0.1 (corrigendum) | 19-086r5 | 2022-08-05 | HTML · PDF |
| 1.0 | 19-086r4 | 2021-08-13 | HTML · PDF |
Version 1.2 is backwards compatible with 1.1.
Corrigenda in preparation: some minor errors found in 1.0.1 and 1.1 were fixed in 1.2. For deployments that are not yet ready to move to 1.2, the fixes are being published as corrigenda 1.0.2 (19-086r7, branch 1.0.2) and 1.1.1 (19-086r8, branch 1.1.1).
OpenAPI definitions: the source YAML is in core/standard/openapi/. Bundled single-file versions for OpenAPI 3.0 and OpenAPI 3.1 are generated automatically in the repository root, and the 3.1 bundle can be browsed in the interactive API viewer. Official schemas for published versions are on schemas.opengis.net.
Part 2 adds an asynchronous "publish and subscribe" model for data and notifications, using AsyncAPI alongside OpenAPI. It is intended to be usable by other OGC APIs as well.
Version 1.0 (23-057r1) was published on 2024-09-23 and is available in HTML and PDF. Source: extensions/pubsub/standard/.
Part 1 was designed to be flexible and easy for Web developers to implement. As it has been widely adopted, some communities have asked to restrict that flexibility so that servers and clients within their domain work together more reliably. A set of such stricter rules for a particular community is a profile.
Part 3 defines how to specify a profile of Part 1. It covers restrictive profiles only, and the restrictions are expressed as JSON Schema fragments that can be tested formally. Like Part 2, it is intended to be usable by other OGC APIs.
Public comment is open from 2026-09-21 until 2026-10-21. Read the draft for public comment and submit comments as GitHub issues. See the OGC announcement for details.
The latest editor's draft is built from extensions/service_profiles/standard/ and published in HTML.
As with other OGC APIs that have a /collections endpoint, EDR serves collections of geospatial data. An EDR collection can hold almost any data about the natural or built environment that is best sampled with a spatio-temporal query. For example:
- A climate model or weather re-analysis accessed at a point or within a bounding rectangle.
- Gridded data such as a digital elevation model accessed along a transect.
- Observations from weather stations queried within a polygon.
- An ensemble of forecast model data accessed for a named location.
- Readings from a hydrologic sensor found spatially or accessed by identifier.
EDR aims to specify the minimum, yet sufficient, variety of metadata, query patterns and response formats to support this range of uses. Any collection of data with consistent spatio-temporal coordinates can be served, not only environmental data.
Each query pattern is optional, but an EDR API should implement at least one. Queries are made against a collection:
/collections/{collectionId}/{queryType}?
coords={wkt-geometry}&
parameter-name={parameter_1},{parameter_n}&
datetime={RFC3339/ISO8601}&
f={format}&
{queryType-specific-parameter}={value}
| Query type | Retrieves data… |
|---|---|
position |
at a point, for a time instant, as a time series, or as a vertical profile |
radius |
within a horizontal radius of a point |
area |
within a polygon |
cube |
within a 2D, 3D or 4D bounding box (a restricted case of area) |
trajectory |
along a 2D, 3D or 4D path |
corridor |
within a corridor around a trajectory |
locations |
at a location identified by name rather than coordinates |
items |
as features, by identifier; compatible with OGC API - Features - Part 1: Core. A feature can hold coordinates for a new EDR query, or be a stored query. |
instances |
from a specific version (instance) of a collection. All other query types can be used under /collections/{collectionId}/instances/{instanceId}/. |
Design goals
EDR can be considered both a "simple" API and a "convenience" API.
It is a simple API because:
- From an implementation viewpoint, the specification encourages a "core" plus "plug-in" framework;
- It does not require much domain knowledge compared to other OGC WxS and API standards;
- It uses key/value pairs;
- The metadata is based on the data being queried and is not verbose;
- The queries are fixed and predefined in the OpenAPI definition;
- The specification encourages the data publisher to publish data in fixed formats that are described within the metadata in a simple way.
It is a convenience API because:
- It complements, and works alongside, other Web-based OGC APIs;
- The query patterns allow users to get just the data they need;
- Users do not need to know the structure of the underlying data;
- It is not constrained to a particular data structure such as grids, point clouds or features;
- It hides the complexity of any underlying time structures, because queries retrieve data for the time(s) the user selects;
- It is the publisher's responsibility to simplify the output appropriately, making it convenient for the user to consume;
- Implementations are constrained by the API definition, so all implementations have the same URL structure.
EDR can also be considered a sampling API. EDR queries create discrete sampling geometries that sample a relatively persistent spatio-temporal data store. The query and its response are transient resources, which can be made persistent for re-use if required. EDR is agnostic as to whether the data store is a data cube that can be sampled anywhere, or a set of pre-existing samples or models of real-world phenomena. While the former is the emphasis, EDR APIs can also offer a list of pre-defined monitoring or modelled locations that can be accessed by identifier. EDR assumes the data store is non-sparse, so that most queries return useful values rather than "data not found".
Server and client implementations are listed in implementations/. Pull requests adding new implementations are welcome.
deployments.md is an older list of demonstration servers, many of them from the development of version 1.0.
An Executable Test Suite (ETS) lets implementations be tested, and optionally certified, as conforming to the standard. The current ETS covers versions 1.0 and 1.0.1 of Part 1. There are three ways to run it:
- On the OGC Validator.
- With Docker:
docker run -p 8081:8080 ogccite/ets-ogcapi-edr10 - From an IDE such as Eclipse or IntelliJ, using the Maven project.
Please report problems with the test suite in its issue tracker.
Implementations that pass can be submitted for certification through the OGC Compliance Program. Certified products are listed in the OGC product database.
Branches
| Branch | Contents |
|---|---|
master |
Part 1 at the latest version (currently 1.2), plus the Part 2 and Part 3 sources. Future work happens here. |
1.0.1, 1.1.0 |
Sources of the published 1.0.1 and 1.1 versions of Part 1 |
1.0.2, 1.1.1 |
Corrigenda to 1.0.1 and 1.1 in preparation |
Directories
| Path | Contents |
|---|---|
core/standard/ |
Part 1 source (Metanorma AsciiDoc) and OpenAPI definitions |
extensions/pubsub/standard/ |
Part 2 source |
extensions/service_profiles/standard/ |
Part 3 source |
*.bundled.json (root) |
Generated OpenAPI bundles. Do not edit by hand. |
implementations/ |
Server and client implementations |
ogc-web-api-guidelines/ |
OGC Web API Guidelines checklists for each version and part |
use-cases/ |
Use cases that informed the standard |
proposals/ |
Process for proposing new features |
docs/ |
SWG charter, development process notes and background material |
Building the documents: each standard directory has a Makefile that builds HTML and PDF with Metanorma. Run make all in that directory, or METANORMA_DOCKER=metanorma/mn make all to use Docker instead of a local install. See core/standard/README.adoc for details.
- Report problems or suggest changes through GitHub issues. Change requests for published standards can also be submitted through the OGC change request form.
- Meeting minutes, actions and notes are on the wiki, along with the development guidelines, comparisons with other OGC standards and longer-term future work.
- The SWG's scope and deliverables are set out in its charter. OGC members can join through the OGC Standards Working Groups page.
- To report a security vulnerability, see SECURITY.md.
| Date | Milestone |
|---|---|
| March 2020 | First virtual sprint |
| September 2020 | Public comment period on version 1.0 closed (28 September) |
| November 2020 | Second sprint (9–10 November) |
| 2021-08-13 | Version 1.0 published (19-086r4) |
| 2022-08-05 | Corrigendum 1.0.1 published (19-086r5) |
| 2023-07-27 | Version 1.1 published (19-086r6) |
| 2024-09-23 | Part 2: Publish-Subscribe Workflow 1.0 published (23-057r1) |
| 2026-09-08 | Version 1.2 published (19-086r9) |
| 2026-09-21 | Part 3: Service Profiles released for public comment |
The contributor understands that any contributions, if accepted by the OGC Membership, shall be incorporated into OGC standards documents and that all copyright and intellectual property shall be vested to the OGC.
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