Programmatic Access

TipFor technical users

This chapter is for readers who want to access SEC-IMS data from scripts, desktop GIS software, or analysis notebooks rather than through the web interface. If you only use the web interface, you can skip the chapter without missing anything.

SEC-IMS publishes its data through OGC API standards. Three APIs cover most use cases:

API Serves Common consumers
OGC API – Records Catalogue search and metadata records QGIS MetaSearch, owslib, browser/curl
OGC API – Features Vector data as JSON (GeoJSON, JSON-FG) QGIS, geopandas, ogr2ogr
OGC API – Coverages Raster data as TIFF/NetCDF subsets QGIS, rioxarray, rasterio

Two complementary delivery formats serve the visual map use case:

Format Serves Common consumers
OGC API – Tiles Pre-cut raster or vector tiles (PNG, MVT) Web maps, QGIS XYZ connection
PMTiles passthrough Single-file vector tile archive Web maps, QGIS PMTiles connection

Each section below shows the same datasets reached through a different client.

7.1 Browser and curl basics

The simplest way to understand the API surface is to open the root URL in a browser:

https://secims.example/pygeoapi/

This lists the available collections and links to each one’s landing page. From the collection landing page you can drill into items, the queryables, and the OpenAPI definition.

For scripting, curl is enough for almost everything:

# List every collection on the server
curl -s https://secims.example/pygeoapi/collections?f=json \
  | jq '.collections[].id'

# Fetch the first ten features of a vector collection as GeoJSON
curl -s "https://secims.example/pygeoapi/collections/coastal_habitats/items?limit=10&f=json" \
  > coastal_habitats.geojson

# Fetch a record from the catalogue
curl -s "https://secims.example/records/collections/metadata:main/items/<record-id>?f=json" \
  | jq .

# Get the OpenAPI document
curl -s https://secims.example/pygeoapi/openapi?f=json > openapi.json

The f= query parameter selects the response format. f=json is universally supported; many endpoints also accept f=html, f=geojson, and f=gpkg.

7.2 QGIS workflows

QGIS connects to SEC-IMS through several built-in mechanisms. The examples below assume QGIS 3.34 or newer.

7.2.1 Catalogue browsing via MetaSearch (CSW)

The MetaSearch plugin (bundled with QGIS) connects to SEC-IMS’s CSW endpoint and lets you search the catalogue from inside QGIS.

  1. Open Web → MetaSearch → Services.
  2. Click New, give the connection a name (e.g. SEC-IMS) and a URL: https://secims.example/csw
  3. Click OK and then Connect.
  4. Switch to the Search tab. Enter terms or set a bounding box and click Search. Results appear with abstract previews; select one and click Add data to load any linked WMS/WFS resources straight into the project.
NoteScreenshot needed

qgis-metasearch-services — The MetaSearch Services tab with the SEC-IMS connection configured. Capture the dialog with the URL field clearly readable.

NoteScreenshot needed

qgis-metasearch-results — The MetaSearch Search tab with results listed after a sample query. Capture with at least one result selected so the abstract pane is populated.

7.2.2 Vector layers via OGC API – Features

  1. Layer → Add Layer → Add WFS Layer…
  2. In the dialog, click New and enter:
    • Name: SEC-IMS Features
    • URL: https://secims.example/pygeoapi/
    • Version: leave as default (QGIS will negotiate).
  3. OK, then Connect. The available collections appear.
  4. Select one or more collections and click Add.

QGIS streams features on demand — only the features in the current map extent are fetched, so even large collections behave responsively. To download a collection in full for offline use, right-click the layer and choose Export → Save Features As….

NoteScreenshot needed

qgis-add-features — The QGIS Add WFS dialog with the SEC-IMS server configured and a collection list visible. Highlight one collection selected for adding.

7.2.3 Raster via OGC API – Coverages

For SEC-IMS raster collections published as coverages:

  1. Layer → Add Layer → Add Raster Layer…
  2. Switch the source type to Protocol: HTTP(S).
  3. URL: https://secims.example/pygeoapi/collections/<id>/coverage?f=GTiff
  4. Add — QGIS reads the full coverage. For large coverages, restrict the area by appending a bounding box: &subset=Lat(13.7:13.9),Lon(-60.95:-60.85)

For frequently accessed coverages, downloading the source GeoTIFF and opening it directly is usually faster than streaming it on every session. The metadata record’s distribution links typically include a direct file URL where this applies.

7.2.4 Raster via XYZ tiles

