openapi: 3.2.0 info: version: '1.0' title: OGC API - Discrete Global Grid Systems DGGRS Description API description: 'Example API Definition for OGC API - DGGS - Part 1: Core' contact: name: Open Geospatial Consortium email: info@ogc.org license: name: OGC License url: http://www.opengeospatial.org/legal/ servers: - description: Example OGC API - DGGS server url: https://maps.gnosis.earth/ogcapi tags: - name: DGGRS Description paths: /dggs: get: tags: - DGGRS Description summary: Retrieve the list of available DGGRSs operationId: .dataset.getDGGRSList parameters: - $ref: '#/components/parameters/f-metadata' responses: '200': $ref: '#/components/responses/DGGSList' '406': $ref: '#/components/responses/NotAcceptable' '500': $ref: '#/components/responses/ServerError' /dggs/{dggrsId}: get: tags: - DGGRS Description summary: Retrieve the description of the specified Discrete Global Grid Reference System operationId: .dataset.getDGGRS parameters: - $ref: '#/components/parameters/dggrsId' - $ref: '#/components/parameters/f-metadata' responses: '200': $ref: '#/components/responses/DGGRS' '404': description: The requested DGGS id was not found content: application/json: schema: $ref: '#/components/schemas/exception' '406': $ref: '#/components/responses/NotAcceptable' '500': $ref: '#/components/responses/ServerError' /dggs/{dggrsId}/zones/{zoneId}: get: tags: - DGGRS Description summary: Retrieve information about a DGGRS Zone, such as geometry and data availability. operationId: .dataset.getDGGRSZoneInfo parameters: - $ref: '#/components/parameters/dggrsId' - $ref: '#/components/parameters/zoneId' - $ref: '#/components/parameters/collections' - $ref: '#/components/parameters/datetime' responses: '200': description: 'DGGRS zone information returned as a response, potentially including id, geometry, links to DGGRS (rel: dggrs), dataset, (rel: dataset), collection (rel: geodata), data (rel: dggrs-zone-data) (if available for this zone)' content: application/json: schema: $ref: '#/components/schemas/zone-info' application/geo+json: schema: allOf: - format: geojson-feature - $ref: '#/components/schemas/zone-info/properties/geometry/allOf/1' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' '500': $ref: '#/components/responses/ServerError' /collections/{collectionId}/dggs: get: tags: - DGGRS Description summary: Retrieve the list of available DGGRS for the specified collection operationId: .collection.getDGGRSList parameters: - $ref: '#/components/parameters/f-metadata' - $ref: '#/components/parameters/collectionId-all' responses: '200': $ref: '#/components/responses/DGGSList' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' '500': $ref: '#/components/responses/ServerError' /collections/{collectionId}/dggs/{dggrsId}: get: tags: - DGGRS Description summary: Retrieve the description of the specified Discrete Global Grid Reference System in the context of a specified collection operationId: .collection.getDGGRS parameters: - $ref: '#/components/parameters/dggrsId' - $ref: '#/components/parameters/f-metadata' - $ref: '#/components/parameters/collectionId-all' responses: '200': $ref: '#/components/responses/DGGRS' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' '500': $ref: '#/components/responses/ServerError' /collections/{collectionId}/dggs/{dggrsId}/zones/{zoneId}: get: tags: - DGGRS Description summary: Retrieve information about a DGGRS Zone, such as geometry and data availability, in the context of a specific collection. operationId: .collection.getDGGRSZoneInfo parameters: - $ref: '#/components/parameters/dggrsId' - $ref: '#/components/parameters/zoneId' - $ref: '#/components/parameters/collectionId-all' - $ref: '#/components/parameters/collections' - $ref: '#/components/parameters/datetime' responses: '200': $ref: '#/paths/~1dggs~1%7BdggrsId%7D~1zones~1%7BzoneId%7D/get/responses/200' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' '500': $ref: '#/components/responses/ServerError' components: schemas: zone-info: title: Information for a specific Discrete Global Grid System zone description: Zone information for a particular zone of a DGGS, including useful information such as zone geometry, data access links and statistics type: object required: - id - links properties: id: description: Zone identifier based on the DGGRS. type: string links: description: Links to related resources. A `[ogc-rel:dggrs-zone-data]` link to retrieve data for this zone and a `[ogc-rel:dggrs]` back to the `.../dggs` resource must be included. type: array items: $ref: '#/components/schemas/link' shapeType: description: The type of shape for the zone geometry (e.g., hexagon or pentagon) type: string level: description: The refinement level of this zone type: integer minimum: 0 crs: description: The Coordinate Reference System in which the geometry, centroid and bbox properties are specified type: string format: uri default: '[OGC:CRS84]' centroid: description: The centroid of the zone, in the CRS specified in crs property type: array items: type: number minItems: 2 maxItems: 3 bbox: description: The spatial envelope of the zone (bounding box), in the CRS specified in crs property type: array items: type: number minItems: 4 maxItems: 6 areaMetersSquare: description: Surface area of the zone in meters square. type: number volumeMetersCube: description: Volume of the zone in meters cube for a DGGS with three spatial dimension. type: number temporalDurationSeconds: description: Amount of time covered by the zone for a temporal DGGS. type: number geometry: description: Spatial geometry of the zone. allOf: - format: geometry-polygon - title: GeoJSON Polygon Feature type: object required: - type - properties - geometry properties: type: type: string enum: - Feature id: oneOf: - type: number - type: string properties: type: - object - 'null' geometry: title: GeoJSON Polygon geometry type: object required: - type - coordinates properties: type: type: string enum: - Polygon coordinates: type: array items: type: array minItems: 4 items: type: array minItems: 2 items: type: number bbox: type: array minItems: 4 items: type: number bbox: type: array minItems: 4 items: type: number temporalInterval: description: Sart and end time of the zone. type: array items: type: string minItems: 2 maxItems: 2 statistics: type: object description: Statistics for individual fields of the data (e.g., fields of the range of a coverage, or relevant numeric properties of a feature collection) additionalProperties: type: object properties: minimum: type: number maximum: type: number average: type: number stdDev: type: number dggrs-item: title: Discrete Global Grid Reference System description (item) description: A minimal Discrete Global Grid Reference System element for use within a list of DGGRS linking to a full description. type: object required: - id - title - links properties: id: description: Local DGGRS identifier consistent with the `{dggrsId}` parameter of `/dggs/{dggrsId}` resources. type: string title: description: Title of this Discrete Global Grid System, normally used for display to a human type: string uri: description: Identifier for this Discrete Global Grid Reference System registered with an authority. type: string format: uri links: description: Links to related resources. A `self` link to the Discrete Global Grid Reference System description and an `[ogc-rel:dggrs-definition]` link to the DGGRS definition (using the schema defined by https://schemas.opengis.net/ogcapi/dggs/1.0/core/schemas/dggrs-definition/dggrs-definition-proposed.yaml) are required. type: array items: $ref: '#/components/schemas/link' exception: title: Exception Schema description: JSON schema for exceptions based on RFC 7807 type: object required: - type properties: type: type: string title: type: string status: type: integer detail: type: string instance: type: string dggrs: title: Discrete Global Grid Reference System description description: A description of a Discrete Global Grid Reference System provided by the API. type: object required: - id - title - description - defaultDepth - links properties: id: description: Local DGGRS identifier consistent with the `{dggrsId}` parameter of `/dggs/{dggrsId}` resources. type: string title: description: Title of this Discrete Global Grid Rfeference System, intended for displaying to a human type: string description: description: Brief narrative description of this Discrete Global Grid System, normally available for display to a human type: string keywords: description: Unordered list of one or more commonly used or formalized word(s) or phrase(s) used to describe this Discrete Global Grid Reference System type: array items: type: string uri: description: Identifier for this Discrete Global Grid Reference System registered with an authority. type: string format: uri crs: allOf: - description: Coordinate Reference System (CRS) used by this DGGS (mandatory if applicable), specified as a URI if one exists. - $ref: '#/components/schemas/crs' defaultDepth: description: "The default zone depth returned for zone data retrieval when the `zone-depth` parameter is not used. This is the DGGS resolution levels beyond the requested DGGS zone’s hierarchy level included in the response, when retrieving data for a particular zone. This can be either: • A single positive integer value — representing a specific zone depth to return e.g., `5`; • A range of positive integer values in the form “{low}-{high}” — representing a\n continuous range of zone depths to return e.g., `1-8`; or,\n• A comma separated list of at least two (2) positive integer values — representing a\n set of specific zone depths to return e.g., `1,3,7`.\n A particular data encoding imply a particular zone depth and not support the default zone depth specified here,\n in which case the default zone depth (or the only possible depth) for that encoding will be used." oneOf: - type: integer minimum: 0 - type: string description: A comma separated list of positive integers, or a {min}-{max} range of relative zone depths maxRefinementLevel: type: integer minimum: 0 description: The maximum refinement level at which the full resolution of the data can be retrieved for this DGGRS and origin (using a `zone-depth` relative depth of 0) and/or used for performing the most accurate zone queries (using that value for `zone-level`) maxRelativeDepth: type: integer minimum: 0 description: The maximum relative depth at which the full resolution of the data can be retrieved for this DGGRS and origin links: description: Links to related resources. A `self` link to the Discrete Global Grid Reference System description and an `[ogc-rel:dggrs-definition]` link to the DGGRS definition (using the schema defined by https://schemas.opengis.net/ogcapi/dggs/1.0/core/schemas/dggrs-definition/dggrs-definition-proposed.yaml) are required. An `[ogc-rel:dggrs-zone-query]` link to query DGGS zones should also be included if _DGGS Zone Query_ is supported. type: array items: $ref: '#/components/schemas/link' linkTemplates: description: Templated Links to related resources. A templated `[ogc-rel:dggrs-zone-data]` link to retrieve data should be included if _DGGS Zone Data_ is supported. type: array items: type: object required: - uriTemplate - rel properties: uriTemplate: type: string description: Supplies the URL template to a remote resource (or resource fragment), with template variables surrounded by curly brackets (`{` `}`). example: http://data.example.com/buildings/{featureId} rel: type: string description: The type or semantics of the relation. example: alternate type: type: string description: A hint indicating what the media type of the result of dereferencing the link templates should be. example: application/geo+json varBase: description: A base path to retrieve semantic information about the variables used in URL template. type: string example: /ogcapi/vars/ hreflang: type: string description: A hint indicating what the language of the result of dereferencing the link should be. example: en title: type: string description: Used to label the destination of a link template such that it can be used as a human-readable identifier. example: Trierer Strasse 70, 53115 Bonn length: type: integer link: type: object required: - href - rel properties: href: type: string description: Supplies the URI to a remote resource (or resource fragment). example: http://data.example.com/buildings/123 rel: type: string description: The type or semantics of the relation. example: alternate type: type: string description: A hint indicating what the media type of the result of dereferencing the link should be. example: application/geo+json hreflang: type: string description: A hint indicating what the language of the result of dereferencing the link should be. example: en title: type: string description: Used to label the destination of a link such that it can be used as a human-readable identifier. example: Trierer Strasse 70, 53115 Bonn length: type: integer all-collections: type: string enum: - SRTM_ViewFinderPanorama - NaturalEarth:cultural:ne_10m_admin_0_countries - HRDEM-Ottawa - HRDEM-RedRiver - blueMarble - NaturalEarth:raster:HYP_HR_SR_OB_DR - NaturalEarth:physical:bathymetry all-dggrs: type: string enum: - ISEA3H - ISEA9R - GNOSISGlobalGrid - OpenEAGGR - rHEALPix - H3 - GeoSOT crs: title: CRS oneOf: - description: String representing the CRS, as a URI when possible type: string - type: object description: JSON encoding for Well-known text representation of coordinate reference systems 2.0 parameters: collectionId-all: name: collectionId in: path description: Local identifier of a collection required: true schema: $ref: '#/components/schemas/all-collections' datetime: name: datetime in: query description: 'Either a date-time or an interval. Date and time expressions adhere to RFC 3339, section 5.6. Intervals may be bounded or half-bounded (double-dots at start or end). Server implementations may or may not support times expressed using time offsets from UTC, but need to support UTC time with the notation ending with a Z. Examples: * A date-time: "2018-02-12T23:20:50Z" * A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" * Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" Only resources that have a temporal property that intersects the value of `datetime` are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.' required: false schema: type: string style: form explode: false collections: name: collections in: query style: form description: The collections that should be included in the response. The parameter value is a comma-separated list of collection identifiers. If the parameters is missing, some or all collections will be included. This parameter may be useful for dataset-wide DGGS resources, but it is not defined by OGC API - DGGS - Part 1. required: false explode: false schema: type: array items: $ref: '#/components/schemas/all-collections' dggrsId: name: dggrsId in: path description: Identifier for a supported Discrete Global Grid System required: true allowEmptyValue: false schema: $ref: '#/components/schemas/all-dggrs' f-metadata: name: f in: query description: The format of the response. If no value is provided, the accept header is used to determine the format. Accepted values are 'json' or 'html'. required: false schema: type: string enum: - json - html style: form explode: false zoneId: name: zoneId in: path description: Identifier for a specific zone of a Discrete Global Grid Systems. This identifier usually includes a component corresponding to a hierarchy level / scale / resolution, components identifying a spatial region, and a optionally a temporal component. required: true schema: type: string example: B2-1-A responses: NotFound: description: The requested resource does not exist on the server. For example, a path parameter had an incorrect value. content: application/json: schema: $ref: '#/components/schemas/exception' text/html: schema: type: string ServerError: description: A server error occurred. content: application/json: schema: $ref: '#/components/schemas/exception' text/html: schema: type: string DGGSList: description: List of available Discrete Global Grid Reference Systems. content: application/json: schema: type: object required: - dggrs properties: links: type: array items: $ref: '#/components/schemas/link' dggrs: type: array items: $ref: '#/components/schemas/dggrs-item' text/html: schema: type: string NotAcceptable: description: Content negotiation failed. For example, the `Accept` header submitted in the request did not support any of the media types supported by the server for the requested resource. content: application/json: schema: $ref: '#/components/schemas/exception' text/html: schema: type: string DGGRS: description: Description for a specific Discrete Global Grid Reference System. content: application/json: schema: $ref: '#/components/schemas/dggrs' text/html: schema: type: string