Add UK-AIR station thumbnails

Author: Sam-Bolling

docs/research/new-publisher-source-planning/UK_AIR_Publisher_Completion_Report_2026-05-26.md

@@ -130,6 +130,22 @@ Two UI polish issues were found and fixed in the Explorer repo:
 
 The UK-AIR symbol rule now maps air-quality stations to the same friendly emplaced sensor family used for Environment Agency Hydrology, USGS Water, CO-OPS, NDBC, and weather station markers.
 
+## Representative Station Thumbnails
+
+The UK-AIR SOS / 52 North API was checked for station and timeseries media fields. It exposes useful station/timeseries metadata, coordinates, units, pollutant URIs, and latest values, but no station photo or thumbnail media. Representative imagery was therefore selected from Wikimedia Commons / Geograph Britain and Ireland using reusable CC BY-SA 2.0 images that depict actual UK air-quality monitoring stations.
+
+Selected images:
+
+| Demo station | Image | Author | License | Rationale |
+| --- | --- | --- | --- | --- |
+| Camden Kerbside | `Air Quality Monitoring Station - geograph.org.uk - 2573031.jpg` | Jonathan Thacker | CC BY-SA 2.0 | Roadside/industrial monitoring cabinet is the closest visual match for an urban kerbside NO2 site. |
+| Auchencorth Moss | `Air-quality monitoring station, Dundonald - geograph.org.uk - 3201697.jpg` | Albert Bridge | CC BY-SA 2.0 | Vegetated/background cabinet is a better fit for a rural background ozone station than the roadside cabinet. |
+| Toft Newton | `Air-quality monitoring station, Dundonald - geograph.org.uk - 3201697.jpg` | Albert Bridge | CC BY-SA 2.0 | Used as a representative background particulate monitoring station image because no Toft Newton station photo is exposed by UK-AIR. |
+
+The station image metadata is stored in `publishers/uk_air/stations.json` and emitted by `bootstrap_uk_air.py` as SensorML `documents` entries with role `http://dbpedia.org/resource/Photograph`, `image/jpeg` media type, source page, author, source, and license attribution. The live OSH server accepted a forced SensorML update for all three UK-AIR systems, and read-back confirmed the image documents persisted.
+
+Explorer also carries a UK-AIR thumbnail fallback for resilience, but the local validation used the live SensorML media path: the side card for `UK-AIR Auchencorth Moss` rendered the Dundonald representative station image with natural dimensions `632 x 570`.
+
 ## Validation Commands
 
 ```powershell
@@ -138,6 +154,7 @@ py -m publishers.uk_air.uk_air_publisher --dry-run --once
 py -m publishers.uk_air.bootstrap_uk_air --dry-run
 py -m publishers.uk_air.bootstrap_uk_air
 py -m publishers.uk_air.uk_air_publisher --once
+py -m publishers.uk_air.bootstrap_uk_air --force-sml
 ```
 
 All final validation commands completed successfully.
@@ -148,10 +165,10 @@ Explorer validation command:
 npm --prefix demo run build
 ```
 
-The patched Explorer build completed successfully and was validated locally through Vite preview at `http://127.0.0.1:4174/` against the live `OSH (OS4CSAPI)` backend.
+The patched Explorer build completed successfully and was validated locally through Vite preview at `http://127.0.0.1:4174/` against the live `OSH (OS4CSAPI)` backend. The validation confirmed the UK-AIR thumbnail image appears in the deployed-system side card.
 
 ## Follow-Up Items
 
-1. After the Explorer deployment completes, spot-check production again to confirm the patched `Air Quality Site` label and value/unit spacing are live.
-2. Consider adding a representative monitoring-station image/fallback after a verified public image source is selected, following the Environment Agency Hydrology pattern.
+1. After the Explorer deployment completes, spot-check production again to confirm the patched `Air Quality Site` label, value/unit spacing, and thumbnail fallback are live in the production bundle.
+2. Consider replacing representative images with exact station photos if Defra/UK-AIR later publishes station-specific media under reusable terms.
 3. Consider expanding the curated sidecar after demo validation, especially for additional urban NO2/PM sites and rural background stations.

publishers/uk_air/README.md

@@ -15,6 +15,11 @@ Source data comes from the UK-AIR SOS / 52 North Timeseries REST API:
 - https://uk-air.defra.gov.uk/data/sos/static/doc/api-doc/
 - https://uk-air.defra.gov.uk/sos-ukair/api/v1/
 
+Station thumbnails use representative UK air-quality monitoring station photographs from Wikimedia Commons / Geograph Britain and Ireland because the UK-AIR API exposes no station photo media:
+
+- Camden Kerbside uses a roadside monitoring-station cabinet photograph by Jonathan Thacker, CC BY-SA 2.0.
+- Auchencorth Moss and Toft Newton use a vegetation/background monitoring-station cabinet photograph by Albert Bridge, CC BY-SA 2.0.
+
 ## Bootstrap
 
 ```bash
@@ -42,3 +47,4 @@ Use `--stations` with comma-separated curated site IDs, such as `camden-kerbside
 - Source units such as `ug.m-3` are preserved in observation results as `unit`, while SWE schemas use the display-friendly `ug/m3` code.
 - The first-pass model consolidates co-located pollutant streams only where the source metadata clearly supports it, such as Toft Newton PM10 and PM2.5.
 - Explorer cards should show latest pollutant concentrations in the same latest-reading section used by other station-style publishers.
