# ArmAQI

> Community air quality monitoring in Armenia: PM2.5 and PM10 from ArmAQI's own sensors, the Yerevan municipal network and Sensor.Community. Open read-only JSON API, no key required.

Fetching data selectively to answer questions and for analysis is welcome; bulk downloading is not, especially for municipal data (see "Sources and terms").

ArmAQI publishes measurements and says "no data" when there are none. It does not establish causes of pollution: its data alone is not evidence of a cause. If you combine it with other sources (weather, satellite, news), say which part of the answer rests on which source.

## API

- [OpenAPI 3.1 description](https://armaqi.org/api/v1/openapi.json): all anonymous read-only endpoints, parameters and response schemas.
- [Air in Yerevan now](https://armaqi.org/api/v1/places/yerevan): the city value for the latest available hour, see "City values" below.
- [All stations now](https://armaqi.org/api/v1/stations): coordinates and the latest hour of every visible station; pick the nearest ones to a point yourself. Only Yerevan is published as a place so far; for other towns use nearby stations.
- [Stations at a past hour](https://armaqi.org/api/v1/stations?at=2026-01-15T08:00:00Z): `at` is RFC 3339, truncated to the hour in UTC, not earlier than 2019-01-01. A station without that exact hour has `current: null`.
- [Station history](https://armaqi.org/api/v1/stations/26/history?step=day&period=30d): `step=hour|day`, and either `period=1d|7d|30d|365d` (ending now) or `from` and `to` together.
- [City history for a month](https://armaqi.org/api/v1/places/yerevan/history?step=day&from=2026-10-01&to=2026-10-31): `from`/`to` take a date `YYYY-MM-DD`, a Yerevan calendar day, and `to` includes its day, so this is the whole of October. They also take an RFC 3339 moment such as `2026-10-01T08:00:00Z`; as `to` it is exclusive. A window is at most 31 days for `step=hour` and 400 days for `step=day`.
- [Wind at a place](https://armaqi.org/api/v1/places/yerevan/wind?from=2026-10-01&to=2026-10-31): a wind rose for the window, same `from`/`to`. The default model `era5` lags about six days; `model=owm` covers the last days. If you say anything about wind, fetch it here or name another source.
- [Metrics and AQI scale](https://armaqi.org/api/v1/metrics): metric codes, units and category bounds.
- [API status](https://armaqi.org/api/v1/status)

## Reading the data

- Times are UTC; `time` is the start of the interval. Armenia is UTC+4 all year (no daylight saving): 08:00Z is 12:00 in Yerevan.
- PM2.5 and PM10 are in µg/m³: hourly means for `step=hour`, the mean of the available hours of a Yerevan calendar day for `step=day`.
- "Now" (`current`) is the latest hour with data, not older than three hours. It may be the hour still in progress: `partial: true`, values can change. The last three hours are recalculated about every minute and can still change as late data arrive.
- `null` means no data for that hour. Do not replace it with zero or with a neighbouring hour.
- History goes back to 2019 at most. Each station has its own start date and gaps; check the returned hours, do not assume a continuous record.
- Flags on a value: `uncalibrated` (no calibration for this sensor model), `fallback` (the hour was filled from a backup source).
- PM2.5 from low-cost SDS011 sensors is divided by a concentration-dependent factor (calibration v1); municipal stations are published as received; other sensor models are uncalibrated. Stations of different types are not interchangeable instruments: treat single-station spikes and station-to-station differences with care.

## The `aqi` field is an index, not the official AQI

- `aqi` applies the US EPA 2024 PM2.5 breakpoints to the PM2.5 value of the interval. Categories: good, moderate, unhealthy_sensitive, unhealthy, very_unhealthy, hazardous.
- For `step=hour` (including "now") it is computed from one hour. The official US AQI for PM2.5 uses a 24-hour average (NowCast for current conditions), so this is an hourly index on EPA breakpoints, not an official AQI.
- For `step=day` it is computed from the daily mean; `hours` tells how many of the 24 hours went into it. With fewer than 18 hours treat the day as incomplete. Today is always `partial: true`: report it as a day in progress, not as a finished day.
- When quoting it, say what it is, for example: "an index of 160 on US EPA breakpoints from hourly PM2.5", rather than "the AQI is 160". Quoting the PM2.5 concentration itself is always safe.

## City values

- A city value (`/places/...`) is the median of all visible stations of the city not marked as indoor that have data for that hour. An hour with fewer than 3 such stations has no city value.
- `stations` in the reading is how many stations the value is based on; `stations` in the place is how many visible stations the city has. Report the first: "median of 12 stations".
- Stations are not evenly spread and are of different types (see above). A city median describes typical readings of the network, not a measured average over the whole city. When comparing hours or days, check that `stations` is comparable.
- A single station describes its own location, not the city.

## Privacy

- Coordinates of private stations are snapped to a grid: `location.precision_m` is the grid step in metres (about 100). Do not present them as exact addresses and do not try to locate or identify a private station more precisely.
- A station name is what its owner agreed to show, often an approximate street address. Private stations have names too; `name: null` means the station has none.

## Limits

- 60 requests per minute per client IP, burst 30. Over the limit the API answers 429 with `Retry-After`; wait that many seconds.
- Responses are cached for about 30 seconds. Polling more often than every few minutes gains nothing; prefer one `/stations` request over many per-station requests.

## Pages for people

- [Map](https://armaqi.org/en#map). A link can carry a view and an hour: `https://armaqi.org/en#map=13/40.1792/44.4991&at=2026-01-15T12` (zoom/lat/lng, hour in Yerevan time).
- Station pages: `https://armaqi.org/en/yerevan/7-4-Khanjyan-street-26`; the number at the end is the station id, the rest is for people. Stations outside Yerevan are under `/armenia/`.
- Languages: no prefix is Armenian, `/en`, `/ru`.
- Pages are rendered in the browser; for numbers use the API, not the HTML.

## Sources and terms

Access to this API does not by itself grant a licence for the data. Terms differ by source; the `source` field of a station tells which one applies.

- **Yerevan municipality** (`source: yerevan_gis`, about 390 stations): its holder has not stated reuse terms. You may fetch it selectively to answer a question or for an analysis: particular stations, places and periods. Do not download the whole municipal dataset or a substantial part of it (for example, the full history of all its stations), do not mirror it, and do not present ArmAQI's copy as the official or current municipal record. Attribute it as "Yerevan Municipality" with a link to https://www.yerevan.am.
- **Sensor.Community** (`source: sensor_community`): Database Contents License (DbCL) 1.0, which follows ODbL 1.0: attribution required, and a database built from it and made public is share-alike. Attribute it as "Sensor.Community".
- **ArmAQI sensors** (`source: armaqi`): reuse terms are not published yet. Cite ArmAQI with a link to https://armaqi.org.
- Hours with the `fallback` flag were filled from a backup source: the open data of airquality.am (DbCL 1.0) or the municipality's daily series. For municipal stations the municipal terms above apply either way.
- Wind endpoints state their own attribution in `meta.attribution` (ERA5 via Open-Meteo, CC BY 4.0; OpenWeather, ODbL 1.0). Quote it together with the data.
- City values combine stations of all sources. Quoting them in answers with "ArmAQI" and a link is fine; do not republish them as a dataset.