API guide · Argus

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:

Public (default for self-serve keys): 60 bulk calls/hour
Partner (on request): 600 bulk calls/hour
Internal: unlimited

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:

sites: comma-separated network:site_code pairs (any subset across networks)
measurand: one of no2, pm25 (also accepted: PM2.5), pm10, no, nox, o3, so2, co (case-insensitive)
start, end: ISO-8601 UTC timestamps (inclusive)
format: json (default) or csv

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

GET /api/networks — every network with site counts, freshness, operators, ratification info, licence. Powers the /networks page.
GET /api/summary — current WHO-band breakdown for a region (bbox or borough). Useful for sanity-checking your bulk pull at a glance.
GET /api/sites/{id} — single-site detail including site history and the last 30 days of every measurand.

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

6. 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.

Argus API — researcher's guide