+- Explorer cards should show the representative thumbnail from SensorML `documents` when the server preserves it; the Explorer also carries a UK-AIR fallback while current OSH system SensorML update behavior is uneven.

publishers/uk_air/bootstrap_uk_air.py

@@ -44,6 +44,32 @@
 OGL3 = "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
 
 
+def _image_docs(station: dict) -> list[dict]:
+    image = station.get("image") or {}
+    if not image.get("url"):
+        return []
+    description = image.get("description") or "Representative UK air quality monitoring station image."
+    attribution = "; ".join(part for part in [
+        image.get("author"),
+        image.get("source"),
+        image.get("license"),
+    ] if part)
+    return [
+        {
+            "role": "http://dbpedia.org/resource/Photograph",
+            "name": image.get("name") or "Representative air quality monitoring station image",
+            "description": f"{description} Attribution: {attribution}.",
+            "link": {"href": image["url"], "type": "image/jpeg"},
+        },
+        {
+            "role": "http://dbpedia.org/resource/Web_page",
+            "name": "Representative image source and license",
+            "description": f"Image source page and reuse terms ({image.get('license', 'license documented at source')}).",
+            "link": {"href": image.get("pageUrl") or image["url"], "type": "text/html"},
+        },
+    ]
+
+
 def _load_stations() -> list[dict]:
     here = os.path.dirname(os.path.abspath(__file__))
     with open(os.path.join(here, "stations.json"), encoding="utf-8") as f:
@@ -156,7 +182,7 @@ def _system_stub(station: dict) -> dict:
 def _system_sml(station: dict) -> dict:
     site_id = station["siteId"]
     pollutant_labels = ", ".join(s["pollutantCode"] for s in station.get("timeseries", []))
-    docs = [
+    docs = _image_docs(station) + [
         {
             "role": "http://dbpedia.org/resource/Web_page",
             "name": "UK-AIR Representative Timeseries",

publishers/uk_air/stations.json

@@ -15,6 +15,16 @@
       "siteType": "urban roadside",
       "stationUrl": "https://uk-air.defra.gov.uk/sos-ukair/api/v1/timeseries/3",
       "selectionReason": "Recognizable London roadside nitrogen dioxide station with recent hourly values.",
+      "image": {
+        "url": "https://upload.wikimedia.org/wikipedia/commons/0/0e/Air_Quality_Monitoring_Station_-_geograph.org.uk_-_2573031.jpg",
+        "pageUrl": "https://commons.wikimedia.org/wiki/File:Air_Quality_Monitoring_Station_-_geograph.org.uk_-_2573031.jpg",
+        "name": "Representative roadside air quality monitoring station",
+        "description": "Representative UK air quality monitoring station cabinet, used for the urban roadside Camden Kerbside demo site because the UK-AIR API exposes no station photo.",
+        "author": "Jonathan Thacker",
+        "source": "Geograph Britain and Ireland via Wikimedia Commons",
+        "license": "CC BY-SA 2.0",
+        "licenseUrl": "https://creativecommons.org/licenses/by-sa/2.0/"
+      },
       "timeseries": [
         {
           "timeseriesId": "3",
@@ -41,6 +51,16 @@
       "siteType": "rural background",
       "stationUrl": "https://uk-air.defra.gov.uk/sos-ukair/api/v1/timeseries/24",
       "selectionReason": "Rural background ozone station with recent hourly values.",
+      "image": {
+        "url": "https://upload.wikimedia.org/wikipedia/commons/7/75/Air-quality_monitoring_station%2C_Dundonald_-_geograph.org.uk_-_3201697.jpg",
+        "pageUrl": "https://commons.wikimedia.org/wiki/File:Air-quality_monitoring_station,_Dundonald_-_geograph.org.uk_-_3201697.jpg",
+        "name": "Representative background air quality monitoring station",
+        "description": "Representative UK air quality monitoring station cabinet in a vegetated setting, used for Auchencorth Moss because the UK-AIR API exposes no station photo.",
+        "author": "Albert Bridge",
+        "source": "Geograph Britain and Ireland via Wikimedia Commons",
+        "license": "CC BY-SA 2.0",
+        "licenseUrl": "https://creativecommons.org/licenses/by-sa/2.0/"
+      },
       "timeseries": [
         {
           "timeseriesId": "24",
@@ -67,6 +87,16 @@
       "siteType": "background particulate monitoring",
       "stationUrl": "https://uk-air.defra.gov.uk/sos-ukair/api/v1/timeseries/5125",
       "selectionReason": "Co-located PM10 and PM2.5 timeseries with recent hourly values.",
+      "image": {
+        "url": "https://upload.wikimedia.org/wikipedia/commons/7/75/Air-quality_monitoring_station%2C_Dundonald_-_geograph.org.uk_-_3201697.jpg",
+        "pageUrl": "https://commons.wikimedia.org/wiki/File:Air-quality_monitoring_station,_Dundonald_-_geograph.org.uk_-_3201697.jpg",
+        "name": "Representative background particulate monitoring station",
+        "description": "Representative UK air quality monitoring station cabinet in a vegetated setting, used for Toft Newton because the UK-AIR API exposes no station photo.",
+        "author": "Albert Bridge",
+        "source": "Geograph Britain and Ireland via Wikimedia Commons",
+        "license": "CC BY-SA 2.0",
+        "licenseUrl": "https://creativecommons.org/licenses/by-sa/2.0/"
+      },
       "timeseries": [
         {
           "timeseriesId": "5125",