Open Geospatial Consortium (OGC) DGGS Zone Query API

openapi: 3.2.0
info:
  version: '1.0'
  title: OGC API - Discrete Global Grid Systems DGGS Zone Query 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: DGGS Zone Query
paths:
  /dggs/{dggrsId}/zones:
    get:
      tags:
      - DGGS Zone Query
      summary: Retrieve the list of zones with data for this dataset, or for a particular query
      operationId: .dataset.getDGGRSZones
      parameters:
      - $ref: '#/components/parameters/collections'
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/bbox-crs'
      - $ref: '#/components/parameters/dggrsId'
      - name: zone-level
        in: query
        description: The DGGS hierarchy level at which to return the list of zones. The precision of the calculation to return the results depends on this parameter. Returned zones will have a level equal or smaller to this specified level. If `compact-zones` is set to true, all returned zones will be of this zone level. If not specified, this defaults to the most detailed zone that the system is able to return for the specific request.
        required: false
        schema:
          type: integer
        style: form
        explode: false
      - $ref: '#/components/parameters/zone-level'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/parent-zone'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/subset-crs'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/geometry'
      - $ref: '#/components/parameters/profile'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/filter-lang'
      - $ref: '#/components/parameters/f-zoneQueries'
      responses:
        '200':
          $ref: '#/components/responses/ZonesList'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
  /collections/{collectionId}/dggs/{dggrsId}/zones:
    get:
      tags:
      - DGGS Zone Query
      summary: Retrieve the list of zones with data for a specific collection, or for a particular query
      operationId: .collection.getDGGRSZones
      parameters:
      - $ref: '#/components/parameters/collectionId-all'
      - $ref: '#/components/parameters/collections'
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/bbox-crs'
      - $ref: '#/components/parameters/dggrsId'
      - $ref: '#/paths/~1dggs~1%7BdggrsId%7D~1zones/get/parameters/4'
      - $ref: '#/components/parameters/zone-level'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/parent-zone'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/subset-crs'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/geometry'
      - $ref: '#/components/parameters/profile'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/filter-lang'
      - $ref: '#/components/parameters/f-zoneQueries'
      responses:
        '200':
          $ref: '#/components/responses/ZonesList'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    geometry:
      name: geometry
      in: query
      description: 'For vector output formats, specify how to return the geometry and/or what the features of the response should represent.

        `vectorized`: return features with regular non-rasterized, non-quantized geometry

        `zone-centroid`: rasterize to zone features and use a Point geometry representing that zone centroid

        `zone-region`: rasterize to zone features and use a (Multi)Polygon/Polyhedron geometry representing that zone''s region -- not supported for DGGS-JSON-FG profiles (`profile=jsonfg-dggs*`)

        `none`: (for zone listing) omit zone geometry -- not supported for DGGS-JSON-FG profiles (`profile=jsonfg-dggs*`)'
      style: form
      explode: false
      required: false
      schema:
        type: string
        enum:
        - vectorized
        - zone-region
        - zone-centroid
        - none
    collectionId-all:
      name: collectionId
      in: path
      description: Local identifier of a collection
      required: true
      schema:
        $ref: '#/components/schemas/all-collections'
    parent-zone:
      name: parent-zone
      in: query
      description: The optional parent zone parameter restricts a zone query to only return zones within that parent zone. Used together with `zone-level`, it allows to explore the response for a large zone query in a hierarchical manner.
      required: false
      schema:
        type: string
      style: form
      explode: false
    zone-level:
      name: compact-zones
      in: query
      description: If set to true (default), when the list of DGGS zones to be returned at the requested resolution (zone-level) includes all children of a parent zone, the parent zone will be returned as a shorthand for that list of children zone. If set to false, all zones returned will be of the requested zone level.
      required: false
      schema:
        type: boolean
        default: true
      style: form
      explode: false
    offset:
      name: offset
      description: The optional offset parameter indicates the offset within the result set from which the server shall begin presenting results in the response document. The first element has an offset of 0 (default).
      explode: false
      in: query
      required: false
      schema:
        default: 0
        minimum: 0
        type: integer
      style: form
    f-zoneQueries:
      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', 'html', 'geojson', 'geotiff' or 'uint64'.
      required: false
      schema:
        type: string
        enum:
        - json
        - html
        - geojson
        - geotiff
        - png
        - uint64
      style: form
      explode: false
    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
    subset:
      name: subset
      in: query
      description: 'Retrieve only part of the data by slicing or trimming along one or more axis

        For trimming: {axisAbbrev}({low}:{high}) (preserves dimensionality)

        For slicing:  {axisAbbrev}({value})      (reduces dimensionality)

        An asterisk (`*`) can be used instead of {low} or {high} to indicate the minimum/maximum value.

        For a temporal dimension, a single asterisk can be used to indicate the high value.

        Support for `*` is required for time, but optional for spatial and other dimensions.

        '
      style: form
      explode: false
      required: false
      schema:
        type: array
        items:
          type: string
    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'
    filter:
      name: filter
      in: query
      description: The filter parameter specifies an expression in a query language (e.g. CQL2) for which an entire feature will be returned if the filter predicate is matched. The language of the filter is specified by the `filter-lang` query parameter.
      required: false
      schema:
        type: string
      style: form
      explode: false
    bbox-crs:
      name: bbox-crs
      in: query
      description: crs for the specified bbox
      required: false
      style: form
      explode: true
      schema:
        type: string
    dggrsId:
      name: dggrsId
      in: path
      description: Identifier for a supported Discrete Global Grid System
      required: true
      allowEmptyValue: false
      schema:
        $ref: '#/components/schemas/all-dggrs'
    subset-crs:
      name: subset-crs
      in: query
      description: crs for the specified subset
      required: false
      style: form
      explode: true
      schema:
        type: string
    crs:
      name: crs
      in: query
      description: reproject the output to the given crs
      required: false
      style: form
      explode: true
      schema:
        type: string
    profile:
      name: profile
      in: query
      description: 'Allows negotiating a particular profile of an output format, such as OGC Feature & Geometry JSON (JSON-FG) or DGGS-JSON-FG output when requesting an `application/geo+json` media type for zone data or zone list requests.

        For both zone data and zone lists in GeoJSON (`application/geo+json`):

        `rfc7946`: return standard GeoJSON without using any extension

        `jsonfg`: return JSON-FG representation

        `jsonfg-plus`: return JSON-FG representation with GeoJSON compatibility

        For zone data in GeoJSON (`application/geo+json`):

        `jsonfg-dggs`: return DGGS-JSON-FG representation, using `dggsPlace` to encode geometry points quantized to sub-zone, represented as local indices from 1 to the number of sub-zones corresponding to the DGGRS deterministic sub-zone order, with a special value of 0 representing an artificial node

        `jsonfg-dggs-plus`: return DGGS-JSON-FG representation, with GeoJSON compatibility `geometry`

        `jsonfg-dggs-zoneids`: return DGGS-JSON-FG representation, using `dggsPlace` to encode geometry points as textual global zone identifiers, with a special value of _null_ representing an artificial node

        `jsonfg-dggs-zoneids-plus`: return DGGS-JSON-FG representation, encoding geometry points as global zone IDs, with GeoJSON compatibility `geometry`

        For zone data in netCDF (`application/x-netcdf`):

        `netcdf3`: return NetCDF classic and 64-bit offset format (not quantized to DGGH)

        `netcdf3-dggs`: return NetCDF classic and 64-bit offset format where one axis corresponds to local sub-zone indices

        `netcdf3-dggs-zoneids`: return NetCDF classic and 64-bit offset format where one axis corresponds to the global identifiers of sub-zones (textual or 64-bit integer)

        `netcdf4`: return HFG5-based NetCDF 4 format (not quantized to DGGH)

        `netcdf4-dggs`: return HDF5-based NetCDF 4 format where one axis corresponds to local sub-zone indices

        `netcdf4-dggs-zoneids`: return HDF5-based NetCDF 4 format where one axis corresponds to the global identifiers of sub-zones (textual or 64-bit integer)

        For zone data in zipped Zarr 2.0 (`application/zarr+zip`):

        `zarr2`: return zipped Zarr 2.0 (not quantized to DGGH)

        `zarr2-dggs`: return zipped Zarr 2.0 where one axis corresponds to local sub-zone indices

        `zarr2-dggs-zoneids`: return zipped Zarr 2.0 where one axis corresponds to the global identifiers of sub-zones (textual or 64-bit integer)

        For zone data in CoverageJSON (`application/prs.coverage+json`):

        `covjson`: return CoverageJSON (not quantized to DGGH)

        `covjson-dggs`: return CoverageJSON where one axis corresponds to local sub-zone indices

        `covjson-dggs-zoneids`: return CoverageJSON where one axis corresponds to the global identifiers of sub-zones (textual or 64-bit integer)'
      style: form
      explode: false
      required: false
      schema:
        type: string
        enum:
        - rfc7946
        - jsonfg
        - jsonfg-plus
        - jsonfg-dggs
        - jsonfg-dggs-plus
        - jsonfg-dggs-zoneids
        - jsonfg-dggs-zoneids-plus
        - covjson
        - covjson-dggs
        - covjson-dggs-zoneids
        - netcdf3
        - netcdf3-dggs
        - netcdf3-dggs-zoneids
        - netcdf4
        - netcdf4-dggs
        - netcdf4-dggs-zoneids
        - zarr2
        - zarr2-dggs
        - zarr2-dggs-zoneids
    filter-lang:
      name: filter-lang
      in: query
      description: The `filter-lang` parameter specifies the query language for the `filter` query parameter.
      required: false
      schema:
        type: string
      style: form
      explode: false
    bbox:
      name: bbox
      in: query
      description: 'Only resources that have a geometry that intersects the bounding box are selected. The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (elevation or depth):

        * Lower left corner, coordinate axis 1 * Lower left corner, coordinate axis 2 * Minimum value, coordinate axis 3 (optional) * Upper right corner, coordinate axis 1 * Upper right corner, coordinate axis 2 * Maximum value, coordinate axis 3 (optional)

        If the value consists of four numbers, the coordinate reference system is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)  unless a different coordinate reference system is specified in the parameter `bbox-crs`.

        If the value consists of six numbers, the coordinate reference system is WGS 84  longitude/latitude/ellipsoidal height (http://www.opengis.net/def/crs/OGC/0/CRS84h) unless a different coordinate reference system is specified in a parameter `bbox-crs`.

        For WGS84 longitude/latitude the values are in most cases the sequence of minimum longitude, minimum latitude, maximum longitude and maximum latitude. However, in cases where the box spans the antimeridian the first value (west-most box edge) is larger than the third value (east-most box edge).

        If the vertical axis is included, the third and the sixth number are the bottom and the top of the 3-dimensional bounding box.

        If a resource has multiple spatial geometry properties, it is the decision of the server  whether only a single spatial geometry property is used to determine the extent or all relevant geometries.'
      required: false
      schema:
        type: array
        oneOf:
        - minItems: 4
          maxItems: 4
        - minItems: 6
          maxItems: 6
        items:
          type: number
      style: form
      explode: false
    limit:
      name: limit
      in: query
      description: 'The optional limit parameter limits the number of zones that are presented in the response document.

        * Minimum = 1 * Maximum = 10000 * Default = 1000'
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 1000
      style: form
      explode: false
  schemas:
    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
    FeatureCollection:
      title: GeoJSON FeatureCollection
      type: object
      required:
      - type
      - features
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            title: GeoJSON Feature
            type: object
            required:
            - type
            - properties
            - geometry
            properties:
              type:
                type: string
                enum:
                - Feature
              id:
                oneOf:
                - type: number
                - type: string
              properties:
                type:
                - object
                - 'null'
              geometry:
                oneOf:
                - title: GeoJSON Point
                  type:
                  - object
                  - 'null'
                  required:
                  - type
                  - coordinates
                  properties:
                    type:
                      type: string
                      enum:
                      - Point
                    coordinates:
                      type: array
                      minItems: 2
                      items:
                        type: number
                    bbox:
                      type: array
                      minItems: 4
                      items:
                        type: number
                - title: GeoJSON LineString
                  type: object
                  required:
                  - type
                  - coordinates
                  properties:
                    type:
                      type: string
                      enum:
                      - LineString
                    coordinates:
                      type: array
                      minItems: 2
                      items:
                        type: array
                        minItems: 2
                        items:
                          type: number
                    bbox:
                      type: array
                      minItems: 4
                      items:
                        type: number
                - title: GeoJSON Polygon
                  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
                - title: GeoJSON MultiPoint
                  type: object
                  required:
                  - type
                  - coordinates
                  properties:
                    type:
                      type: string
                      enum:
                      - MultiPoint
                    coordinates:
                      type: array
                      items:
                        type: array
                        minItems: 2
                        items:
                          type: number
                    bbox:
                      type: array
                      minItems: 4
                      items:
                        type: number
                - title: GeoJSON MultiLineString
                  type: object
                  required:
                  - type
                  - coordinates
                  properties:
                    type:
                      type: string
                      enum:
                      - MultiLineString
                    coordinates:
                      type: array
                      items:
                        type: array
                        minItems: 2
                        items:
                          type: array
                          minItems: 2
                          items:
                            type: number
                    bbox:
                      type: array
                      minItems: 4
                      items:
                        type: number
                - title: GeoJSON MultiPolygon
                  type: object
                  required:
                  - type
                  - coordinates
                  properties:
                    type:
                      type: string
                      enum:
                      - MultiPolygon
                    coordinates:
                      type: array
                      items:
                        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
        bbox:
          type: array
          minItems: 4
          items:
            type: number
    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
  responses:
    ServerError:
      description: A server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        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
    ZonesList:
      description: 'List of DGGRS Zones. In addition to a compact JSON response intended for fast DGGS client/server exchange (which should support compression),

        visual representations such as GeoTIFF and/or GeoJSON may also be supported.'
      content:
        application/json:
          schema:
            type: object
            required:
            - zones
            properties:
              zones:
                type: array
                items:
                  type: string
              returnedAreaMetersSquare:
                type: number
              returnedVolumeMetersCube:
                type: number
              returnedVolumeMetersSquareSeconds:
                type: number
              returnedHyperVolumeMetersCubeSeconds:
                type: number
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
        image/png:
          schema:
            type: string
            format: binary
        application/geo+json:
          schema:
            allOf:
            - format: geojson-feature-collection
            - $ref: '#/components/schemas/FeatureCollection'
        image/tiff; application=geotiff:
          schema:
            type: string
            format: binary
        text/html:
          schema:
            type: string