Suggestions from Fuhu's Team - Suggestion 2 - neighbours operation for zone query

[geofizzydrink]

Based on the document, there are parent, child, and sibling operations in ZoneQuery, but we failed to find the ‘neighbors’ operation, which is finding the neighbors of zone. We indeed find end-point /collections/{collectionId}/neighbors in the Testbed-16 document, and it gets the neighboring zones to one given zone. We think /dggs/{dggsID}/zones/{zoneID}neighbors might be more suitable with query parameters the number of neighbors. For GeoSOT 2D zones (quadrilateral), their neighbors are zones with common edges or vertices and edges, which means the number of neighbors can be 4 or 8; for 3-dimensional zones, they will have 6, 18, or 26 neighbors differentiated by common vertices, edges, and faces. This is our preliminary idea which takes the number of neighbors as query parameter, please don’t hesitate to propose better opinions.

[jerstlouis]

This still fits in the "demonstration / educational" category since it is not an operation that needs to cross the client-server category in a practical use of the API.

However, like zone geometry, OGC API - DGGS - Part 1: Core could include a recommendation to include this in the zone information.
While it could be at /dggs/{dggsID}/zones/{zoneID}/neighbors, because it would be a very small numbers of neighbors as an array of ID strings, it could be included directly as a property of the zone information. We could define the geometry, parent, children, sibling and neighbors as properties of the zone information.

A remaining question is whether we will find any non-demosntration / educational use of the zone information in a practical client/server setting. I am thinking for example of data aggregation summary for the zone -- should the resource be used for this, or should that be done with /data?

We could decide to keep /dggs/{dggsID}/zones/{zoneID} for basic demonstration / education / information only and keep it as a recommendation only to implement.

[AkexStar]

@jerstlouis
I'm a member of Fuhu's team. I think your suggestion is very enlightening.
Do you mean we just put the zone's geometry, parent, children, siblings, neighbors and other zonal information in /dggs/{dggsID}/zones/{zoneID}, which you call it zone geometry in #64.

However, the zone geometry fits nicely being included in the "Zone Information" resource, which I think we could define in OGC API - DGGS Core, possibly as a recommendation.

Like your GNOSIS shows:
https://maps.gnosis.earth/ogcapi/dggs/GNOSISGlobalGrid/zones/1-0-2

[jerstlouis]

@AkexStar Yes, it could all be included in the zone information response (but by geometry, I did mean specifically the geometry).

Currently in the JSON response all we include is links, id, and areaMetersSquare:

https://maps.gnosis.earth/ogcapi/collections/sentinel2-l2a/dggs/GNOSISGlobalGrid/zones/0-0-0?f=json

But we could also have parent, children, neighbors, sibling, and geometry.
We do return geometry if negotiating a GeoJSON response:

https://maps.gnosis.earth/ogcapi/collections/sentinel2-l2a/dggs/GNOSISGlobalGrid/zones/0-0-0?f=geojson

in which case it is the only thing returned (we could potentially include the other things as GeoJSON properties as well).

My suggestion is that we define all of those properties either in recommendations of the Core requirements class, or in a separate requirements class.

A practical scenario client would not really use this, but an educational DGGS demonstration / explorer-type client might.

[jerstlouis]

We also support returning the zone geometry for the representation of Zones query when negotiating GeoJSON (or GeoTIFF), for example you can visualize the grid directly in GeoJSON.io by selecting a zone-level and turning off compact-zones (so that they're not always replaced by level 0 zones):

Level 0: http://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D0%26compact-zones%3Dfalse

Level 1: http://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D1%26compact-zones%3Dfalse

Level 2: http://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D2%26compact-zones%3Dfalse

Level 3: http://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D3%26compact-zones%3Dfalse

Level 4: http://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D4%26compact-zones%3Dfalse

You can also do this for a specific collection to get only the zones for that collection:

https://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D4%26compact-zones%3Dfalse

Or include a CQL2 filter (Elevation > 3000 here):

https://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D6%26compact-zones%3Dfalse%26filter%3DElevation%3E3000

Or with compact-zones true and level 8:

https://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D8%26compact-zones%3Dtrue%26filter%3DElevation%3E3000

[AkexStar]

@jerstlouis Thanks for your demonstration! I've also recently been considering revising our APIs draft.
I also think the document(OGC API - DGGS - Part 1: Core) should be modified to make it more clear.

And I have a suggestion(maybe a question) to your GeoJSON, such as bellow:

https://geojson.io/#data=data:text/x-url,https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones.geojson%3Fzone-level%3D8%26compact-zones%3Dtrue%26filter%3DElevation%3E3000

    {
      "type": "Feature",
      "id": 678,
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              92.8125,
              36.5625
            ],
            [
              93.1640625,
              36.5625
            ],
            [
              93.1640625,
              36.9140625
            ],
            [
              92.8125,
              36.9140625
            ],
            [
              92.8125,
              36.5625
            ]
          ]
        ]
      },
      "properties": {
        "feature::id": 678
      }
    }

The feature::id of each zone's properties is only a serial-number(Ordinal). Where is the ZoneID?
According to my understanding, ZoneID is the identity-card number of each zone.

[jerstlouis]

@AkexStar The "id" (and the feature::id) are only the internal feature ID.
You are right that ideally an implementation should include a zoneID property in the GeoJSON representation, so that one could easily query the zoneID from that GeoJSON output.
In fact we did plan to add this, just did not get around to it yet.

But again I point out that this "GeoJSON" output mode of zones is purely for educational / demonstration purposes.
A practical application of OGC API - DGGS "Zones Query" would never use this.
Instead they would use something like our binary output:
https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones?zone-level=8&compact-zones=true&filter=Elevation%3E3000&f=uint64
which is 10.9 kb (2.1kb LZMA-compressed) instead of 464 kb (25.4kb compressed).

or slightly less compact, but avoiding a custom binary encoding, simply JSON IDs:

https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones?zone-level=8&compact-zones=true&filter=Elevation%3E3000&f=json
which is 17.3 kb (2.5 kb compressed).

Those are the formats that could actually be used in practice, and provide a compact way to exchange / return an area of interest either to a DGGS client performing a Where is it? type query, or between two servers as part of a complex DGGS integration / processing chain, using the same grid.