Open Geospatial Consortium (OGC) DGGRS Description API

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