The Breathe API

Getting started

Every endpoint is a plain GET on https://api.breatheoss.app, and nothing needs a header, a token or a body, so the quickest way to see what the API gives you is to open a URL in your browser or run it through curl. The request below asks for the current air in Srinagar.

curl https://api.breatheoss.app/aqi/zone/srinagar

You'll get back one JSON object with the current AQI on both the US EPA and the Indian CPCB scales, the raw pollutant concentrations behind them, an hourly history of the last 24 hours, every sensor in the zone with its own reading and the current weather. The full shape is documented under /aqi/zone/{zone_id}.

If you don't know the zone IDs yet, start with /zones, which lists all of them along with their coordinates and whether they're backed by ground sensors or by satellite estimates. For anything more than a couple of zones, use /aqi/zones instead of calling each one separately (it's one request instead of twenty five, and it's what our own apps do now).

Concepts

Zones and sensors

The API is organised around zones, and a zone is a town or a city (Srinagar, Jammu, Leh, Kargil and so on) with an ID like srinagar or jammu_city. Some zones have one or more physical sensors inside them, and the API calls each of those sensors a node. A zone with six nodes reports the average of whichever ones are healthy at that moment, and every node is also listed on its own so you can see how much the air differs from one neighbourhood to the next (which, in a city like Srinagar, is quite a lot).

Zone IDs are meant to stay the same once a zone is live, but new zones do get added as people host sensors, so read the list from /zones instead of hardcoding it.

Ground sensors and satellite estimates

Every zone has a provider, which is either airgradient or openmeteo. An airgradient zone has real AirGradient sensors on rooftops and balconies measuring PM2.5 and PM10 every few minutes, and these are what we'd recommend trusting first. An openmeteo zone has no sensor yet, so its numbers come from the Open-Meteo air quality API, which is a model built on satellite data and not a measurement of the street you're standing on.

The sensors only measure particulates, so the gases (NO₂, SO₂, CO and methane) always come from Open-Meteo, even in a sensor zone. That's why a sensor zone's source reads something like airgradient (5/6 sensors) + openmeteo.

If every sensor in a zone goes offline, or the readings look broken (more on that under spike protection), the zone quietly falls back to Open-Meteo for that refresh, its source changes to openmeteo air pollution api and warning says why. So provider tells you what a zone normally uses, and source tells you what this particular response actually used.

Two AQI scales

Every AQI value comes in two versions, us_aqi on the US EPA scale and aqi on the Indian CPCB scale. Both run from 0 to 500, but they cut the range up very differently, and the same air can easily read 141 on the US scale and 84 on the Indian one. The Breathe apps lean on the US scale because its PM2.5 bands are much stricter (and in our opinion, much closer to what the health research actually says), but both are always there and you can pick whichever suits you. The bands for each are listed under AQI scales.

Time and units

Timestamps are Unix seconds in UTC (ts, timestamp_unix), except for the calendar windows on the history endpoints, which are read as dates in IST because every zone sits in IST. Concentrations are in µg/m³, apart from CO and methane, which are in mg/m³. Temperature is in °C, humidity is relative humidity in percent and precipitation is in millimetres.

How fresh the data is

A background job refreshes every zone every 15 minutes, which lines up with how often the sensors report and keeps us well inside Open-Meteo's rate limits. Live requests are served from that cache, so calling /aqi/zone/srinagar every few seconds won't give you anything newer, and polling more often than every 5 to 15 minutes is just wasted traffic. A sensor reading older than an hour is treated as the sensor being down, not as the current state of the air.

History, weather and seasonal responses are cached for longer (an hour for history and weather, six hours for seasonal), so the newest bucket in a history response can lag the live reading by up to an hour.

Browsers and limits

The API sends CORS headers only for our own sites (breatheoss.app, about.breatheoss.app and localhost on ports 3000 and 8080 for development). Server side code, scripts, bots, notebooks and mobile apps aren't affected by this at all, but a web page on another domain calling the API straight from the browser will be blocked. If that's what you're building, put a small proxy in front of it (a Cloudflare Worker is enough) or tell us your domain and we'll look at adding it.

