Overview¶
Aeolus is organised around two types of data sources:
Networks vs Portals¶
Networks are discrete monitoring networks operated by specific organisations:
- AURN (UK government regulatory network)
- SAQN (Scottish network)
- Breathe London (London low-cost sensors)
- AirQo (African cities)
Portals are aggregation platforms that collect data from multiple sources:
- OpenAQ (global data from 100+ countries)
- PurpleAir (global low-cost sensors)
The Unified API¶
The typical workflow is: find sites → download data → analyse → plot.
Finding Sites¶
Use find_sites() to discover monitoring sites without needing to know whether a source is a network or portal:
import aeolus
# Find AURN sites near central London
sites = aeolus.find_sites("AURN", near=(51.5074, -0.1278), radius_km=20)
print(sites[["site_code", "site_name", "distance_km"]])
# Find sites from all free sources (no API key needed)
sites = aeolus.find_sites(near=(51.5, -0.1), radius_km=10)
# Find sites in a bounding box
sites = aeolus.find_sites(["AURN", "SAQN"], bbox=(-0.5, 51.3, 0.3, 51.7))
Downloading Data¶
Use download() with the site codes from find_sites():
from datetime import datetime
start = datetime(2024, 1, 1)
end = datetime(2024, 1, 31)
# Single source
data = aeolus.download("AURN", ["MY1"], start, end)
# Multiple sources
data = aeolus.download(
{"AURN": ["MY1"], "OpenAQ": ["2178"]},
start_date=start,
end_date=end
)
Analyse and Plot¶
from aeolus import metrics, viz
# Annual regulatory statistics
stats = metrics.aq_stats(data, year=2024)
# Trend analysis
result = metrics.trend(data, pollutant="NO2")
# Temporal variation plot (openair-style 2x2)
fig = viz.plot_time_variation(data, pollutant="NO2")
Data Standardisation¶
All sources return data in a consistent format:
site_code | network | date_time | measurand | value | units | qa_code | qa_tier | ratification_stage | backend | source_network | ratification | created_at
----------|---------|---------------------------|-----------|-------|-------|---------|---------|--------------------|---------|----------------|--------------|---------------------------
MY1 | AURN | 2024-01-01 00:00:00+00:00 | NO2 | 45.2 | ug/m3 | verified | reference_full_qc | ratified | RDATA | AURN | Ratified | 2026-02-16 12:00:00+00:00
networkis who produced the data;backendis which of Aeolus's fetchers served it (AURNviaRDATAorSOS).qa_codeis the upstream's own quality token, verbatim.qa_tier(reference_full_qc,reference_provisional,lcs_calibrated,lcs_factory_only,flagged,unknown) andratification_stage(unratified,ratified,supplied,not_applicable, or null) are derived from it through the network's vocabulary, so they mean the same thing across networks.source_networkandratificationare deprecated mirrors of the columns above, kept until 1.0. SetAEOLUS_LEGACY_COLUMNS=0to drop them and confirm your code no longer reads them.
This makes it easy to combine and compare data from different sources.
Metadata Schema¶
Site metadata (from find_sites()) uses a consistent format:
site_code | site_name | latitude | longitude | network | country | instrument_class | provider | backend | measurands | source_network (deprecated mirror)
----------|--------------------|---------:|----------:|---------|---------|------------------|----------|---------|------------|---------------
MY1 | London Marylebone | 51.5225 | -0.1546 | AURN | GB | reference | null | RDATA | [NO2, ...] | AURN
provider is the operating council for LMAM sites and null elsewhere; instrument_class is the network's default until per-site values are wired.
When using near, an additional distance_km column is included, sorted nearest-first.
Time Conventions¶
Every date_time is timezone-aware UTC and marks the start of its averaging interval: a timestamp of 13:00 is the mean over 13:00–14:00 (left-closed: [13:00, 14:00)).
This is openair's "date beginning" convention. The UK-AIR web portal shows the same data "date ending", so values there appear an hour later. Where an upstream uses a different clock or labels the end of the interval (the EEA publishes in UTC+1, Sonitus stamps the end of each 15-minute bin, OpenAQ gives both ends), Aeolus converts, so the same hour from two sources carries the same timestamp.
Earlier versions of this page
Before 0.5.0 this page said 13:00 meant 12:00–13:00. The UK sources never worked that way; the page was wrong, not the data.