When a raster has been published as tiles (OGC API – Tiles or OGC API – Maps), it can be added as an XYZ connection:

  1. Layer → Add Layer → Add XYZ Layer…
  2. New, name it (e.g. SEC-IMS satellite mosaic).
  3. URL template (replace <id> with the collection identifier): https://secims.example/pygeoapi/collections/<id>/map/tiles/WebMercatorQuad/{z}/{y}/{x}?f=png
  4. Set the zoom range to match the tileset (typically 0–18).
  5. OK and Add.

The exact tile-URL template for a collection is listed in the metadata record’s distribution section. Copy it from there rather than typing it manually.

NoteScreenshot needed

qgis-xyz-add — The Add XYZ Layer dialog with the URL template filled in. Highlight the URL template and zoom range fields.

7.2.5 PMTiles passthrough

SEC-IMS serves large pre-built vector tile archives in the PMTiles format directly. QGIS 3.34+ can read PMTiles natively via the Vector Tiles connection:

  1. Layer → Add Layer → Add Vector Tile Layer…
  2. New → Generic Connection, name it (e.g. SEC-IMS habitats PMTiles).
  3. URL: the .pmtiles distribution link from the dataset’s metadata page, for example https://secims.example/pmtiles/habitats.pmtiles.
  4. OK, then Add.

PMTiles connections work over Range requests, so QGIS only downloads the tiles it needs for the current view.

NoteScreenshot needed

qgis-pmtiles-add — The Add Vector Tile Layer dialog showing a PMTiles URL. Annotate the distinction between a PMTiles URL (.pmtiles endpoint) and a regular vector tile URL template.

7.3 Python notebooks

The examples below use owslib, requests, geopandas, and rioxarray. All are available from PyPI:

pip install owslib requests geopandas rioxarray

7.3.1 Catalogue queries

Use owslib for CSW (the OGC 2.0.2 endpoint) or requests against OGC API – Records.

# Option 1 — owslib against the CSW endpoint
from owslib.csw import CatalogueServiceWeb

csw = CatalogueServiceWeb("https://secims.example/csw")
csw.getrecords2(maxrecords=10, esn="full")
for rec in csw.records.values():
    print(rec.identifier, "-", rec.title)
# Option 2 — plain HTTP against OGC API – Records
import requests

r = requests.get(
    "https://secims.example/records/collections/metadata:main/items",
    params={"q": "mangrove", "limit": 10, "f": "json"},
    timeout=30,
)
for feat in r.json()["features"]:
    p = feat["properties"]
    print(feat["id"], "-", p.get("title"))

7.3.2 Vector data with geopandas

geopandas can read OGC API – Features endpoints directly:

import geopandas as gpd

url = (
    "https://secims.example/pygeoapi/"
    "collections/coastal_habitats/items?f=json&limit=10000"
)
gdf = gpd.read_file(url)
print(gdf.crs, gdf.shape)
gdf.head()

For large collections, page through the results using the API’s limit and offset parameters, or restrict by bounding box with the bbox parameter to avoid retrieving the whole collection.

7.3.3 Raster data with rioxarray and rasterio

For raster collections offered through OGC API – Coverages or as direct GeoTIFFs:

import rioxarray

# Direct GeoTIFF link from the metadata record
url = "https://secims.example/files/dem_southeast_coast.tif"
da = rioxarray.open_rasterio(url, masked=True)
da.plot.imshow()

For a Coverages subset:

import rioxarray

url = (
    "https://secims.example/pygeoapi/"
    "collections/dem_southeast_coast/coverage"
    "?subset=Lat(13.7:13.9),Lon(-60.95:-60.85)&f=GTiff"
)
da = rioxarray.open_rasterio(url, masked=True)
da.rio.to_raster("dem_subset.tif")

For Cloud Optimised GeoTIFFs hosted as direct files, rioxarray and rasterio use Range requests to stream only the windows you read — opening a 2 GB COG and reading a small subset takes seconds, not the time it would take to download the whole file.

7.4 Where to go next

  • OGC API specifications — the canonical reference for each API:
  • SEC-IMS API documentation — the auto-generated OpenAPI document at https://secims.example/pygeoapi/openapi?f=html describes every endpoint with full parameter lists and example responses.
  • pygeoapi documentation — the upstream pygeoapi documentation at https://docs.pygeoapi.io/ covers the server’s capabilities in depth, including provider plugins and query language details.
  • pycsw documentation — the upstream pycsw documentation at https://docs.pycsw.org/ describes the catalogue and search endpoints.