STAC API and OGC API - Features - Part 1: Core

September 7, 2022 · View on GitHub

This API is an implementation of both the STAC API and the OGC API - Features - Part 1: Core (OAFeat). The STAC API and OAFeat have a slightly different data model, which is briefly discussed below.

The STAC API is a “dataset based” download service providing access to packaged geospatial data and related metadata. The data model is based on the following main concepts:

  • Collection: a collection is a set of metadata about a geospatial dataset, like its name, description, spatial and temporal extent, etc. Individual records within a collection are called items
  • Item: an item represents an atomic collection of inseparable data and metadata. A STAC item is a GeoJSON Feature and can be easily read by any modern GIS or geospatial library, and it describes a SpatioTemporal Asset. This means that the GeoJSON is not the "actual" thing, but instead references files and serves as an index to an asset
  • Asset: an asset is any file containing the actual data.

OAFeat is a "features based" service providing access to single objects (features) of a dataset. In OAFeat there is no concept of asset and the item is the actual data.

To summarize, the STAC API is aimed at providing access to the complete dataset, while OAFeat is aimed at providing access to single features of a dataset.

Note Feedback required: after you tested our Proof of Concept, give us feedback on the MeteoSwiss data or OGC API Features services -> Fill out the SURVEY (DE) or SURVEY (EN), it takes only 10 min

API endpoints

The API provides the following endpoints:

EndpointReturnsDescription
/JSONLanding page
/conformanceJSONInfo about standards to which the API conforms
/collectionsJSONObject containing an array of Collection objects in the Catalog, and Link relations
/collections/{collectionId}CollectionReturns single Collection JSON
/collections/{collectionId}/itemsItemCollectionGeoJSON FeatureCollection-conformant entity of Item objects in collection
/collections/{collectionId}/items/{featureId}ItemReturns single Item (GeoJSON Feature)
/searchItem CollectionSTAC search endpoint

The API documentation is available here:

EndpointDescription
/apiThe Open API definition
/swaggerThe Swagger UI

Default limit and pagination

The number of items returned as a result to a query (/collections/{collectionId}/items and /search endpoints) is limited to 100. In case the number of matched items is greater than 100, the API implements a pagination mechanism and provides two links rel: "next" and rel: "prev" to allow you to go through all matched items. The following query, for example, matches 394092 (see property numberMatched) items but only returns 100 of them (see property numberReturned). The link with rel: "next" returns the next 100 items and so on. The link with rel: "prev" returns the previous 100 items.

Available datasets

The API provides currently the following datasets (collections):

Note The collections Measurement values air temperature 2 m, Instantaneous Value and Measurement values: Hourly values (PoC) have been implemented as STAC and as OAFeat resources. The STAC assets (the complete datasets) are available directly at collection level. The assets at item level do not link to packaged files but to the API call to the item itself.

Some example queries

Note For the collections Measurement values air temperature 2 m, Instantaneous Value and Measurement values: Hourly values (PoC) all item properties can be used as key-value pairs (KVP) in the query URL.

Here a list of example queries you can test within a browser. Use Firefox, which has a built-in json viewer. Copy&paste the example queries in URL bar of the browser:

Working with the STAC Browser

Note At this link you will find a list of clients that can be used to work with APIs implementing the STAC API Specification. Here the basic usage with the STAC Browser will be shortly discussed.

An easy way to consume the API is to use the STAC Browser:

Load

You will get a HTML presentation of the Landing Page with a description and a list of collections and additional links. You can visualize the collections as List or as Tiles and you can order them alphabetically by title. Then you just follow your nose to browse the different resources. Meaning: click on a collection of interest, click on an item of interest, download the asset files.

Landing page

Note For the collections Measurement values air temperature 2 m, Instantaneous Value and Measurement values: Hourly values (PoC) the asset files are available directly at collection level.

Working with the STAC API Browser Plugin in QGIS

In order to consume the API with the STAC API Browser Plugin in QGIS proceed as follows:

  • Open QGIS and go to Plugins>Manage and Install Plugins...
  • Search for STAC API Browser and install the plugin

STAC API Plugin

Add connection

  • Click on Fetch collections, select the collection of interest and click on Search
  • Click on View assets in the item of interest
  • Click on Download asset and load back into QGIS the downloaded file

Download asset

It is additionally possible to filter by datetime and by bbox. In the following example we will retrieve the asset files of the item with datetime 2022-07-07T13:24:00Z from the collection Warnung vor Naturgefahren:

  • In the main window of the plugin select the collection Warnung vor Naturgefahren
  • Activate Filter by date and set the date and time in Start. Leave End as NULL
  • Click on Search and download the asset file

Filter by datetime

Working with the OAFeat interface in ArcGIS Online

Note At this link you will find a list of clients that can be used to work with APIs implementing OAFeat. Here the basic usage with ArcGIS Online will be shortly discussed.

Add OAFeat connection AGOL

  • Adapt symbology, labels and various other settings with the right hand menu, make sure you set the refresh interval

Add OAFeat symbol AGOL

Working with the OAFeat interface in QGIS

Note At this link you will find a list of clients that can be used to work with APIs implementing OAFeat. Here the basic usage with the GIS client QGIS will be shortly discussed.

