Demystifying OGC APIs with GeoServer: introduction and status of implementation Ing. Andrea Aime GeoSolutions 1

GeoSolutions Enterprise Support Services Deployment Subscription Professional Training Customized Solutions GeoNode • Offices in Italy & US, Global Clients/Team • 30+ collaborators, 25+ Engineers • Our products • Our Offer 2

Affiliations We strongly support Open Source, it Is in our core We actively participate in OGC working groups and get funded to advance new open standards We support standards critical to GEOINT 3

OGC API - Common elements 4

OGC APIs - OpenAPI • Fresh take on spatial data interoperability • Based on OpenAPI/RESTful concepts • Resource/representation • HTTP verbs • Small core, a basic service can be implemented in a matter of days • Extensions for every other functionality 5

OGC API (OAPI) Common • Can be found at: https://github.com/opengeospatial/oapi_common • Resources: • / (landing page) • /conformance (conformance classes implemented) • For services exposing data: • /collections • /collection/{collectionId} • OpenAPI definition linked from landing page with rel service-desc 6

Links, links everywhere! • All resources are linked to the others, in the various encodings: /collections /collections/{collectionId} Backlinks to self and alternative representations (different formats/encodings) Links to each collection in each of its formats { "href":"http://data.example.org/collections.json", "rel":"self", "type":"application/json", "title":"this document" } 7

Resource representations • OAPI Commons recommends: ○ HTML for humans and crawlers ○ JSON for machine to machine • Choose: ○ Accept header ○ Custom query param (“f” is a common choice) 8

Extensions and conformance • Tiny core, bare minimum for a working service • Modular extensions for everything else • Find what is supported using conformance declaration 9

GeoServer implementation, common bits 10

One service per API • The current GeoServer implementation has one separate service per API • Matches 1-1 classic OGC services • Each OGC API is built on top of the classic OGC service engine (found in GeoServer core) • An implementation of a uber-service with all blocks together is possible, but not trivial, since each service is a pluggable module in GeoServer (can be pulled away at any time) OGC API - Features WFS 1.1 Features services engine WFS 1.0 WFS 2.0 11

Mimic classic OGC service • Same output formats as classic OGC service ○ e.g., can extract zipped shapefile out of OGC API - Features • Similar vendor extensions ○ e.g. can filter using Extended CQL ○ but some vendor extensions are not yet exposed (e.g., filtering mosaic images via CQL like in WCS) • Integrate same basic functionality ○ Authentication and authorization supported out of the box ○ Monitoring and control-flow similarly supported 12

HTML Resource representations • HTML representation is controlled by templates, fully user customizable • Example, collections page, vanilla: 13

Customizable links • Configurable links for services and collections • Examples: license, metadata, enclosure, INSPIRE tags, human readable description of the data set or collection 14

OGC API - Features 15

Features API Core • In addition to OAPI core: • /collection/{collectionId}/items • /collection/{collectionId}/items/{itemId} • Only supported CRS are • CRS84 (WGS84 lon/lat) • CRS84h (WGS84 lon/lat/height) • Schema not required, features can be anything: • Simple • Complex • Heterogeneous • “describeBy” can link to schema (optional) 16

OpenAPI definition 17

/collection/{collectionId}/items • Lists the contents of a collection • Can be a GeoJSON document, GML, anything • Filtering • bbox in CRS84 or CRS84h • datetime (instant or range of times) • extra parameters declared in the API document (only by equality, not supported by GS) …/collections/buildings/items? bbox=41,54,42,55 &datetime=2018-02-12T23%3A20%3A52Z &buildingState=good 18

Paging • limit query parameter (first page) • A limit is always present (server default) • Paging works through links, "prev" and "next" rel values [ { "href":"http://example.org/collections/buildings/items.json?limit:50", "rel":"prev", "type":"application/geo+json" }, { "href":"http://example.org/collections/buildings/items.json?limit:50&offset:50", "rel":"self", "type":"application/geo+json" }, { "href":"http://example.org/collections/buildings/items.json?limit:50&offset:100", "rel":"next", "type":"application/geo+json" } ] 19

CITE compliance • GeoServer 2.24.x nightly builds are passing OGC API - Features compliance tests 20

Part 2 - CRS by Reference • OGC API - Features, part 2, Coordinate Reference Systems by Reference • Info about storage CRS • BBOX with CRS • Output reprojection • CRS information as a response header (does not rely on format native ability) • Compliant, CITE tests pass { "crs": [ "http://www.opengis.net/def/crs/OGC/1.3/CRS84", "http://www.opengis.net/def/crs/EPSG/0/4326", "http://www.opengis.net/def/crs/EPSG/0/3857" ], "storageCrs": "http://www.opengis.net/def/crs/EPSG/0/26713" } 21

Part 3 - Filtering (draft) ● Queryables: properties that can be used for filtering ○ May be a sub-set of the actual attributes ○ May not even match the attributes (e..g, like “anyText” in CSW) ● filter: the filter specification ● filter-lang: the language used ● filter-crs: the CRS for the geometries used in the filter ● cql2-text, cql2-json ● GeoServer supports also ecql-text (classic GeoServer extended CQL) 22

CQL2 encodings (earlier draft) eo:cloud_cover BETWEEN 0.1 AND 0.2 AND landsat:wrs_row=28 AND landsat:wrs_path=203 { "and": [ { "between": [ {"property": "eo:cloud_cover"}, 0.1, 0.2 ] }, { "=": [{"property": "landsat:wrs_row"},28] }, { "=": [{"property": "landsat:wrs_path"},203] } ] } &filter-lang=cql2-text &filter-lang=cql2-json 23

