AQS API | AirData | US EPA - Chuyên Trang Chia Sẻ Kiến Thức Thời Trang Mới Nhất

Welcome to the AQS API (version 2).

This API is the primary place to obtain row-level data from the EPA’s Air Quality System (AQS) database. If you would
like aggregated or visual data from AQS, or large files of pre-extracted data,
AirData
is the place to start.

AQS contains ambient air sample data collected by state, local, tribal, and federal air pollution control
agencies from thousands of monitors around the nation. It also contains meteorological data, descriptive
information about each monitoring station (including its geographic location and its operator), and
information about the quality of the samples.
More about AQS.
Note, AQS does not contain real-time air quality data (it can take 6 months or more from
the time data is collected until it is in AQS). For real-time data, please visit the
AirNow API

Data from this API is available to anyone but is targeted at application developers and data analysts who
are familiar with the data and its interpretation. You must sign up to obtain a key to use the API.

The remainder of this page contains a description of the services, how to construct them, and examples.
We also have OpenAPI specifications (json)
available.

Please email us with any suggested changes to the API or documentation.

On this page

Services Overview

This table lists the services available and the type of data each one provides.
Each is linked to detailed construction rules and examples.

Top of Page

Variables used in service requests

These are the variables you will use to construct your request. See the details below about which variables are
required and which are optional for each request type. If a variable contains text, that text is case sensitive.
For example, if using the parameter class for CRITERIA pollutants, it must be in all upper case.

Variable
Description
Example

email
The email address of the requester.
[email protected]

key
The key matching the email address for the requester. This is provided at registration. (This is not referred
to as a password since it is not used for authentication, but only account monitoring.)
notarealkey

The begin date of the data selection in YYYYMMDD format. Only data on or after this date will be returned. (Note, for annual data, only the year portion of the bdate and edate are used and only whole years of data are returned. For example, bdate = 20171231 and edate = 20180101 will return full data for 2017 and 2018.)
20170101

The end date of the data selection in YYYYMMDD format. Only data on or before this date will be returned. The end date must be in the same year as the begin date. This rule does not apply to the Monitors service. (Note, for annual data, only the year portion of the bdate and edate are used and only whole years of data are returned. For example, bdate = 20170531 and edate = 20170630 will return full data for 2017.)
20171231

param
The AQS parameter code for the data selection. AQS uses proprietary 5 digit codes. They may be obtained via the
list parameters service. Up to 5 parameters may be requested, separated by commas. Only data for these parameters will be returned.
81101,44201

state
The 2 digit state FIPS code for the state (with leading zero). They may be obtained via the
list states service. Only data from within this state will be returned.
01

county
The 3 digit state FIPS code for the county within the state (with leading zeroes). They may be obtained via the
list counties service. Only data from within this county will be returned.
089

site
The 4 digit AQS site number within the county (with leading zeroes). They may be obtained via the
list sites service. Only data from this site will be returned.
0014

duration
The 1-character AQS sample duration code. This is an optional variable (on the Sample Data service only)
that limits returned data to that specific sample duration. (Since these are sample durations, calculated
durations do not apply – you cannot get 8-hour ozone this way, for example.) A list of valid duration codes
may be viewed on this page,
and the “Observed” durations are valid entries. Not all parameters are measured
at all durations. Only data reported at this sample duration will be returned.
1

cbsa
The 5 digit AQS Core Based Statistical Area code (as defined by the census bureau, with leading zeroes).
They may be obtained via the list cbsas service. Only data from this area will be returned.
16740

minlat
The minimum latitude of a geographic box. Decimal latitude with north being positive.
Only data north of this latitude will be returned.
36.42348

maxlat
The maximum latitude of a geographic box. Decimal latitude with north being positive.
Only data south of this latitude will be returned.
36.8

minlon
The minimum longitude of a geographic box. Decimal longitude with east being positive.
Only data east of this longitude will be returned.
-85.4

maxlon
The maximum longitude of a geographic box. Decimal longitude with east being positive.
Only data west of this longitude will be returned. Note that -80 is less than -70.
-85.1

Each value in our database has a “date of last change” that indicates when it was last updated. The cbdate is used to
filter data based on the change date, cbdate = change begin date in YYYYMMDD format. Only data that changed on
or after this date will be returned.
20180101

Each value in our database has a “date of last change” that indicates when it was last updated. The cedate is used to
filter data based on the change date, cedate = change end date in YYYYMMDD format. Only data that changed on
or before this date will be returned.
20180101

pqao
The 4 digit AQS Primary Quality Assurance Organization code (with leading zeroes). They may be obtained via the
list pqaos service. Only data for this PQAO will be returned. Only used in QA Data services.
0001

ma
The 4 digit AQS Monitoring Agency code (with leading zeroes). They may be obtained via the
list mas service. Only data for this Monitoring Agency will be returned. Only used in QA Data services.
1189

pc
The AQS parameter class name. Parameter Classes are a way to group like parameters. They may be obtained via the
list classes service. Only used in the list parameters service.
CRITERIA

Top of Page

Service Details and Examples

This section describes each service, required and optional variables, and gives some usage examples.

Please note, for the examples we use a test account that has a limited number of uses per day.
If that limit is exceeded, you will get an error message rather than data.
Please register for your own account if you want to use the services.

The required and optional variables may be submitted in any order.

This service creates an account or resets a password. Requires validation of registered email address. Email will
be sent to the registered address from [email protected].