There's no rate limit or quota on our side right now. That said, the API runs on a single small Heroku dyno, so please cache what you can, use /aqi/zones instead of looping over zones, and don't hammer /historical-data with year long ranges at 15 minute intervals in a loop. If you're planning something heavy (a public dashboard with a lot of traffic, a research project pulling the full archive), drop us a message first, we're happy to help.

Responses over about 1 KB are gzipped if your client asks for it, which every browser and curl --compressed does.

Endpoints

{
  "zones": [
    {
      "id": "jammu_city",
      "name": "Jammu",
      "provider": "airgradient",
      "lat": 32.7169,
      "lon": 74.8609,
      "zone_type": "urban"
    },
    {
      "id": "anantnag_city",
      "name": "Anantnag",
      "provider": "openmeteo",
      "lat": 33.7295,
      "lon": 75.15,
      "zone_type": "hills"
    }
  ]
}

{
  "zone_id": "srinagar",
  "zone_name": "Srinagar",
  "source": "airgradient (5/6 sensors) + openmeteo",
  "timestamp_unix": 1794432223.32853,
  "coordinates": { "lat": 34.0709, "lon": 74.8122 },
  "averages_24h": {
    "pm2_5": 84.9,
    "pm10": 104.5,
    "temp": 15.4,
    "humidity": 59.6,
    "aqi": 179,
    "us_aqi": 171
  },
  "history": [
    {
      "ts": 1794427200,
      "aqi": 189,
      "us_aqi": 173,
      "pm2_5": 87.06,
      "pm10": 116.48,
      "temp": 10.54,
      "humidity": 72.6
    },
    {
      "ts": 1794430800,
      "aqi": 182,
      "us_aqi": 172,
      "pm2_5": 85.58,
      "pm10": 114.14,
      "temp": 10.16,
      "humidity": 73.6
    }
  ],
  "warning": null,
  "nodes": {
    "Kanipora": {
      "pm2_5": 90.3,
      "pm10": 120.2,
      "temp": 9.4,
      "humidity": 75.0,
      "aqi": 200,
      "us_aqi": 175,
      "history": [],
      "status": "active"
    },
    "Ahmadnagar": {
      "pm2_5": null,
      "pm10": null,
      "temp": null,
      "humidity": null,
      "aqi": null,
      "us_aqi": null,
      "status": "stale",
      "history": []
    }
  },
  "weather": {
    "condition": "smog",
    "weather_code": 45,
    "precipitation": 0.0,
    "season": "autumn",
    "text": "Cold, stagnant air is trapping smoke and particulates near the ground. Consider limiting outdoor activity."
  },
  "aqi": 182,
  "us_aqi": 172,
  "main_pollutant": "pm2_5",
  "us_main_pollutant": "pm2_5",
  "aqi_breakdown": { "pm2_5": 182, "pm10": 109, "no2": 22, "so2": 5, "co": 20 },
  "concentrations_us_units": {
    "pm2_5": 85.58,
    "pm10": 114.14,
    "ch4": 1.58,
    "no2": 18.9,
    "so2": 4.9,
    "co": 0.49
  },
  "zone_applied": "urban"
}

curl "https://api.breatheoss.app/aqi/zones?ids=srinagar,leh"

curl "https://api.breatheoss.app/historical-data/jammu_city/6h/1h/pm2.5,pm10"

{
  "data": [
    { "zone_id": "jammu_city", "ts": 1794409200, "pm2_5": 213.96, "pm10": 230.83 },
    { "zone_id": "jammu_city", "ts": 1794412800, "pm2_5": 181.29, "pm10": 196.83 },
    { "zone_id": "jammu_city", "ts": 1794430800, "pm2_5": 111.26, "pm10": 122.64 }
  ],
  "stats": {
    "max_pm2_5": 213.96,
    "min_pm2_5": 111.26,
    "avg_pm2_5": 148.72,
    "max_pm10": 230.83,
    "min_pm10": 122.64,
    "avg_pm10": 161.56
  }
}

