Skip to content

AQS daily summaries

epa:aqs-daily uses the dailyData service of the AQS Data API, checked on 2026-09-23 with a registered key. AQS is EPA's archive of regulatory air monitoring: state, local, and tribal agencies submit, validate, and certify the data, so it is the checked historical record, not a live feed. For today's preliminary readings use AirNow, which is a different source.

One row is one monitor's summary for one local calendar day under one pollutant standard: the mean and maximum of the day's samples, the hour of the maximum, the AQI where the standard defines one, how complete the day was, and the site's name, address, coordinates, county, and metro area.

A key is required

Every request carries an email address and a key. Register once by opening https://aqs.epa.gov/data/api/signup?email=you@example.com with your own address; EPA emails the key from aqsdatamart@epa.gov. Opening the same link again issues a new key to the same address. There is no way to delete the account yourself.

Set both variables in the environment:

export USDATA_AQS_EMAIL="you@example.com"
export USDATA_AQS_KEY="the-key-from-the-email"

Any secret manager that sets environment variables works, and so does uv run --env-file. A manifest never holds a key, and no key appears in a lockfile, provenance sidecar, cached file, dry-run line, or error message. usdata doctor reports whether both are set without printing them. Without them, fetch and pull stop before any request and name the variables. A locked restore can still come from the cache, or from a configured mirror, without asking EPA; see provenance and drift.

Selecting

  • Pollutants. -p parameters=88101 names one to five AQS parameter codes, comma-separated. 88101 is PM2.5 (local conditions), 44201 ozone, 42401 SO2, 42602 NO2, and 42101 CO; the full list comes from the service's list/parametersByClass endpoint. More than five is refused: split them across manifest sources.
  • Place, exactly one of:
    • --location "Queens County, NY" or --location "New York": the county or state exactly, through byCounty or byState. A county's bounding box would take in monitors in its neighbours (ADR 0034).
    • -p sites=36-081-0124: AQS site ids, state-county-site, one request each.
    • --bbox or --lat/--lon: the monitors inside the box, through byBox.
  • Dates. Both are required. Their UTC calendar dates select AQS date_local days, inclusive. date_local is a day in the monitor's local standard time, not a UTC interval, and the reader leaves it as a naive date.
  • Years. The service refuses a request that spans two calendar years, so each year the window touches is its own request and its own file.
  • variables is refused: the columns are fixed. Free text is refused as everywhere.
usdata fetch epa:aqs-daily --start 2023-06-01 --end 2023-06-15 --location "Queens County, NY" -p parameters=88101
usdata fetch epa:aqs-daily --start 2023-01-01 --end 2023-12-31 -p sites=36-081-0124 -p parameters=88101,44201

What arrives

A JSON file per selection and year, named aqs-daily_<selection>_<codes>_<first day>_<last day>.json. It is not the bytes as sent. The service's header echoes the whole request, key included, and its request_time and the order of the rows change between identical requests. A checksum could not pin that, so the adapter writes a canonical form: the header without url and request_time, the rows sorted by site, parameter, POC, local date, duration, standard, method, and event type, and the JSON with sorted keys. Each provenance sidecar records this step under transformations (ADR 0039).

item.open() returns a pandas DataFrame with one row per element of Data, the columns named as the service names them. date_local and date_of_last_change are parsed as naive dates, identifiers such as state_code, county_code, and site_number stay text, and the header is in frame.attrs["usdata"]["header"].

Reading the rows

Several rows can describe one monitor on one day. Pick the ones a question needs before averaging or counting:

  • pollutant_standard. A PM2.5 day appears once per standard it is compared with (the 1997, 2006, 2012, and 2024 standards, 24-hour and annual), eight rows in the Queens probe, and once with no standard for the hourly series. Filter to one, such as PM25 24-hour 2024.
  • sample_duration. Continuous monitors report 1 HOUR samples, summarized again as 24-HR BLK AVG; filter-based samplers report 24 HOUR.
  • event_type. A day an agency flagged as an exceptional event, such as wildfire smoke, appears as Events Included and again as Concurred Events Excluded (or Events Excluded). Keep No Events plus Events Included to see what was measured; the excluded rows are what the regulatory design value uses.
  • poc. Parameter occurrence code: more than one instrument can measure the same pollutant at one site.
  • validity_indicator and observation_percent say whether the day met completeness criteria.

