$30 off During Our Annual Pro Sale. View Details »

Demystifing OGC APIs with GeoServer: introduction and status of implementation (FOSS4G 2022 Edition)

Demystifing OGC APIs with GeoServer: introduction and status of implementation (FOSS4G 2022 Edition)

The OGC APIs are a fresh take at doing geo-spatial APIs, based on WEB API concepts and modern formats, including:

Small core with basic functionality, extra functionality provided by extensions
OpenAPI/RESTful based
JSON first, while still allowing to provide data in other formats
No mandate to publish schemas for data
Improved support for data tiles (e.g., vector tiles)
Specialized APIs in addition to general ones (e.g., DAPA vs OGC API - Processes)
Full blown services, building blocks, and ease of extensibility

This presentation will provide an introduction to various OGC APIs and extensions, such as Features, Styles, Maps and Tiles, DAPA, STAC and CQL2 filtering. 
While some have reached a final release, most are in draft: we will discuss their trajectory towards official status, as well as how good the GeoServer implementation is tracking them, and show examples based on the GeoServer HTML representation of the various resources.

Simone Giannecchini

August 31, 2022

More Decks by Simone Giannecchini

Other Decks in Technology


  1. Demystifying OGC APIs with GeoServer: introduction and status of implementation

    Ing. Andrea Aime GeoSolutions
  2. GeoSolutions Enterprise Support Services Deployment Subscription Professional Training Customized Solutions

    GeoNode • Offices in Italy & US, Global Clients/Team • 40+ collaborators, 30+ Engineers • Our products • Our Offer
  3. 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
  4. A bit of history

  5. At the beginning, there was WFS3 • First commit July

    31st 2017 • Developed in the repo for a bunch of months, then various public events shaped it into OGC API - Features WFS3 Hackaton Testbed 14 Vector Tiles Pilot Testbed 15 API Hackaton London
  6. API Hackaton, London 2018 • The same Web API approach

    as WFS3 is extended to other APIs, as well as having a shared core API Commons Features Coverages Maps & Tiles Processes Catalogs Styles More!
  7. Periodic OGC API Sprints • Since then OGC organized periodic

    code sprints • Each sprint focuses on 2-3 specs and: ◦ Push forward specification drafts ◦ Implement and gather feedback ◦ Test interoperability • GeoSolutions participates to push GeoServer API implementations forwards
  8. Up to 2022: releases and drafts • Released: ◦ OGC

    API - Features ▪ Core (Sept 2019) ▪ CRS by Reference (Oct 2020) ◦ OGC API - Environmental Data Retrieval (March 2021) ◦ OGC API - Processes (August 2021) • Most APIs and extensions are still in draft stage and changing
  9. OGC API - Common elements

  10. 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
  11. 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
  12. 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" }
  13. 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)
  14. Extensions and conformance • Tiny core, bare minimum for a

    working service • Modular extensions for everything else • Find what is supported using conformance declaration
  15. Features API Core

  16. Features API Core • In addition to OAPI core: •

    /collection/{collectionId}/items (features) • /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)
  17. OpenAPI definition

  18. /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
  19. Paging • limit query parameter • A limit is always

    present (like in WFS 1.x and 2.x) but can be high • Paging works through links, "prev" and "next" rel values • Links can be implemented the way you want • GeoServer uses offset as an extra paging parameter [ { "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" } ]
  20. CORE: that’s all folks! • Yes ladies and gentlemen, this

    is everything OGC API - Features - CORE covers
  21. Wait wait wait…. • Look that's nice, but what about….

  22. Part 2 - CRS by Reference • Support CRS other

    than CRS84 • Discover: ◦ Storage (native) CRS ◦ Supported target CRS • Parameters: ◦ bbox-crs (query) ◦ crs (reproject) • Finalized! • GeoServer currently implements older draft
  23. 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)
  24. CQL2 encodings (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
  25. CQL2 encodings support in GeoServer • Initially it was slightly

    modified CQL, quite similar to ECQL. Supported! • First round of CQL-JSON in Sept 2020 • In Sept 2021, CQL2, with significant changes ◦ cql2-text support landed Feb 2021 ◦ cql2-json parsing March 2022 ◦ cql2-json encoding June 2022 • CQL2 is still changing (last change, Aug 2nd 2022)
  26. Sorting • Not part (yet) of OGC API - Features

    • Part of “proposals” not yet turned into draft extensions • Borrowed from OGC API - Records • Available in GS 2.22 and 2.21 /items?sortby=name,-dateOfBirth
  27. Property selection • Not part (yet) of OGC API -

    Features • Not implemented in GeoServer • Part of “proposals” not yet turned into draft extensions • returnables, parallel to queryables, list properties that can be selected • properties to enumerate wanted properties • skip-geometry to avoid geometry field • STAC API has a different take: fields • Use “-” to remove a property, e.g. fields=geometry,-links,-assets&f=json
  28. Part 4 - CRUD transactions in draft • Create/Replace/Update/Delete for

    single feature • Currently in draft • Not currently supported by GeoServer .../collections/topp:states/items/states.1 POST PUT DELETE PATCH
  29. OGC Features API GeoServer HTML representations


  31. Features API /api

  32. Collections /collections

  33. Collection /collections/{collectionId}

  34. Items /collections/{collectionId}/items

  35. Coverages

  36. OGC APIs - Coverages • The simplest WCS ever? •

    Collection as a single coverage • GeoServer implementation is currently incomplete
  37. Coverage and its components • DomainSet: spatial and temporal domain

    description • RangeType: data structure (bands and types) • RangeSet: the actual pixels • Metadata: any other info about the coverage DomainSet + RangeType + RangeSet + Metadata = ----------- Coverage Coverage Implementation Schema (JSON encoding)
  38. Coverage extraction • Core allows to extract data from a

    coverage by: • bbox • datetime ...collections/nurc:Img_Sample/coverage? f=image%2Fpng& bbox=-130,20,-100,40
  39. Missing bits • The GeoServer implementation lacks the following: •

    RangeSet resource → describes bands • Range subsetting → band selection • Scaling scale-size/scale-factor/scale-axes • Coverage tiles
  40. Maps

  41. Maps API • Draft available at https://github.com/opengeospatial/ogcapi-maps • Building block

    to produce maps, can be attached to collections, but in general, to any resource that can be mapped • Adds a notion of a “style”, listed in collection metadata • Adds a “maps” resource • GetFeatureInfo not in core!
  42. “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/collections/topp:states/styles/population/map?f=image/png
  43. “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/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 --------------------------------------------
  44. Tiles

  45. Tiles API • Available at https://github.com/opengeospatial/ogcapi-tiles • Still evolving, GeoServer

    not up to date • Adds resources for tiles, tile matrix sets, eventually styles • Tiles can be styled or not (e.g. tiling maps or tiling data)
  46. 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, we'll tile it
  47. Tiles resource, URL templates ogc/tiles/collections/topp%3Astates/styles/population/map/tiles/ WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}?f=image%2Fpng

  48. Tiles “metadata” resource • Extension provided by some implementations •

    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" ...
  49. Styles

  50. Styles API • Building block to describe styles for a

    resource • In GeoServer a stand-alone API
  51. Style transformation • If the server supports it, fetch a

    style in various encodings (GeoServer can do CSS 🡪 SLD, MBStyle 🡪 SLD, YSLD 🡪🡪 SLD) A stylesheet can be marked as “native” SLD 1.0 core SLD 1.1 core YSLD extension MBStyles community GeoCSS extension SLD 1.0 inspired object model, with extensions
  52. Style metadata 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
  53. Styles API client • "Visual style editor" as developed by

    GeoSolutions in Testbed 15
  54. And more

  55. More of APIS! • More APIS supported by GeoServer: •

    STAC API • DGGS/DAPA (Data Access and Processing API) • Images (mosaic management) • More APIs NOT supported by GeoServer yet: • Records (CSW) • Processes (WPS) • Routes (WPS specific for routing) • Environmental Data Retrieval
  56. That’s all folks! Questions? info@geo-solutions.it

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