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