Sorting ● Not part of OGC API - Features ● Discussed in issue 157 ● Syntax borrowed from OGC API - Records /items?sortby=name,-dateOfBirth 24

STAC API 25

STAC API (RC1) ● Spatio Temporal Asset Catalog ● Search engine for “assets” in space and time ● Typical asset: satellite imagery ● GS implementation, compatible with OGC API - Features 26

GeoServer implementation structure Collection Item Granule STAC STAC Maps e.g. Sentinel 2 e.g. specific Sentinel 2 scene Band 12 of the scene 27

Customization example by DLR 28

OGC API - Coverages 29

OGC APIs - Coverages • The simplest WCS ever? • Collection as a single coverage • Partial implementation from code sprint 30

Coverage extraction • Core allows to extract data from a coverage by: • bbox • datetime • Scaling available too but not implemented yet ...collections/nurc:Img_Sample/coverage? f=image%2Fpng& bbox=-130,20,-100,40 or &subset=Lat(20:40),Long(-90:-70) 31

OGC API - Maps 32

OGC API - Maps • Draft specification available (GeoServer implements earlier version) • Partial implementation from code sprint • Building block to produce maps, can be attached to collections, but in general, to any resource that can be mapped • E.g., could be a OGC API - process result, that has a “map” sub-resource 33

Maps API • Adds a notion of a “style”, listed in collection metadata • Adds a “maps” resource 34

“map” resource • Fetches a map in the requested format • Params: width, height, bbox, crs, …. • Unlike WMS GetMap, all params are optional → similar to the GeoServer WMS reflector .../ogc/maps/v1 /collections/topp:states/styles/population/map?f=image/png 35

“info” resource (GS specific) • Not part of the standard (used to be in a previous draft) • Still useful (considers scale deps, filters, symbology) • Feature info at given location • Params: “i/j” mandatory, others same as “map” .../ogc/maps/v1/ collections/topp:states/styles/population/map/info? f=text/plain&i=50&j=10 Results for FeatureType 'http://www.openplans.org/topp:states': -------------------------------------------- the_geom = [GEOMETRY (MultiPolygon) with 276 points] STATE_NAME = Washington STATE_FIPS = 53 SUB_REGION = Pacific STATE_ABBR = WA LAND_KM = 172447.205 WATER_KM = 12226.63 PERSONS = 4866692.0 FAMILIES = 1264934.0 HOUSHOLD = 1872431.0 MALE = 2413747.0 FEMALE = 2452945.0 WORKERS = 1830031.0 DRVALONE = 1700872.0 CARPOOL = 282240.0 PUBTRANS = 104403.0 EMPLOYED = 2293961.0 UNEMPLOY = 139216.0 -------------------------------------------- 36

OGC API - Tiles 37

OGC API - Tiles building block • Finalized specification https://docs.ogc.org/is/20-057/20-057.html • Full implementation based on earlier draft • Adds resources for tiles, tile matrix sets, eventually styles 38

Building block, can tile “anything” ● /collections/{collectionId} 🡪 data tiles from single collection ● /collections/{collectionId}/maps 🡪 rendered tiles from single map ● /collections 🡪 raw tiles from multiple collections (list of collections as query param) ● /map 🡪 tiles from multi-layer map (list of collections as query param) ● /add/your/own/here 🡪 if it can be sliced, API Tiles can expose it 39

Tiles resource, URL templates ogc/tiles/collections/topp%3Astates/styles/population/map/tiles/ WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}?f=image%2Fpng 40

Tiles “metadata” resource ● Extension provided by some implementations (not core) ● Describes the tiles contents ● Can return TileJSON (GeoServer does) { "tilejson": "2.2.0", "name": "topp:states" , "description" : "This is some census data on the states." , "scheme": "xyz", "tiles": [ ".../ogc/tiles/collections/topp%3Astates/tiles/WebMercatorQuad/{z}/{y}/{x}?f=mvt ], "center": [ -89.99999997494392 , 42.525564403512014 , 1.0 ], "bounds": [-124.731422 , 24.955967, -66.969849, 49.371735 ], "format": "application/vnd.mapbox-vector-tile" , "minzoom": 0, "maxzoom": 24, "vector_layers" : [ { "id": "states", "description" : "This is some census data on the states." , "fields": { "STATE_NAME" : "string", "STATE_FIPS" : "string", "HOUSHOLD": "number" ... 41

Other APIs 42

OGC API - Styles • Building block to describe styles for a resource • In GeoServer a stand-alone API • Implements early draft. Specification is slow moving. 43

OGC API - Styles - example Basic metadata info (yeah, I did not fill it yet, no love lost for metadata!) Access to style source, native (CSS) and converted (SLD) when possible List of layers involved in the style (could have many) and attributes used in each (style editor can use them to check compatibility with available data) The style identifier 44

DGGS related APIs • Discrete Global Grid System • A way to describe position and accuracy as a hierarchical pyramid of cells rHealPix (equal area) H3 (equal distance) 45

DGGS related APIs • Access to zones, neighbours, children, mapping to point/polygons • DAPA style aggregation API: aggregate over area, time, or both 46

Moving forward 47

Next steps - code • Move from community module to extension • At least for Features • Waiting CQL2 and its implementation • Complete outdated/partial implementations • Tiles • Coverages • Maps • More extensions • Features: property selection, transactions • More APIs • processes • records 48

Next steps - users/deploys • Hopefully get more uptake/usage • Currently few deployments (research institutes) • More hybrid deployments (both classic services and OGC APIs) • More front-end support (e.g., MapStore) • Overall hopefully more business around it 49

That’s all folks! Questions? info@geo-solutions.it 50