Open Geospatial Consortium (OGC) DGGS Data Retrieval API

openapi: 3.2.0
info:
  version: '1.0'
  title: OGC API - Discrete Global Grid Systems DGGS Data Retrieval 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 Data Retrieval
paths:
  /dggs/{dggrsId}/zones/{zoneId}/data:
    get:
      tags:
      - DGGS Data Retrieval
      summary: Retrieve data from a DGGRS Zone. For a DGGRS defining a sub-zone order, optimized zone data packets such as DGGS-(UB)JSON for raster data, or DGGS-(UB)JSON-FG for vector data can be used.
      operationId: .dataset.getDGGRSZoneData
      parameters:
      - $ref: '#/components/parameters/dggrsId'
      - $ref: '#/components/parameters/zoneId'
      - $ref: '#/components/parameters/collections'
      - $ref: '#/components/parameters/f-zoneData'
      - $ref: '#/components/parameters/properties'
      - $ref: '#/components/parameters/exclude-properties'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/geometry'
      - $ref: '#/components/parameters/profile'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/zone-depth'
      - $ref: '#/components/parameters/values-offset'
      - $ref: '#/components/parameters/values-scale'
      responses:
        '200':
          $ref: '#/components/responses/ZoneData'
        '204':
          $ref: '#/components/responses/EmptyData'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
  /collections/{collectionId}/dggs/{dggrsId}/zones/{zoneId}/data:
    get:
      tags:
      - DGGS Data Retrieval
      summary: Retrieve data from a DGGRS Zone for a specific collection. For a DGGRS defining a sub-zone order, optimized zone data packets such as DGGS-(UB)JSON for raster data, or DGGS-(UB)JSON-FG for vector data can be used.
      operationId: .collection.getDGGRSZoneData
      parameters:
      - $ref: '#/components/parameters/dggrsId'
      - $ref: '#/components/parameters/zoneId'
      - $ref: '#/components/parameters/collectionId-all'
      - $ref: '#/components/parameters/f-zoneData'
      - $ref: '#/components/parameters/properties'
      - $ref: '#/components/parameters/exclude-properties'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/geometry'
      - $ref: '#/components/parameters/profile'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/zone-depth'
      - $ref: '#/components/parameters/values-offset'
      - $ref: '#/components/parameters/values-scale'
      responses:
        '200':
          $ref: '#/components/responses/ZoneData'
        '204':
          $ref: '#/components/responses/EmptyData'
        '404':
          $ref: '#/components/responses/NotFound'
        '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'
    properties:
      name: properties
      in: query
      description: 'Select specific data record fields (measured/observed properties) to be returned using a comma-separated list of field names.

        The field name must be one of the fields defined in the associated data resource''s logical schema.


        Extensions may enable the use of complex expressions to support defining derived fields, potentially also

        including the possibility to use aggregation functons.'
      required: false
      schema:
        type: string
    values-scale:
      name: values-scale
      in: query
      description: 'Specify the scale factor for a zone data output format such as PNG not supporting floating-point, to be applied before adding an offset and resulting in the encoded integer values (e.g., 8-bit or 16-bit unsigned for PNG).

        '
      style: form
      explode: false
      required: false
      schema:
        type: number
    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
    zone-depth:
      name: zone-depth
      in: query
      description: "The DGGS resolution levels beyond the requested DGGS zone’s hierarchy level to include in the response, when retrieving data for that zone. This can be either: • A single positive integer value — representing a specific zone depth to return (e.g., `zone-depth=5`); • A range of positive integer values in the form “{low}-{high}” — representing a\n  continuous range of zone depths to return (e.g., `zone-depth=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., `zone-depth=1,3,7`). Some or all of\n  these forms of the zone-depth parameter may not be supported with particular\n  data packet encodings (the data encoding may support a fixed depth, a range of\n  depths, and/or an arbitrary selection of depths).\nWhen this parameter is omitted, the default value specified in the `defaultDepth` property of the `.../dggs/{dggrsId}` DGGRS description is used."
      required: false
      schema:
        oneOf:
        - type: integer
          minimum: 0
        - type: string
          description: A comma separated list of positive integers, or a {min}-{max} range of relative zone depths
      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'
    values-offset:
      name: values-offset
      in: query
      description: 'Specify the offset for a zone data output format such as PNG not supporting floating-point, to be applied after multiplying by the scale factor and resulting in the encoded integer values (e.g., 8-bit or 16-bit unsigned for PNG).

        '
      style: form
      explode: false
      required: false
      schema:
        type: number
    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
    dggrsId:
      name: dggrsId
      in: path
      description: Identifier for a supported Discrete Global Grid System
      required: true
      allowEmptyValue: false
      schema:
        $ref: '#/components/schemas/all-dggrs'
    exclude-properties:
      name: exclude-properties
      in: query
      description: 'Exclude specific data record fields (measured/observed properties) from being returned using a comma-separated list of field names.

        The field name must be one of the fields defined in the associated data resource''s logical schema.'
      required: false
      schema:
        type: string
    f-zoneData:
      name: f
      in: query
      description: The format of the zone data response (e.g. GeoJSON, GeoTIFF).
      required: false
      schema:
        type: string
        enum:
        - json
        - geotiff
        - geojson
        - png
      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
    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
  responses:
    ZoneData:
      description: DGGRS zone data returned as a response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/dggs-json'
        image/png:
          schema:
            type: string
            format: binary
        image/tiff; application=geotiff:
          schema:
            type: string
            format: binary
        application/geo+json:
          schema:
            allOf:
            - format: geojson-feature-collection
            - $ref: '#/components/schemas/FeatureCollection'
    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
    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
    EmptyData:
      description: No data available for this zone.
  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
    dggs-json:
      type: object
      properties:
        dggrs:
          type: string
          format: uri
        zoneId:
          type: string
        depths:
          type: array
          items:
            type: integer
            minimum: 0
        schema:
          description: Attributes of the features or fields of a coverage range. Defined by a subset of the JSON Schema for the properties of a feature
          type: object
          required:
          - type
          - properties
          properties:
            type:
              type: string
              enum:
              - object
            required:
              type: array
              minItems: 1
              items:
                type: string
            properties:
              type: object
              default: {}
              additionalProperties:
                type: object
                properties:
                  title:
                    type: string
                  description:
                    type: string
                  type:
                    type: string
                    enum:
                    - array
                    - boolean
                    - integer
                    - 'null'
                    - number
                    - object
                    - string
                  enum:
                    type: array
                    minItems: 1
                    items: {}
                    uniqueItems: true
                  format:
                    type: string
                  contentMediaType:
                    type: string
                  maximum:
                    type: number
                  exclusiveMaximum:
                    type: number
                  minimum:
                    type: number
                  exclusiveMinimum:
                    type: number
                  pattern:
                    type: string
                    format: regex
                  maxItems:
                    type: integer
                    minimum: 0
                  minItems:
                    type: integer
                    default: 0
                    minimum: 0
                  x-ogc-definition:
                    type: string
                    format: uri
                  x-ogc-unit:
                    type: string
                  x-ogc-unitLang:
                    type: string
        dimensions:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              definition:
                type: string
                format: uri
              unit:
                type: string
              unitLang:
                type: string
                format: uri
              grid:
                type: object
                required:
                - cellsCount
                oneOf:
                - required:
                  - resolution
                  - firstCoordinate
                - required:
                  - coordinates
                properties:
                  cellsCount:
                    type: integer
                  resolution:
                    oneOf:
                    - type: number
                    - type: string
                  relativeBounds:
                    type: array
                    minItems: 2
                    maxItems: 2
                    items:
                      oneOf:
                      - type: number
                      - type: string
                  coordinates:
                    type: array
                    items:
                      oneOf:
                      - type: number
                      - type: string
                  boundsCoordinates:
                    type: array
                    items:
                      type: array
                      minItems: 2
                      maxItems: 2
                      items:
                        oneOf:
                        - type:
                          - number
                          - 'null'
                        - type:
                          - string
                          - 'null'
                  firstCoordinate:
                    oneOf:
                    - type: number
                    - type: string
              interval:
                type: array
                minItems: 2
                maxItems: 2
                items:
                  oneOf:
                  - type:
                    - number
                    - 'null'
                  - type:
                    - string
                    - 'null'
            required:
            - name
            - interval
            - grid
        values:
          additionalProperties:
            type: array
            items:
              type: object
              required:
              - data
              properties:
                depth:
                  type: integer
                shape:
                  type: object
                  properties:
                    count:
                      type: integer
                    subZones:
                      type: integer
                    dimensions:
                      type: object
                      additionalProperties:
                        type: integer
                  required:
                  - count
                  - subZones
                data:
                  type: array
                  items:
                    type:
                    - number
                    - 'null'
      required:
      - dggrs
      - zoneId
      - depths
      - values
    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