Skip to content

opengeospatial/ogcapi-discrete-global-grid-systems

Repository files navigation

OGC API - Discrete Global Grid Systems

This GitHub repository contains the draft OGC API - Discrete Global Grid Systems standard, as well as supporting information.

The latest draft candidate standard can be accessed here in HTML and here in PDF.

The OpenAPI building blocks defined by the specification as well as complete bundled example API definition are available here, and can also be visualized and experimented with an example implementation with SwaggerUI here.

OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. OpenAPI can be used to describe and document the reusable API building blocks (resource paths, query parameters, responses supporting different representations such as JSON and HTML, schemas for both request payload and responses).

The OGC API family of standards is organized by resource type. OGC API - DGGS specifies an API for accessing data organised according to a Discrete Global Grid Reference System (DGGRS). A DGGRS is a spatial reference system combining a discrete global grid hierarchy (DGGH, a hierarchical tessellation of zones to partition) with a zone indexing reference system (ZIRS) to address the globe. Aditionally, to enable DGGS-optimized data encodings, a DGGRS defines a deterministic for sub-zones whose geometry is at least partially contained within a parent zone of a lower refinement level. A Discrete Global Grid System (DGGS) is an integrated system implementing one or more DGGRS together with functionality for quantization, zonal query, and interoperability. DGGS are characterized by the properties of the zone structure of their DGGHs, geo-encoding, quantization strategy and associated mathematical functions.

Overview

OGC API - DGGS provides access to data organised according to one or more Discrete Global Grid Reference System (DGGRS).

The following transportable end-point resources can be attached either to an OGC API dataset (as defined by OGC API - Common - Part 1: Core) or to an OGC API collection (as defined by OGC API - Common - Part 2: Geospatial data).

GET .../dggs

List of Discrete Global Grid Reference Systems (DGGRS)

GET .../dggs/{dggrsId}

Description of the DGGRS, providing links to the definition of the DGGRS it implements, which consists of a specific hierarchy of Discrete Global Grids, a Zone Indexing Reference System (ZIRS) and a deterministic ordering of sub-zones. The description also includes links to the data retrieval mechanism and zone query end-points. The DGGRS definition describes the parameters and structure of its DGGS and ZIRS as specified by OGC Abstract Specification Topic 21 v2.0 - Part 1 (ISO/19170-1), as well as a deterministic sub-zone order.

GET .../dggs/{dggrsId}/zones

Query the list of zones where data is available and/or match certain query criteria (e.g., a bounding box, a CQL2 filter), for a selected DGGRS, optionally specifying a particular DGGS hierarchy level (zone-level). This end-point supports a compact representation based on zone hierarchy (compact-zones=true, the default), as well a parent-zone parameter allowing to progressively explore the hierarchy to avoid potentially large responses. Implementations can support among others a simple JSON response and/or a 64-bit integer binary response.

GET .../dggs/{dggrsId}/zones/{zoneId}

Information about a specific zone for a specific DGGRS, such as its geometry and area.

GET .../dggs/{dggrsId}/zones/{zoneId}/data

Retrieve the data for a specific zone of a particular DGGRS, at a resolution corresponding to the DGGS hierarchy level of that zone, in one or more available data packet encodings. Typically, the data packet would include values for descendent zones at a number of levels deeper than the requested zone's level (zone-depth parameter), as opposed to a single value for the requested zone. See the DGGS-JSON schema in particular as well as the associated UB-JSON encoding requirement class.

Server and client implementations

Overview of tools implementing OGC API - DGGS

Communication

Join the SWG mailing list (Private) or the DWG mailing list (Public).

Most of all 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.

Additional information

The draft OGC API - DGGS standard references the OGC Abstract Specification Topic 21 v2.0 - Part 1 (ISO/19170-1).

Building

Document Initialisation and Compilation instructions are here.

The contributor understands that any contributions, if accepted by the OGC Membership and ISO/TC 211, shall be incorporated into OGC and ISO/TC 211 Standards documents and that all copyright and intellectual property shall be vested to the OGC.

The Discrete Global Grid Systems (DGGS) 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