Add OAFeat connection

  • In the main window choose the newly created connection, click on Connect, select the collection Aktuelle Daten..., click on Add then on Close

Add OAFeat collection

It is additionally possible to filter by datetime, bbox and by other item properties. In the following example we will retrieve all observations (collection Measurement values: Hourly values (PoC)...) of the parameter pp0qnhh0 for all stations at the datetime 2022-07-17T00:00:00Z:

  • Select the collection Measurement values: Hourly values (PoC)... and click on Build query
  • Under Provide Specific Filter Expressions set the expression to "param_short" = 'pp0qnhh0' AND "datetime" = '2022-07-17T00:00:00Z'
  • Click on OK, click on Add then on Close

OAFeat filters

Working with the command line

Note At this link you will find a list of CLI clients that can be used to work with APIs implementing the STAC API Specification. For the following examples we will be using curl, jq and wget

  • Get the title and the ID of all available collections:
    • curl "https://poc.meteoschweiz-poc.swisstopo.cloud/root/collections" | jq ".collections[] | .title, .id"
  • Get all items of the collection Gridded dataset of global radiation (ID: 4ccc5153-cc27-47b8-abee-9d6e12e19701):
    • curl "https://poc.meteoschweiz-poc.swisstopo.cloud/root/collections/4ccc5153-cc27-47b8-abee-9d6e12e19701/items" | jq ".features[].id"
  • Get the URL of the assets of the item with ID 20220301 from the collection Gridded dataset of global radiation (ID: 4ccc5153-cc27-47b8-abee-9d6e12e19701):
    • curl "https://poc.meteoschweiz-poc.swisstopo.cloud/root/collections/4ccc5153-cc27-47b8-abee-9d6e12e19701/items/20220301" | jq ".assets[].href"
  • Download an asset file:
    • wget "https://s3.meteoschweiz-poc.swisstopo.cloud/4ccc5153-cc27-47b8-abee-9d6e12e19701/msg.SIS-No-Horizon.M_ch02.lonlat_20220301000000.nc"
  • Get the URL of the assets of the item with datetime=2022-07-04T13:24:00Z from the collection Severe weather warnings (PoC) (ID: 35ff8133-364a-47eb-a145-0d641b706bff):
    • curl "https://poc.meteoschweiz-poc.swisstopo.cloud/root/collections/35ff8133-364a-47eb-a145-0d641b706bff/items?datetime=2022-07-04T13:24:00Z" | jq ".features[].assets[].href"
  • Get the URL of all assets of all items in a given bbox from the collection Measurement values: Daily values (PoC) (ID: b46a8f8d-bc48-41d3-b20a-de61d0763318):
    • curl "https://poc.meteoschweiz-poc.swisstopo.cloud/root/collections/b46a8f8d-bc48-41d3-b20a-de61d0763318/items?bbox=7.222133596513244,46.8348382353821,7.632747610185119,47.022404503762395" | jq ".features[].assets[].href"

Under Windows 10 - Powershell

  • Start Windows Powershell

  • In case you are behind a proxy server, you need to execute this 4 commands:

    • $browser = New-Object System.Net.WebClient
    • $browser.Proxy.Credentials =[System.Net.CredentialCache]::DefaultNetworkCredentials
    • $AllProtocols = [System.Net.SecurityProtocolType]'Ssl3,Tls,Tls11,Tls12'
    • [System.Net.ServicePointManager]::SecurityProtocol = $AllProtocols
    • (Invoke-WebRequest -Uri "https://s3.meteoschweiz-poc.swisstopo.cloud/").StatusCode

  • Download an asset file, e.g. based from the items list or you can construct the URL yourself e.g. for COSMO-1E with <model-name>/<format>/<ZZ>/<HHH>/<parameter-shortname>/<file name> with ZZ= modelrun, HHH forecast e.g. COSMO-1E_alps_rotlatlon_single-level_leadtime_000_member_000_parameter_T_2M.grib2:

    • wget "https://s3.meteoschweiz-poc.swisstopo.cloud/a6296aa9-d183-45c3-90fc-f03ec7d637be/COSMO-1E_alps_rotlatlon_single-level_leadtime_000_member_000_parameter_T_2M.grib2" -Outfile "COSMO-1E_alps_rotlatlon_single-level_leadtime_000_member_000_parameter_T_2M.grib2"

  • In case you want to increase the Donwload speed in Powershell, deactivate the progress bar with $ProgressPreference = 'SilentlyContinue' and reactivate it with $ProgressPreference = 'Continue'

An example of an interactive web map with Leaflet

Here an example of an interactive web map using Leaflet, the WMTS of the Federal Spatial Data Infrastructure for the backgroung map and the OAFeat interface to the collection Measurement values air temperature 2 m, Instantaneous Value:

image

Feedback required: Can you answer our questions about the Proof of Concept?

We are inviting you to take our survey about our Proof of Concept data and services since you are interested in MeteoSwiss data or OGC API Features services.

-> Fill out the SURVEY (DE) or SURVEY (EN), it takes only 10 min

Terms Of Service

Consult the Terms of Service section of the README.md.

Questions?

Please drop us an e-mail to customerservice@meteoswiss.ch with the subject POC OGD24.