{
  "interval": 21600,
  "anchor": 0,
  "points": [
    { "ts": 1794333600, "condition": "cloudy", "precipitation": 0.0 },
    { "ts": 1794355200, "condition": "rain", "precipitation": 0.9 },
    { "ts": 1794376800, "condition": "clear", "precipitation": 0.0 },
    { "ts": 1794398400, "condition": "rain", "precipitation": 0.1 },
    { "ts": 1794420000, "condition": "fog", "precipitation": 0.0 }
  ],
  "zone_id": "srinagar"
}

{
  "zone_id": "srinagar",
  "zone_name": "Srinagar",
  "current_month": 11,
  "current_season": "autumn",
  "months": [
    {
      "month": 1,
      "name": "January",
      "season": "winter",
      "pm2_5": 70.8,
      "pm10": 92.6,
      "aqi": 131,
      "us_aqi": 161,
      "precipitation": 113.2,
      "temp": -0.8,
      "sensor_pm2_5": 95.5,
      "sensor_pm10": 125.8
    },
    {
      "month": 12,
      "name": "December",
      "season": "winter",
      "pm2_5": 61.8,
      "pm10": 78.7,
      "aqi": 101,
      "us_aqi": 155,
      "precipitation": 84.7,
      "temp": 1.6
    }
  ],
  "source": "openmeteo reanalysis (2022-present)"
}

{ "status": "ok", "postgres": "ok", "redis": "ok" }

Time ranges and intervals

/historical-data and /weather-history take the same time_range and interval syntax. A rolling range ends now and is written as a number followed by a unit.

Watch out for m against mo, because 1m is one minute and 1mo is a month. A unit the API doesn't recognise falls back to one day without telling you, so a typo won't error out, it'll just give you the wrong window.

Calendar windows

time_range can also be a fixed window, which is handy for "show me last October" or for comparing the same week across years. Dates are read in IST and buckets are counted from the start of the window, so a 1d interval on a calendar window gives you buckets that start at local midnight.

A window that doesn't parse, ends before it starts or begins before the year 2000 returns 400 with a detail that shows the accepted formats. Our archive starts in late 2025, when the first sensor went up, so anything earlier is simply empty.

curl "https://api.breatheoss.app/historical-data/jammu_city/2026-W42/1h/pm2.5,pm10?format=csv" -o jammu-w42.csv

How the numbers are made

You don't need any of this to use the API, but if you're doing research or comparing our numbers against another source, this is what happens between the sensor and the JSON. All of it is in the open in the API repository if you'd rather read the code.

From concentration to AQI

Each pollutant gets its own sub index, and that comes from finding which band of the official breakpoint table its concentration falls into, then interpolating in a straight line inside that band.

Here C is the concentration, C_lo and C_hi are the edges of the band it falls in, and I_lo and I_hi are the index values at those edges. As a worked example, take 85.6 µg/m³ of PM2.5 on the US scale. That lands in the 55.5 to 125.4 band, which maps to 151 to 200, so the sub index is (200 - 151) / (125.4 - 55.5) × (85.6 - 55.5) + 151, which comes to about 172.

The overall AQI is the highest sub index, not an average, and the pollutant behind it is reported as us_main_pollutant (or main_pollutant for the Indian scale). A concentration above the top band is capped at 500. For the US scale, gases are converted from µg/m³ to ppb (or ppm for CO) at 25 °C first, and PM2.5 is truncated to one decimal before the lookup, the way the EPA does it. For the Indian scale, CO and methane are converted to mg/m³. Methane is reported but isn't part of either index.

The top level aqi and us_aqi are worked out from the current concentrations, so they react to a spike right away. The official definitions use a 24 hour average for particulates instead, and that version is in averages_24h, which is the one to use if you're comparing against government stations.

Spike protection

Low cost sensors on someone's balcony get things blown on them, sprayed near them and occasionally set on fire next to them, and one bad reading can drag a whole zone into "hazardous". So before a sensor's reading is used, it's checked against a few limits.

