Add format=csv to any route and the same rows arrive flattened into columns, with a Content-Disposition filename attached so a browser saves rather than displays them. CSV is a first-class citizen here because it is what people actually load into pandas, R and Excel.

Paging a CSV. The continuation token cannot live in the body of a CSV, so it lives in the response headers instead: X-Next-Cursor carries the next cursor when one exists, and X-Row-Count carries the number of data rows. You can therefore page a bulk download without parsing a byte of the file. The header value is already URL-encoded — pass it straight back.

Where CSV and JSON differ. The columns track the JSON fields with two exceptions, both of them omissions: first_seen and last_seen are omitted from the /stations CSV, and upstream_timestamp is omitted from the /latest and raw-measurement CSVs. Everything else is column-for-field identical, pm25_correction_applied_since included: it carries the same date string the JSON does, and an empty cell is simply how CSV spells null — a network we never correct, not a correction date we failed to record.

One CSV quirk worth knowing. Spreadsheets execute a cell that begins with =, +, - or @, and station names arrive from external feeds, so any such value is prefixed with an apostrophe to render it inert. In practice this affects southern latitudes, which appear as '-8.533623. Strip a leading apostrophe before parsing coordinates numerically.

Knowing which store answered. Every /measurements response carries source_table, naming the store the rows came out of. Naming a station gives you a single store — station_daily, station_snapshots, station_snapshots (hourly buckets), nafas_daily, nafas_hourly, iq_scrape_daily or iq_scrape_hourly. A bulk scan unions several, and says so in the same field: station_daily + nafas_daily + iq_scrape_daily for bulk daily, and station_snapshots (hourly buckets) + nafas_hourly + iq_scrape_hourly for bulk hourly. Bulk raw is the single-store case, station_snapshots. You never have to know this to use the interface — the row shape is identical either way — but it means any result you publish can be traced back to specific tables.

Where min, max and samples are null. Networks that publish pre-aggregated hourly or daily figures give us one number per bucket, not a distribution, so pm25_min, pm25_max and samples come back null for those rows: pm25_min and pm25_max are null on every Nafas and scraped-IQAir row, and samples is null on every Nafas row and on scraped-IQAir hourly rows, though scraped-IQAir daily rows do carry a count where the scrape recorded one. Where the bucket was computed here from raw snapshots, all three are populated. A null is an honest absence, never a zero; and a populated samples of 1 is not the same thing as a null — see Chapter E.

Which basis the dates are on. Every /measurements response also carries date_basis, which is "WITA (UTC+8) calendar day" when the rows are daily and "UTC instant" when they are hourly or raw. It is there so a script never has to infer the boundary from the interval it asked for.

Instants are UTC. Daily dates are WITA. This is the one place the interface is deliberately not uniform, and it will bite an analysis that assumes otherwise. Every instant — observed_at, first_seen, last_seen, generated_at, and the normalised from and to in the query block — is ISO-8601 UTC with a trailing Z. But a daily date is a WITA calendar day, WITA being UTC+8 all year with no daylight saving. Daily buckets are aggregated on the local day because that is the meaningful one for a Bali reader: household waste burning has a sharp morning peak and a second climb after dark, and a UTC day would cut that evening in half. Every /measurements response states which basis applies in date_basis, so you never have to guess. Convert instants to WITA before analysing time of day, and do not silently re-bucket the daily series onto UTC.

Two networks are corrected, the rest are not, and only from a date. Low-cost optical sensors size particles with a laser, so in humid air water-swollen particles scatter more light and the sensor over-reads. AirGradient and PurpleAir publish that uncorrected figure on the open feeds we read, so we apply the standard US-EPA 2021 humidity correction before publication; every other network — Nafas, IQAir, AQICN, OpenAQ, Smart Citizen, Airly — is passed through exactly as supplied. The correction began on a specific date, which /stations reports per network as pm25_correction_applied_since, and it was not applied retroactively. The great majority of archived PurpleAir and AirGradient rows therefore predate it and carry pm25_corrected: false with a null pm25_raw — so a series that crosses that date is not corrected uniformly along its length. Nothing is lost either way: pm25_raw carries the original figure on every corrected reading, so you can reverse or re-derive the correction yourself. The formula and its behaviour at the bottom of its range are set out in the methodology chapter of the appendix.

Gaps are real. A sensor that went silent has no rows for that period — not a repeated last value, not a zero, not an interpolation. If your chart has a hole in it, that hole is the truth: nobody was measuring. This matters for Bali specifically, because several of the longest-running stations in the record went dark and stayed dark. Do not fill forward without saying so, and never treat a missing row as a clean-air row.

These are not reference instruments. Low-cost sensors drift, disagree with each other, and are affected by humidity and by their own siting. Values are published as recorded, without warranty of accuracy or fitness for any purpose. They are good enough to establish patterns, trends and magnitudes, and they are what exists — Bali has almost no regulatory monitoring. Treat them as evidence of what the air is doing, not as calibrated measurement, and say so in whatever you publish.