GeoBridge

Python library that bridges Copernicus Data Stores into mainstream GIS workflows.

GeoBridge removes the technical friction GIS users face when working with Copernicus climate, atmosphere, and emergency data. It resolves dataset discovery, authentication, and access-method differences into a single ergonomic API that produces analysis-ready Cloud Optimized GeoTIFFs.

The library is the foundation for the project's QGIS plugin.

What it does

• Discovery. gb.discover() lists every dataset in the Copernicus catalogue with filters for keyword, service, variable, bounding box, and time range — all from a locally bundled snapshot, no network needed. gb.discover_one() fetches a single dataset by ID.
• Authentication. A single gb.authenticate() call handles credential resolution for the new ARCO bearer-token model.
• Extraction — ARCO path. gb.zarr_to_geotiff() pulls a spatial / temporal subset from the ARCO Zarr Data Lake and writes it as a Cloud Optimized GeoTIFF, ready for QGIS or ArcGIS. gb.list_datasets() and gb.list_variables() enumerate what's available through this path.
• Extraction — CDS API path. gb.cds_to_geotiff() submits a download job through the standard CDS API for datasets that are not yet in the ARCO lake, converts the result to GeoTIFF, and streams it to disk.
• WMTS. gb.wmts_layer() returns a ready-to-use WMTS layer object for live tile streaming inside QGIS.
• Time series. gb.point_time_series() and gb.point_value() sample a single point over time via WMTS GetFeatureInfo requests — no download, best for a handful to a few dozen time steps. gb.zarr_point_time_series() reads the same point directly out of the ARCO Zarr archive in a few chunked range-requests, and is the one to prefer for long time ranges.
• Form schema. gb.fetch_form() and gb.fetch_constraints() retrieve the server-side parameter form for any dataset so your UI can build validated request widgets. gb.valid_variables_for_product_type() filters the variable list to what the selected product type actually supports, and gb.validate_request() checks a full request dict against the dataset's constraints before you submit it.
• Styling. gb.to_qgis_style() generate calibrated colour ramps for known Copernicus variables.
• Fusion. gb.fuse() co-registers two layers onto a common grid for joint analysis (e.g. heat + air quality). The resampling kernel is picked per layer from what the variable means and whether the grid is being coarsened or refined (average for continuous fields, mode for categorical masks, max for extrema), and can be overridden with method=.
• Semantics. gb.semantic_search() resolves user themes like "urban heat island" or "wildfire risk" into concrete dataset and workflow recommendations. gb.semantic_resources() returns the matching resources directly. gb.list_themes() and gb.list_use_cases() enumerate the built-in vocabulary.

How to run it

Prerequisites

• Python 3.10 or newer. GeoBridge does not support older Python.
• A free Copernicus account. Register at https://cds.climate.copernicus.eu and copy your personal access token from your profile page.
• macOS, Linux, or Windows with WSL2. Native Windows may work but is not tested.

Configure your credentials

Create ~/.cdsapirc with your personal access token:

key: YOUR-CDS-API-KEY-HERE

Then protect the file so other users on the machine cannot read it:

chmod 600 ~/.cdsapirc

Alternatively, export your key as an environment variable instead of writing it to a file:

export CDS_API_KEY=YOUR-CDS-API-KEY-HERE

Run the Athens demo

This is the end-to-end demonstration. It extracts ERA5 temperature for Athens summer 2023, writes a Cloud Optimized GeoTIFF, and generates a matching QGIS style:

python examples/athens_urban_heat.py

Expected runtime is roughly one minute on a reasonable broadband connection. The output appears in ./athens_outputs/. Open the .tif in QGIS, load the .qml style alongside it, and you should see Athens temperatures rendered with a calibrated colour ramp.

License

MIT. See LICENSE.

Acknowledgements

GeoBridge was developed for the ECMWF Copernicus Data Store GIS Integration Challenge.