South London Scientific

Argus

Network › API guide

Argus API — researcher's guide

Argus is a unified read layer over every UK regulatory air quality monitoring network (AURN, LAQN, AQE, SAQN, WAQN, NI) plus the Breathe London low-cost sensor network. This page is a 5-minute introduction for researchers who want to pull bulk hourly data through the HTTP API. The full machine-readable reference lives at /api/docs.

1. Get an API key

Every keyed endpoint requires an X-API-Key header. Keys are issued by self-serve email: POST your email and a one-line purpose, and the key arrives in a moment. 

curl -X POST https://argus.southlondonscientific.com/api/keys/request \
  -H "Content-Type: application/json" \
  -d '{"email": "you@university.ac.uk",
       "purpose": "DiD analysis of ULEZ on PM2.5"}'

Issuance is rate-limited (5 requests/day, 50/30 days per IP) to keep the abuse surface narrow. The email includes a one-click revocation link if the key ever leaks. Bulk-readings access is tiered:

A per-IP backstop (1000 keyed calls/min) sits in front of the whole namespace. Non-bulk endpoints (catalogue, summary, headline) aren't per-tier limited — only /api/readings/bulk is.

If you need higher throughput or a partner tier, email hello@southlondonscientific.com with what you're building.

2. The two endpoints you actually need

Most research workflows reduce to: find the sites, then pull the time series. Two endpoints cover this.

GET /api/sites — the catalogue

Returns one row per monitoring site with code, network, name, coordinates, site type, and the most recent reading per measurand. Pass ?bbox=min_lon,min_lat,max_lon,max_lat for a geographic filter; omit it for UK-wide. Example: every site in Wales. 

curl "https://argus.southlondonscientific.com/api/sites?bbox=-5.7,51.3,-2.6,53.5" \
  -H "X-API-Key: $ARGUS_KEY"

Each site comes back with a stable (network, site_code) pair — these are the IDs you pass to the bulk endpoint. Site codes are scoped to network (e.g. WAQN:CAR04 is a different site from AURN:CAR04 if both existed), so always pair them with the network.

GET /api/readings/bulk — the time series

Returns long-format hourly data for many sites in one call. Designed for downstream analytics (panel regressions, DiD, ML pipelines). 

curl "https://argus.southlondonscientific.com/api/readings/bulk\
?sites=WAQN:CAR04,WAQN:CAR05,AURN:MY1\
&measurand=no2\
&start=2022-05-17T00:00:00Z\
&end=2026-05-17T00:00:00Z\
&format=csv" \
  -H "X-API-Key: $ARGUS_KEY"

Parameters:

Each row has six fields:

time, network, site_code, measurand, value, units

Times are UTC. Values are µg/m³ (mass concentrations) or ppb (where upstream reports gas concentrations as ppb) — always check the units column rather than assuming. Hours are timestamped at the start of the hourly mean.

3. Worked example: 4 years of Welsh NO₂

Pull every WAQN site's NO₂ from May 2022 to today as a pandas DataFrame: 

import os
import io
import requests
import pandas as pd

KEY = os.environ["ARGUS_KEY"]
BASE = "https://argus.southlondonscientific.com/api"

# 1. List Welsh sites
sites = requests.get(
    f"{BASE}/sites?bbox=-5.7,51.3,-2.6,53.5",
    headers={"X-API-Key": KEY},
).json()
waqn_codes = [f"WAQN:{s['site_code']}" for s in sites if s["source_network"] == "WAQN"]
print(f"{len(waqn_codes)} WAQN sites")

# 2. Pull 4 years of hourly NO2 as CSV
r = requests.get(
    f"{BASE}/readings/bulk",
    params={
        "sites": ",".join(waqn_codes),
        "measurand": "no2",
        "start": "2022-05-17T00:00:00Z",
        "end": "2026-05-17T00:00:00Z",
        "format": "csv",
    },
    headers={"X-API-Key": KEY},
)
if r.headers.get("X-Argus-Capped") == "true":
    raise RuntimeError("Hit 500k-row cap — narrow the window or split sites")

df = pd.read_csv(io.StringIO(r.text), parse_dates=["time"])
print(df.head())
print(df.groupby("site_code").size().describe())

Expect 1–3 million rows depending on which sites you include. The 500,000-row cap (signalled by X-Argus-Capped: true) is per call — split by year or site if you hit it.

4. Data caveats

Provisional vs ratified

Argus delivers provisional data — values as published by upstream networks in real time, before quarterly ratification. Final ratified values typically appear 9 months after year-end. If your analysis publishes formal statistics, refresh from the upstream network's ratified archive for the relevant year, or wait until the ratification window has closed. See /networks for each network's ratification process and lag.

Refresh cadence

AURN, LAQN, AQE, SAQN, and Breathe London poll every 15 minutes. WAQN and NI poll every 4 hours via openair RData (the upstream R files refresh ~daily — sub-hour polling buys no fresh data). LAQN and the openair RData feeds can lag 1–2 days behind real-time intermittently when upstream pipelines are slow.

Coverage

Argus carries the last 2–4 years for most networks. Pre-2022 data is not present — pull it from uk-air.defra.gov.uk (AURN), londonair.org.uk (LAQN), or the openair R package directly.

Licence

AURN, LAQN, SAQN, AQE, and NI publish under Open Government Licence v3.0. WAQN publishes under Crown Copyright with reproduction permitted for personal or in-house use — see airquality.gov.wales/copyright-statement before redistributing. Breathe London is open under their own terms (see breathelondon.org). Argus adds no rights restrictions of its own.

Attribution

When publishing, attribute the upstream network as the data source (e.g. "Welsh Government / Natural Resources Wales via Argus (South London Scientific)"). Argus is a convenience layer over the canonical publishers — they did the measurement work.

5. Other useful endpoints

Full reference (request schemas, response models, all parameters): /api/docs (Swagger UI) or /api/openapi.json (raw OpenAPI 3 spec).

6. Public endpoints (no API key)

These need no key and are CORS-open, so you can call them from a browser. They serve modelled estimates, not measurements — see sources and methods before using them in anything that matters. Rate limits are per-IP.

Background concentration

Health impact

The 20-year benefit of an English area meeting the WHO 2021 guidelines — deaths and cases prevented, QALYs, and monetised value. Research preview: population-level estimates for comparison and prioritisation, under independent review. Full method and citations at sources and methods.

Every response carries a caveat field describing the resolution of the underlying health rates, a working block with the model inputs (guideline targets, discount rate, QALY value, undiscounted QALYs), and provenance (model version, function library, run hash). If you display these figures, display the caveat.

7. Getting help

If something doesn't behave as documented, or you want a partner-tier rate limit for a specific project, email hello@southlondonscientific.com. Argus is built and maintained by South London Scientific — we welcome problem reports, feature requests, and academic collaborations.