Service
Filter
Endpoint
Required Variables
Optional Variables

signup
email

Examples:

Use this service to register as a user. A verification email will be sent to the email account specified. To
register using the email address “[email protected]” create and request this link (Replace
“[email protected]” in the example with your email address.):

https://aqs.epa.gov/data/api/[email protected]

To reset a key: If the request is made with an email that is already registered, a new key
will be issued for that account and emailed to the listed address. Usage is the same as above.

Returns information about the API. Note, is it not necessary to check the API
availibility before each service request (the system does this internally and
will return an error message if there is a problem). The intent of this
service is to let you know the system is up before you start a long job.

Service
Filter
Endpoint
Required Variables
Optional Variables

MetaData
Is the API available for use?
metaData/isAvailable

email, key

Example:

To check if the API is up and running:

https://aqs.epa.gov/data/api/metaData/isAvailable

Revision History
metaData/revisionHistory
email, key

Examples:

Returns a complete list of revisions to the API in reverse chronological order:

https://aqs.epa.gov/data/api/metaData/[email protected]&key=test

Returned Fields by Service
metaData/fieldsByService
email,
key,
service

Examples:

Returns a list and definitions of fields in the Sample Data service:

https://aqs.epa.gov/data/api/metaData/[email protected]&key=test&service=sampleData

Returns a list and definitions of fields in the List service:

https://aqs.epa.gov/data/api/metaData/[email protected]&key=test&service=list

Known Issues
metaData/issues
email,
key

Examples:

Returns a list of any known issues with system functionality or the data.
These are usually issues that have been identified internally and
will require some time to correct in our system or database.

https://aqs.epa.gov/data/api/metaData/[email protected]&key=test

Lists

This service provides the variable values you many need to create other service requests.
All outputs are a value or code and the definition of that value.

Service
Filter
Endpoint
Required Variables
Optional Variables

List
States
list/states
email,
key

Returns a list of the states and their FIPS codes used for constructing other requests:

https://aqs.epa.gov/data/api/list/[email protected]&key=test

Counties by State
list/countiesByState
email,
key,
state

Example; returns all counties in North Carolina:

https://aqs.epa.gov/data/api/list/[email protected]&key=test&state=37

Sites by County
list/sitesByCounty
email,
key,
state,
county

Example; returns all sites in Wake County, NC:

https://aqs.epa.gov/data/api/list/[email protected]&key=test&state=37&county=183

CBSAs (Core Based Statistical Areas)
list/cbsas
email,
key

https://aqs.epa.gov/data/api/list/[email protected]&key=test

Parameter Classes (groups of parameters, like criteria or all)
list/classes
email,
key

https://aqs.epa.gov/data/api/list/[email protected]&key=test

Parameters in a class (obtain the list of classes from the List – Parameter Classes service)
list/parametersByClass
email,
key,
pc

Example; returns all parameters in the CRITERIA class:

https://aqs.epa.gov/data/api/list/[email protected]&key=test&pc=CRITERIA

PQAOs (primary quality assurance organizations)
list/pqaos
email,
key

https://aqs.epa.gov/data/api/list/[email protected]&key=test

MAs (monitoring agencies)
list/mas
email,
key

https://aqs.epa.gov/data/api/list/[email protected]&key=test

Monitors

Returns operational information about the samplers (monitors) used to collect the
data. Includes identifying information, operational dates, operating organizations,
etc.

Service
Filter
Endpoint
Required Variables
Optional Variables