What the service does not say

  • A mistyped code looks like no data. An unknown parameter code, such as 99999, returns the same No data matched your selection as a valid code with no monitors in the place. Both are written as a file with no rows. Check the code if a query comes back empty.
  • It is slow. Ten days of PM2.5 for one county took about two minutes. A state-year of a common pollutant takes much longer and can be tens of megabytes. The read timeout is ten minutes.
  • It limits callers. EPA asks for one request at a time, at most ten a minute, and a pause between them, and may disable an account that ignores this. The adapter waits until six seconds have passed since the previous request started, across every adapter in the process. Two processes sharing a key are not coordinated.
  • Values are revised. Agencies can change submitted data, and each row carries date_of_last_change. A revised day changes its year's file, which a locked restore reports as drift; pull --update accepts it.
  • Refusals. A request the service refuses answers with a Failed header and a reason, usually with a 4xx status. usdata raises AqsError, a QueryError (CLI exit 2), with that reason and without the key.
  • Sizes are not known before download; --dry-run lists the requests, and needs the key set only because the adapter cannot be built without it.

Metadata sources

Every value in the catalog entry's resolution, cadence, citation, terms, variables, and limits comes from one of these pages. A field the agency does not publish is left empty rather than estimated.

  • The services, filters, limits, signup, and output format: the AQS Data API documentation, including its request limits and terms of service.
  • Variable descriptions: the service's own field list, from metaData/fieldsByService?service=dailyData.
  • Latency and cadence: agencies must submit each calendar quarter's data within 90 days after it ends (40 CFR 58.16), and certify the previous year by May 1 (40 CFR 58.15).
  • Citation: EPA's AirData FAQ has a question on citing its data whose answer did not load when checked, so the entry uses the "Agency, Product, accessed via usdata" form.
  • License: the data is a work of the U.S. Government.
  • No window limit is declared: the adapter splits a window by year and enforces no longest one.

EPA access notes.

Reference

epa:aqs-daily · Released · Included since usdata 0.26. Air Quality System Daily Summaries.

At a glance

Parameters

Pass these as --param name=value to the CLI, as params: entries in a manifest, or as keyword arguments to build_query.

Parameter Meaning
parameters Required AQS parameter code(s), one to five, such as 88101 (PM2.5) or 44201 (ozone).
sites AQS site id(s) as state-county-site, such as 36-081-0124; or use a location.

Variables

Variable Units Meaning
state_code — FIPS code of the state the monitor is in; 80 for Mexico, CC for Canada at border sites
county_code — FIPS code of the county, parish, or independent city within the state
site_number — Four-digit site number, unique within the county
parameter_code — AQS code of the parameter measured
poc — Parameter occurrence code distinguishing instruments measuring the same parameter at one site
latitude degrees_north Site latitude, WGS84
longitude degrees_east Site longitude, WGS84
datum — Datum of the coordinates, always WGS84
parameter — Name of the parameter measured
sample_duration_code — Code of the sample duration
sample_duration — Averaging period: observed, such as 1 HOUR or 24 HOUR, or calculated, such as 24-HR BLK AVG
pollutant_standard — National ambient air quality standard the row's statistics are calculated for; empty for none
date_local — Day the sample was taken, in local standard time
units_of_measure — Units of every statistic on the row
event_type — Whether exceptional-event data are included: No Events, Events Included, Events Excluded, or Concurred Events Excluded
observation_count — Number of observations in the averaging period
observation_percent percent Share of scheduled values for the day that were reported
validity_indicator — Y where the value meets all completeness criteria
arithmetic_mean — Mean of the day's values, in units_of_measure
first_max_value — Highest value at the row's duration or standard, in units_of_measure
first_max_hour — Hour of the day, 24-hour local standard time, of the highest value
aqi — Air Quality Index for the day, where the pollutant has one
method_code — Three-digit measurement method code, unique within a parameter
method — Collection and analysis method
local_site_name — Site name in the operating agency's own nomenclature
site_address — Approximate street address of the site
county — Name of the county the site is in
state — Name of the state the site is in
city — Incorporated city the site is in, if any
cbsa_code — Code of the core-based statistical (metropolitan) area
cbsa — Name of the core-based statistical (metropolitan) area
date_of_last_change — Date the underlying data were last changed in AQS

Catalog facts

  • Availability: since 0.26
  • Domain: Air quality
  • Spatial resolution: Regulatory monitoring sites operated by state, local, and tribal agencies
  • Temporal resolution: Daily summaries of each monitor's samples, one row per pollutant standard
  • Updates: As monitoring agencies submit each quarter (40 CFR 58.16) and certify the previous year by May 1 (40 CFR 58.15); submitted values can be revised later
  • Latency: Agencies must submit each calendar quarter's data within 90 days after it ends (40 CFR 58.16)
  • Terms of use: https://aqs.epa.gov/aqsweb/documents/data_api.html#terms
  • Citation: U.S. Environmental Protection Agency, Air Quality System (AQS) daily summary data, AQS Data API, accessed via usdata
  • Coverage: not specified in the catalog
  • Coverage varies by station, product, and date; the range above does not guarantee observations.
  • Upstream documentation
  • License: US Government Work (public domain)
  • Transport: http
  • Adapter: usdata.providers.epa.aqs:AqsDaily