• A reading above 600 µg/m³ of PM2.5 or 900 of PM10 is thrown out, since real air in these zones doesn't get there.
• A PM2.5 jump of more than 200 µg/m³ inside an hour is treated as local interference and thrown out. From October to February the limit is 300, because cold nights with heating smoke and temperature inversions really do push the air up that fast.
• A sensor that trips either check is left out of its zone for an hour (its status is grace_period during that time) so it can't flicker back in on the next refresh.
• During Diwali (the dates are kept in the API's festivals.json), the jump check is turned off and the ceilings go up to the sensor's hardware limit of 999, because firecracker spikes on those nights are real and filtering them out would hide exactly what people want to see.

If every sensor in a zone is filtered or offline, the zone falls back to Open-Meteo for that refresh, as described in ground sensors and satellite estimates.

Node statuses

Warnings

warning is null most of the time. When it isn't, it's plain text meant to be shown to people as is, and it comes from one or both of two places. The first is the sensors, when one or more of them were dropped and the zone is running on fewer sensors or on satellite data (like Physical sensor temporarily offline. Using satellite-based estimates from Open-Meteo.). The second is the zone as a whole, when its reading went past the spike ceilings or its AQI rose by more than 150 in the last hour (200 from October to February), which gets a general note that the reading may not reflect the whole region. If both apply, the sensor note comes first and the two are separated by a blank line.

The exact wording isn't part of the contract and may change, so check whether warning is null instead of matching on the text.

AQI scales

These are the bands each scale uses. The colours match the Breathe apps, so feel free to use them if you'd like your project to look consistent with ours.

US EPA (us_aqi)

The PM2.5 bands are the 2024 revision, where "good" tops out at 9.0 instead of the older 12.0.

Indian CPCB (aqi)

Put the two tables side by side and the difference is pretty obvious, since 55 µg/m³ of PM2.5 is "unhealthy for sensitive groups" on the US scale but still "satisfactory" on the Indian one. The full tables for every pollutant are in aqi_breakpoints.json (Indian) and conversions.py (US).

Errors

Errors come back as JSON with a detail string, which is FastAPI's standard shape.

{ "detail": "zone not found" }

When an upstream source (AirGradient or Open-Meteo) has a bad moment, the live endpoints serve the last good reading for the zone instead of an error, so an older timestamp_unix is the thing to look out for there, not a status code.

Code examples

JavaScript

Current US AQI for every zone, worst first. This runs as is in Node 18 or later, or anywhere else with fetch (just not from a browser on another domain, because of CORS).

const res = await fetch('https://api.breatheoss.app/aqi/zones');
const { zones } = await res.json();

zones
  .sort((a, b) => b.us_aqi - a.us_aqi)
  .forEach((z) => {
    console.log(`${z.zone_name.padEnd(12)} ${z.us_aqi}  (${z.source})`);
  });

Python

A month of hourly PM2.5 for Jammu as a pandas DataFrame, using the CSV output.

import pandas as pd

url = "https://api.breatheoss.app/historical-data/jammu_city/2026-10/1h/pm2.5,pm10?format=csv"
df = pd.read_csv(url)
df["time"] = pd.to_datetime(df["ts"], unit="s", utc=True).dt.tz_convert("Asia/Kolkata")

print(df.set_index("time")["pm2_5"].resample("1D").mean())

Shell

Just the number, for a status bar or a cron job.

curl -s https://api.breatheoss.app/aqi/zone/srinagar | jq '.us_aqi'

Source and help

The API is MIT licensed and lives at breathe-OSS/api, and its README covers running it yourself (you'll need Python 3.10 or later and a Redis server). If something on this page doesn't match what the API actually does, that's a bug in one of the two, so please open an issue there.

For questions, or to tell us what you've built (we'd genuinely love to see it), the quickest place is our Discord, or you can write to [email protected]. If you use the data in research or in something public, a link back to breatheoss.app is appreciated, and it helps more people find the network and maybe host a sensor of their own.