Monitors
By Site
monitors/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns list of SO2 monitors at the Hawaii Volcanoes NP site (#0007) in Hawaii County, HI that were operating on May 01, 2015. (Note, all monitors that operated between the bdate and edate will be returned):

https://aqs.epa.gov/data/api/monitors/[email protected]&key=test&param=42401&bdate=20150501&edate=20150502&state=15&county=001&site=0007

By County
monitors/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns all SO2 monitors in Hawaii County, HI that were operating on May 01, 2015:

https://aqs.epa.gov/data/api/monitors/[email protected]&key=test&param=42401&bdate=20150501&edate=20150502&state=15&county=001

By State
monitors/byState
email,
key,
param,
bdate,
edate,
state

Example; returns SO2 monitors in Hawaii that were operating on May 01, 2015:

https://aqs.epa.gov/data/api/monitors/[email protected]&key=test&param=42401&bdate=20150501&edate=20150502&state=15

By Box
monitors/byBox
email,
key,
param,
bdate,
edate,
minlat,
maxlat,
minlon,
maxlon

Example; returns all ozone monitors in the vicinity of central Alabama that operated in 1995:

https://aqs.epa.gov/data/api/monitors/[email protected]&key=test&param=44201&bdate=19950101&edate=19951231&minlat=33.3&maxlat=33.6&minlon=-87.0&maxlon=-86.7

By CBSA
monitors/byCBSA
email,
key,
param,
bdate,
edate,
cbsa

Example; returns NO2 monitors for the Charlotte-Concord-Gastonia, NC-SC CBSA that were operating on January 01, 2017:

https://aqs.epa.gov/data/api/monitors/[email protected]&key=test&param=42602&bdate=20170101&edate=20170101&cbsa=16740

Sample Data

Returns sample data – the finest grain data reported to EPA.

Service
Filter
Endpoint
Required Variables
Optional Variables

Sample Data
By Site
sampleData/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site
duration,
cbdate,
cedate

Example; returns all ozone data for the Millbrook School site (#0014) in Wake County, NC for June 18, 2017:

https://aqs.epa.gov/data/api/sampleData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&state=37&county=183&site=0014

Example; returns all ozone data for the Millbrook School site (#0014) in Wake County, NC for June 18, 2017 that changed after January 01, 2018 (and before the end of 2018):

https://aqs.epa.gov/data/api/sampleData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&cbdate=20180101&cedate=20181231&state=37&county=183&site=0014

By County
sampleData/byCounty
email,
key,
param,
bdate,
edate,
state,
county
duration,
cbdate,
cedate

Example; returns all FRM/FEM PM2.5 data for Wake County, NC between January and February 2016:

https://aqs.epa.gov/data/api/sampleData/[email protected]&key=test&param=88101&bdate=20160101&edate=20160228&state=37&county=183

By State
sampleData/byState
email,
key,
param,
bdate,
edate,
state
duration,
cbdate,
cedate

Example; returns all benzene samples from North Carolina collected on May 15th, 1995:

https://aqs.epa.gov/data/api/sampleData/[email protected]&key=test&param=45201&bdate=19950515&edate=19950515&state=37

By Box
sampleData/byBox
email,
key,
param,
bdate,
edate,
minlat,
maxlat,
minlon,
maxlon
duration,
cbdate,
cedate

Example; returns all ozone samples in the vicinity of central Alabama for the first two days in May, 2015:

https://aqs.epa.gov/data/api/sampleData/[email protected]&key=test&param=44201&bdate=20150501&edate=20150502&minlat=33.3&maxlat=33.6&minlon=-87.0&maxlon=-86.7

By CBSA
sampleData/byCBSA
email,
key,
param,
bdate,
edate,
cbsa
duration,
cbdate,
cedate

Example; returns NO2 data for the Charlotte-Concord-Gastonia, NC-SC CBSA for January 01, 2017:

https://aqs.epa.gov/data/api/sampleData/[email protected]&key=test&param=42602&bdate=20170101&edate=20170101&cbsa=16740

Daily Summary Data

Returns data summarized at the daily level. All daily summaries are
calculated on midnight to midnight basis in local time. Variables
returned include date, mean value, maximum value, etc. Data is at
the monitor level and may include
more than one entry per monitor. There may be multiple entries for different
(1) sample durations, (2) pollutant standards.

Service
Filter
Endpoint
Required Variables
Optional Variables

Daily Summary Data
By Site
dailyData/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site
cbdate,
cedate

Example; returns daily summary ozone data for the Millbrook School site (#0014) in Wake County, NC for June 18, 2017:

https://aqs.epa.gov/data/api/dailyData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&state=37&county=183&site=0014

Example; returns all ozone daily summary data for the Millbrook School site (#0014) in Wake County, NC for June 18, 2017 that changed after January 01, 2018 (and before the end of 2018):

https://aqs.epa.gov/data/api/dailyData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&cbdate=20180101&cedate=20181231&state=37&county=183&site=0014

By County
dailyData/byCounty
email,
key,
param,
bdate,
edate,
state,
county
cbdate,
cedate

Example; returns daily summary FRM/FEM PM2.5 data for Wake County, NC in January and February 2016:

https://aqs.epa.gov/data/api/dailyData/[email protected]&key=test&param=88101&bdate=20160101&edate=20160229&state=37&county=183

By State
dailyData/byState
email,
key,
param,
bdate,
edate,
state
cbdate,
cedate

Example; returns all benzene daily summaries from North Carolina collected on May 15th, 1995:

https://aqs.epa.gov/data/api/dailyData/[email protected]&key=test&param=45201&bdate=19950515&edate=19950515&state=37

By Box
dailyData/byBox
email,
key,
param,
bdate,
edate,
minlat,
maxlat,
minlon,
maxlon
cbdate,
cedate

Example; returns ozone daily summaries in the vicinity of central Alabama for the first two days in May, 2015:

https://aqs.epa.gov/data/api/dailyData/[email protected]&key=test&param=44201&bdate=20150501&edate=20150502&minlat=33.3&maxlat=33.6&minlon=-87.0&maxlon=-86.7

By CBSA
dailyData/byCBSA
email,
key,
param,
bdate,
edate,
cbsa
cbdate,
cedate

Example; returns daily summary NO2 data for the Charlotte-Concord-Gastonia, NC-SC CBSA for January 01, 2017:

https://aqs.epa.gov/data/api/dailyData/[email protected]&key=test&param=42602&bdate=20170101&edate=20170101&cbsa=16740

Quarterly Summary

Returns data summarized at the calendar quarter level. Variables include mean value,
maxima, percentiles, etc. Data is labeled with quarter number (Q1 = Jan – Mar,
Q2 = Apr – Jun, Q3 = Jul – Sep, Q4 = Oct – Dec). All quarters for the specified year
are returned. Data is at the monitor level and may include
more than one entry per monitor. There may be multiple entries for different
(1) sample durations, (2) pollutant standards.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quarterly Summary Data
By Site
quarterlyData/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site
cbdate,
cedate

Example; returns quarterly summary ozone data for the Millbrook School site (#0014) in Wake County, NC for 2017
(Note, for quarterly data, only the year portion of the bdate and edate are used and all 4 quarters in the year are returned.):

https://aqs.epa.gov/data/api/quarterlyData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&state=37&county=183&site=0014

Example; returns all ozone quarterly summary data for the Millbrook School site (#0014) in Wake County, NC for 2017 that changed after January 01, 2018
(and before the end of 2018):

https://aqs.epa.gov/data/api/quarterlyData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&cbdate=20180101&cedate=20181231&state=37&county=183&site=0014

By County
quarterlyData/byCounty
email,
key,
param,
bdate,
edate,
state,
county
cbdate,
cedate

Example; returns quarterly summary FRM/FEM and non-FRM PM2.5 data for Wake County for 2016:

https://aqs.epa.gov/data/api/quarterlyData/[email protected]&key=test&param=88101,88502&bdate=20160101&edate=20160228&state=37&county=183

By State
quarterlyData/byState
email,
key,
param,
bdate,
edate,
state
cbdate,
cedate

Example; returns all benzene quarterly summaries from North Carolina for 1995:

https://aqs.epa.gov/data/api/quarterlyData/[email protected]&key=test&param=45201&bdate=19950515&edate=19950515&state=37

By Box
quarterlyData/byBox
email,
key,
param,
bdate,
edate,
minlat,
maxlat,
minlon,
maxlon
cbdate,
cedate

Example; returns ozone quarterly summaries in the vicinity of central Alabama for 2015:

https://aqs.epa.gov/data/api/quarterlyData/[email protected]&key=test&param=44201&bdate=20150501&edate=20150502&minlat=33.3&maxlat=33.6&minlon=-87.0&maxlon=-86.7

By CBSA
quarterlyData/byCBSA
email,
key,
param,
bdate,
edate,
cbsa
cbdate,
cedate

Example; returns quarterly summary NO2 data for the Charlotte-Concord-Gastonia, NC-SC CBSA for 2017:

https://aqs.epa.gov/data/api/quarterlyData/[email protected]&key=test&param=42602&bdate=20170101&edate=20170101&cbsa=16740

Annual Summary

Returns data summarized at the yearly level. Variables include mean value,
maxima, percentiles, etc. Data is at the monitor level and may include
more than one entry per monitor. There may be multiple entries for different
(1) sample durations, (2) pollutant standards.

Service
Filter
Endpoint
Required Variables
Optional Variables

Annual Summary Data
By Site
annualData/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site
cbdate,
cedate

Example; returns annual summary ozone data for the Millbrook School site (#0014) in Wake County, NC for 2017 (Note, for annual data, only the year portion of the bdate and edate are used and only whole years of data are returned. For example, bdate = 20171231 and edate = 20180101 will return full data for 2017 and 2018):

https://aqs.epa.gov/data/api/annualData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&state=37&county=183&site=0014

Example; returns all ozone annual summary data for the Millbrook School site (#0014) in Wake County, NC for June 18, 2017 that changed after January 01, 2018 (and before the end of 2018):

https://aqs.epa.gov/data/api/annualData/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&cbdate=20180101&cedate=20181231&state=37&county=183&site=0014

By County
annualData/byCounty
email,
key,
param,
bdate,
edate,
state,
county
cbdate,
cedate

Example; returns annual summary FRM/FEM and non-FRM PM2.5 data for Wake County, NC for 2016:

https://aqs.epa.gov/data/api/annualData/[email protected]&key=test&param=88101,88502&bdate=20160101&edate=20160229&state=37&county=183

By State
annualData/byState
email,
key,
param,
bdate,
edate,
state
cbdate,
cedate

Example; returns all benzene annual summaries from North Carolina collected for 1995:

https://aqs.epa.gov/data/api/annualData/[email protected]&key=test&param=45201&bdate=19950515&edate=19950515&state=37

By Box
annualData/byBox
email,
key,
param,
bdate,
edate,
minlat,
maxlat,
minlon,
maxlon
cbdate,
cedate

Example; returns ozone annual summaries in the vicinity of central Alabama for 2015:

https://aqs.epa.gov/data/api/annualData/[email protected]&key=test&param=44201&bdate=20150501&edate=20150502&minlat=33.3&maxlat=33.6&minlon=-87.0&maxlon=-86.7

By CBSA
annualData/byCBSA
email,
key,
param,
bdate,
edate,
cbsa
cbdate,
cedate

Example; returns annual summary NO2 data for the Charlotte-Concord-Gastonia, NC-SC CBSA for 2017:

https://aqs.epa.gov/data/api/annualData/[email protected]&key=test&param=42602&bdate=20170101&edate=20170101&cbsa=16740

QA Annual Performance Evaluations

This service returns pairs of data (known and measured values) at several concentration levels for gaseous criteria pollutants.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – Annual Performance Evaluations
By Site
qaAnnualPerformanceEvaluations/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns annual performance evaluation data for ozone at the Fairhope site (#0010) in Baldwin County, AL for 2017:

https://aqs.epa.gov/data/api/qaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&state=01&county=003&site=0010

By County
qaAnnualPerformanceEvaluations/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns annual performance evaluation data for ozone in Baldwin County, AL for 2017:

https://aqs.epa.gov/data/api/qaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&state=01&county=003

By State
qaAnnualPerformanceEvaluations/byState
email,
key,
param,
bdate,
edate,
state

Example; returns annual performance evaluation data for ozone in Alabama during 2017:

https://aqs.epa.gov/data/api/qaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&state=0

By Primary Quality Assurance Organization
qaAnnualPerformanceEvaluations/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns annual performance evaluation data for ozone in during 2017 where the PQAO is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&pqao=0013

By Monitoring Agency
qaAnnualPerformanceEvaluations/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns annual performance evaluation data for ozone in during 2017 where the Monitoring Agency is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&agency=0013

QA Blanks

This service returns the concentration from blank samples.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – Blanks Data
By Site
qaBlanks/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns PM2.5 blank data for the Muscle Shoals site (#0014) in Colbert County, AL for January 2018:

https://aqs.epa.gov/data/api/qaBlanks/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01&county=033&site=1002

By County
qaBlanks/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns PM2.5 blank data for Colbert County, AL for January 2018:

https://aqs.epa.gov/data/api/qaBlanks/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01&county=033

By State
qaBlanks/byState
email,
key,
param,
bdate,
edate,
state

Example; returns PM2.5 blank data for Alabama for January 2018:

https://aqs.epa.gov/data/api/qaBlanks/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01

By Primary Quality Assurance Organization
qaBlanks/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns PM2.5 blank data for January 2018 where the PQAO is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaBlanks/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&pqao=0013

By Monitoring Agency
qaBlanks/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns PM2.5 blank data for January 2018 where the Monitoring Agency is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaBlanks/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&agency=0013

QA Collocated Assessments

This service returns pairs of PM samples collected at the same time and place
by different samplers.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – Collocated Assessments
By Site
qaCollocatedAssessments/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns collocated assessment data for FRM PM2.5 at the Huntsville Old Airport site (#0014) in Madison County, AL for January 2013:

https://aqs.epa.gov/data/api/qaCollocatedAssessments/[email protected]&key=test&param=88101&bdate=20130101&edate=20130131&state=01&county=089&site=0014

By County
qaCollocatedAssessments/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns collocated assessment data for FRM PM2.5 in Madison County, AL for January 2013:

https://aqs.epa.gov/data/api/qaCollocatedAssessments/[email protected]&key=test&param=88101&bdate=20130101&edate=20130131&state=01&county=089

By State
qaCollocatedAssessments/byState
email,
key,
param,
bdate,
edate,
state

Example; returns collocated assessment data for FRM PM2.5 in Alabama for January 2013:

https://aqs.epa.gov/data/api/qaCollocatedAssessments/[email protected]&key=test&param=88101&bdate=20130101&edate=20130131&state=01

By Primary Quality Assurance Organization
qaCollocatedAssessments/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns collocated assessment data for FRM PM2.5 January 2013 where the PQAO is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaCollocatedAssessments/[email protected]&key=test&param=88101&bdate=20130101&edate=20130131&pqao=0013

By Monitoring Agency
qaCollocatedAssessments/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns collocated assessment data for FRM PM2.5 January 2013 where the Monitoring Agency is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaCollocatedAssessments/[email protected]&key=test&param=88101&bdate=20130101&edate=20130131&agency=0013

QA Flow Rate Verifications

This service returns the flow rate checks performed by monitoring agencies.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – Flow Rate Verifications
By Site
qaFlowRateVerifications/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns Flow Rate Verification data for the Muscle Shoals site (#1002) in Colbert County, AL for January 2018:

https://aqs.epa.gov/data/api/qaFlowRateVerifications/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01&county=033&site=1002

By County
qaFlowRateVerifications/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns Flow Rate Verification data for Colbert County, AL for January 2018:

https://aqs.epa.gov/data/api/qaFlowRateVerifications/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01&county=033

By State
qaFlowRateVerifications/byState
email,
key,
param,
bdate,
edate,
state

Example; returns Flow Rate Verification data for Alabama for January 2018:

https://aqs.epa.gov/data/api/qaFlowRateVerifications/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01

By Primary Quality Assurance Organization
qaFlowRateVerifications/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns Flow Rate Verification data for January 2018 where the PQAO is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaFlowRateVerifications/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&pqao=0013

By Monitoring Agency
qaFlowRateVerifications/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns Flow Rate Verification data for January 2018 where the Monitoring Agency is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaFlowRateVerifications/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&agency=0013

QA Flow Rate Audits

This service returns flow rate audit data.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – Flow Rate Audits
By Site
qaFlowRateAudits/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns Flow Rate Audit data for the Wylam site (#2003) in Jefferson County, AL for January 2018:

https://aqs.epa.gov/data/api/qaFlowRateAudits/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01&county=073&site=2003

By County
qaFlowRateAudits/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns Flow Rate Audit data for Jefferson County, AL for January 2018:

https://aqs.epa.gov/data/api/qaFlowRateAudits/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01&county=073

By State
qaFlowRateAudits/byState
email,
key,
param,
bdate,
edate,
state

Example; returns Flow Rate Audit data for Alabama for January 2018:

https://aqs.epa.gov/data/api/qaFlowRateAudits/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&state=01

By Primary Quality Assurance Organization
qaFlowRateAudits/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns Flow Rate Audit data for January 2018 where the PQAO is the Jefferson County, AL Department Of Health (agency 0550):

https://aqs.epa.gov/data/api/qaFlowRateAudits/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&pqao=0550

By Monitoring Agency
qaFlowRateAudits/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns Flow Rate Audit data for January 2018 where the Monitoring Agency is the Jefferson County, AL Department Of Health (agency 0550):

https://aqs.epa.gov/data/api/qaFlowRateAudits/[email protected]&key=test&param=88101&bdate=20180101&edate=20180131&agency=0550

QA One Point QC Raw Data

This service returns the measured versus actual concentration of 1 point QC checks.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – One Point Quality Control Raw Data
By Site
qaOnePointQcRawData/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns One Point QC data for ozone at the Truro National Seashore site (#0002) in Barnstable County, MA for January 2018:

https://aqs.epa.gov/data/api/qaOnePointQcRawData/[email protected]&key=test&param=44201&bdate=20180101&edate=20180131&state=25&county=001&site=0002

By County
qaOnePointQcRawData/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns One Point QC data for ozone in Barnstable County, MA for January 2018:

https://aqs.epa.gov/data/api/qaOnePointQcRawData/[email protected]&key=test&param=44201&bdate=20180101&edate=20180131&state=25&county=001

By State
qaOnePointQcRawData/byState
email,
key,
param,
bdate,
edate,
state

Example; returns One Point QC data for ozone in Massachusetts for January 2018:

https://aqs.epa.gov/data/api/qaOnePointQcRawData/[email protected]&key=test&param=44201&bdate=20180101&edate=20180131&state=25

By Primary Quality Assurance Organization
qaOnePointQcRawData/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns ozone One Point QC data for January 2018 where the PQAO is the Massachusetts Department of Environmental Protection (agency 0660):

https://aqs.epa.gov/data/api/qaOnePointQcRawData/[email protected]&key=test&param=44201&bdate=20180101&edate=20180131&pqao=0660

By Monitoring Agency
qaOnePointQcRawData/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns ozone One Point QC data for January 2018 where the Monitoring Agency is the Massachusetts Department of Environmental Protection (agency 0660):

https://aqs.epa.gov/data/api/qaOnePointQcRawData/[email protected]&key=test&param=44201&bdate=20180101&edate=20180131&agency=0660

QA PEP Audits

This service returns data related to PM2.5 monitoring system audits.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – PEP Audits
By Site
qaPepAudits/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns PEP Audit data for FRM PM2.5 at the Huntsville Old Airport site (#0014) in Madison County, AL for 2017:

https://aqs.epa.gov/data/api/qaPepAudits/[email protected]&key=test&param=88101&bdate=20170101&edate=20171231&state=01&county=089&site=0014

By County
qaPepAudits/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns PEP Audit data for FRM PM2.5 in Madison County, AL for 2017:

https://aqs.epa.gov/data/api/qaPepAudits/[email protected]&key=test&param=88101&bdate=20170101&edate=20171231&state=01&county=089

By State
qaPepAudits/byState
email,
key,
param,
bdate,
edate,
state

Example; returns PEP Audit data for FRM PM2.5 in Alabama for 2017:

https://aqs.epa.gov/data/api/qaPepAudits/[email protected]&key=test&param=88101&bdate=20170101&edate=20171231&state=01

By Primary Quality Assurance Organization
qaPepAudits/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns PEP Audit data for June 2017 where the PQAO is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaPepAudits/[email protected]&key=test&param=88101&bdate=20170601&edate=20170630&pqao=0013

By Monitoring Agency
qaPepAudits/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns PEP Audit data for June 2017 where the Monitoring Agency is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/qaPepAudits/[email protected]&key=test&param=88101&bdate=20170601&edate=20170630&agency=0013

Sample Data Transaction

Returns sample data in the submission (transaction) format for AQS.

Service
Filter
Endpoint
Required Variables
Optional Variables

Sample Data Transaction
By Site
transactionsSample/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site
cbdate,
cedate

Example; returns all ozone data for the Millbrook School site (#0014) in Wake County, NC for June 18, 2017:

https://aqs.epa.gov/data/api/transactionsSample/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&state=37&county=183&site=0014

Example; returns all ozone data for the Millbrook School site (#0014) in Wake County, NC for June 18, 2017 that changed after January 01, 2018 (and before the end of 2018):

https://aqs.epa.gov/data/api/transactionsSample/[email protected]&key=test&param=44201&bdate=20170618&edate=20170618&cbdate=20180101&cedate=20181231&state=37&county=183&site=0014

By County
transactionsSample/byCounty
email,
key,
param,
bdate,
edate,
state,
county
cbdate,
cedate

Example; returns all FRM/FEM PM2.5 data for Wake County, NC between January and February 2016:

https://aqs.epa.gov/data/api/transactionsSample/[email protected]&key=test&param=88101&bdate=20160101&edate=20160228&state=37&county=183

By State
transactionsSample/byState
email,
key,
param,
bdate,
edate,
state
cbdate,
cedate

Example; returns all benzene samples from North Carolina collected on May 15th, 1995:

https://aqs.epa.gov/data/api/transactionsSample/[email protected]&key=test&param=45201&bdate=19950515&edate=19950515&state=37

By Monitoring Agency
transactionsSample/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns all ozone samples collected by monitors operated by the South Coast Air Quality Management District collected on May 15th, 2015:

https://aqs.epa.gov/data/api/transactionsSample/[email protected]&key=test&param=44201&bdate=20150515&edate=20150515&agency=0972

QA Annual Performance Evaluations Transaction

This service returns pairs of data QA at several concentration levels in the submission (transaction) format for AQS.

Service
Filter
Endpoint
Required Variables
Optional Variables

Quality Assurance – Annual Performance Evaluations Transaction
By Site
transactionsQaAnnualPerformanceEvaluations/bySite
email,
key,
param,
bdate,
edate,
state,
county,
site

Example; returns annual performance evaluation data for ozone at the Fairhope site (#0010) in Baldwin County, AL for 2017:

https://aqs.epa.gov/data/api/transactionsQaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&state=01&county=003&site=0010

By County
transactionsQaAnnualPerformanceEvaluations/byCounty
email,
key,
param,
bdate,
edate,
state,
county

Example; returns annual performance evaluation data for ozone in Baldwin County, AL for 2017:

https://aqs.epa.gov/data/api/transactionsQaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&state=01&county=003

By State
transactionsQaAnnualPerformanceEvaluations/byState
email,
key,
param,
bdate,
edate,
state

Example; returns annual performance evaluation data for ozone in Alabama during 2017:

https://aqs.epa.gov/data/api/transactionsQaAnnualPerformanceEvaluations/[email protected]&key=test&param=44201&bdate=20170101&edate=20171231&state=01/a>

By Primary Quality Assurance Organization
transactionsQaAnnualPerformanceEvaluations/byPQAO
email,
key,
param,
bdate,
edate,
pqao

Example; returns annual performance evaluation data for ozone in during 2017 where the PQAO is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/transactionsQaAnnualPerformanceEvaluations/[email protected]&key=test&param=88101&bdate=20170101&edate=20171231&pqao=0013

By Monitoring Agency
transactionsQaAnnualPerformanceEvaluations/byMA
email,
key,
param,
bdate,
edate,
ma

Example; returns annual performance evaluation data for ozone in during 2017 where the Monitoring Agency is the Alabama Department of Environmental Management (agency 0013):

https://aqs.epa.gov/data/api/transactionsQaAnnualPerformanceEvaluations/[email protected]&key=test&param=88101&bdate=20170101&edate=20171231&agency=0013

Top of Page

Output Format – JSON

The only output format available from the services is JSON. This is in conformity with the

18f API standards for government.

The JSON response has two top-level elements. A header and a body. The header contains information about the request and the body contains
the data.

The header contains the following elements:

status. “SUCCESS” if the request returned data. “FAILED” if the request could not be processed. “No data matched your selection” if
the request was processed but resulted in no data.
request_time. The date and time (at the location of the server) when the request was received.
url. The original URL that was submitted to make the request.
row. The number of rows of data in the body object.
errors. Any errors encountered when attempting to respond to the request.

The body is an array with one object per data row. The contents of the object will vary based on the request made. (E.g. the columns
of data returned are different for each query.

Here is a sample of the output of a Raw Data request with one data point:


			{
			  "Header": [
				{
				  "status": "success",
				  "request_time": "2018-06-13T07:45:01-04:00",
				  "url": "https://...",
				  "rows": 1
				}
			  ],
			  "Body": [
				{
				  "state_code": "01",
				  "county_code": "073",
				  "site_number": "0023",
				  "parameter_code": "88101",
				  "poc": 1.0,
				  "latitude": 33.0,
				  "longitude": -86.0,
				  "datum": "WGS84",
				  "parameter_name": "PM2.5 - Local Conditions",
				  "date_local": "2017-04-01",
				  "time_local": "00:00",
				  "date_gmt": "2017-04-01",
				  "time_gmt": "06:00",
				  "sample_measurement": 6.2,
				  "unit_of_measure": "Micrograms/cubic meter (LC)",
				  "detection_limit": 2.0,
				  "uncertainty": null,
				  "qualifiers": null,
				  "method_type": "FRM",
				  "method_code": "142",
				  "method_name": "BGI Models PQ200-VSCC or PQ200A-VSCC - Gravimetric",
				  "state_name": "Alabama",
				  "county_name": "Jefferson",
				  "date_of_last_change": "2017-05-30",
				  "cbsa_code": "13820"
				}
			  ]
			}

Here is a sample of the output of a Raw Data request with one data point:

Top of Page

Loading JSON into Excel

If you want to import this data into Excel, follow these steps (these may vary depending on your software version):

Save the output of your query as a .json file
Open Excel (the imported data will be added as a new sheet to a new or existing workbook)
Go to the “Data” tab
Select Get Data > From File > From JSON from the ribbon (you may have to go to Data > New Query > From File > From JSON depending on your Excel configuration)
Find the file and open it – this should take you to the “Power Query Editor” and the “Convert” pane
Select “Into Table” from the ribbon – this should display two columns called “Name” and “Value”
Click on the grey box next to the word “Value” (the box contains a left-pointing arrow and a right-pointing arrow)
Select “Expand to new rows” – this may add rows to your display
Again, click on the grey box next to the word “Value” (the box contains a left-pointing arrow and a right-pointing arrow)
Uncheck any columns you do not want (e.g., those from the header: status, request_time, url, and rows)
(Optional) Uncheck the box at the bottom: “Use original column names as prefix”
Click “OK” to close the dialogue box
Note, you can now remove columns and sort data in this view.
Click “Close & Load” from the close pane (top left)
Wait a few moments and the data will appear, one row for the header and one for each record of data

The data is loaded as a table in a new sheet in the workbook. This makes some Excel functions
“grey out” (e.g., sort) when the entire sheet is selected. To sort, for example, select a cell in
table header (rather than the entire workbook or workbook header) and the sort functionality should work.

You can query the API from within Excel. At the “Data” tab, select Get Data > From Other Sources > From Web.
Enter the API request URL in the form and select “OK”.
Excel should run the query and take you to the “Power Query Editor”. Use the steps outlined above to
load the data into a sheet.

Top of Page

Error Handling and Status Codes

If the API is able to parse your request it will return the JSON described above and an HTTP status of 200.

If the API is not able to parse your request it will return a status code of 400 and only the header, which will include an
array of error messages instead of a row count. For example:


	     {
		  "Header": [
			{
			  "status": "Failed",
			  "request_time": "2018-06-13T08:05:46.588-04:00",
			  "url": "https://...",
			  "error": [
			    "value is missing or the value is empty: param"
			]
			}
		  ],
		  "Body": []
		}

If the API is able to parse your request but no data matches your selections, it will return the JSON header and
an HTTP status of 200. The row count will be zero, the status will be a message that no data matched your selection criteria, and the body will be empty.


	    {
		  "Header": [
			{
			  "status": "No data matched your selection",
			  "request_time": "2018-06-13T10:15:42-04:00",
			  "url": "https://...",
			  "rows": 0
			}
		  ],
		  "Body": []
		}

Top of Page

Request Limits and Terms of Service

The API has the following limits imposed on request size:

Length of time. All services (except Monitor) must have the end date (edate field) be in the
same year as the begin date (bdate field).
Number of parameters. Most services allow for the selection of multiple parameter codes (param field). A maximum of 5 parameter codes may be listed in a single request.

Please adhere to the following when using the API.

Limit the size of queries. Our database contains billions of values and you may request more than you intend.
If you are unsure of the amount of data, start small and work your way up.
We request that you limit queries to 1,000,000 rows of data each.
You can use the “observation count” field on the annualData service to determine how much data exists for a time-parameter-geography combination.
If you have any questions or need advice, please contact us.
Limit the frequency of queries. Our system can process a limited load.
If scripting requests, please wait for one request to complete before submitting another and do not make more than 10 requests per minute.
Also, we request a pause of 5 seconds between requests and adjust accordingly for response time and size.

If you violate these terms, we may disable your account without notice (but we will be in contact via the email address provided).

Top of Page

Usage tips

This section contains suggestions for completing certain data related tasks and links to software tools using the API.

Determine if or how much data exists for a time-parameter-geography combination:

Retrieve data using the annualData service.
If no records are returned, we do not have the data.
If records are returned, use the observation count to determine the temporal and geographic distribution of the data.

Monthly averages:

AQS does not routinely calculate monthly aggregate statistics.
If you need these, you must calculate them yourself.
These can be calculated from the sample data or the daily data without loss of fidelity.

Determine a single value for a site with collocated monitors:

Many sites will have collocated monitors – monitors collecting the same parameter at the same time.
The API currently provides only monitor level values. (We anticipate adding site-level values at some point.)
For some criteria pollutants (PM2.5, ozone, lead, and NO2), the regulations define procedures for defining a single site-level value.
For other pollutants, determining a single site-level value is left to the investigator.

Software Tools

The EPA has released an R package that uses this API To query AQS data. It is
available at the Comprehensive R Archive Network (CRAN).
This software is open source and the repository page is linked to from that site. Also, please use the link there to report issues or ask
questions about the package.

Top of Page

What has changed from the API version 1

The following changes have been made to the web services.

All output is JSON. In conformity with
federal API standards, all output is now JSON
Services have been added. Instead of one primary service, raw data, there now a multitude of services.
The request structure has been simplified. Rather than having a mixture of required and optional variables, each service has required
variables and some have the optional change begin and end dates.
There is no interface to help users build a query. Previously, an interface was provided with drop downs to assist users in building a query.
In retrospect, this led to as many questions as is solved, so we are no longer providing it.
Asynchronous requests have been removed. All requests now return data.
Uptime should be better. The number of moving parts behind the scenes has been reduced and we expect less downtime.
Terms have changed. “User ID” and “password” have been changed to “email” and “key” to better reflect meaning. Old accounts are still valid.
Query size limits have been removed. You may query as much data as you like. If this does not work, we will put limits on accounts.
The URL has changed from aqs.epa.gov/api to aqs.epa.gov/data/api. This is to allow for both to run concurrently during
the transition period and to make room for other potential (non-data) APIs.
The sample data service returns null samples.

Top of Page

Change log and planned enhancements

Change log

To see the recent changes to the API and data, use
the Revision History service. For example:

https://aqs.epa.gov/data/api/metaData/[email protected]&key=test

Known issues

To see any known issues with the API or the AQS data, use
the Known Issues service. For example:

https://aqs.epa.gov/data/api/metaData/[email protected]&key=test

Planned enhancements

Add the ability to filter data by sample duration. The user will
be able to select a single duration to be returned: 1-hour, 5-minute, etc.
(early 2020)
Add “by zip code” as a retrieval method for all services.
(no planned implementation date)

Top of Page

This page last updated on 2020-01-10

AQS API | AirData | US EPA

Services Overview

Variables used in service requests

Service Details and Examples

Sign Up

Lists

Monitors

Sample Data

Daily Summary Data

Quarterly Summary

Annual Summary

QA Annual Performance Evaluations

QA Blanks

QA Collocated Assessments

QA Flow Rate Verifications

QA Flow Rate Audits

QA One Point QC Raw Data

QA PEP Audits

Sample Data Transaction

QA Annual Performance Evaluations Transaction

Output Format – JSON

Loading JSON into Excel

Error Handling and Status Codes

Request Limits and Terms of Service

Usage tips

Software Tools

What has changed from the API version 1

Change log and planned enhancements