• AQS API | AirData | US EPA
    Return to Air Data Home

    Air Quality System (AQS) API

    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.

    Service Description
    Sign up Creates an account or resets a password. Requires validation of registered email address. Email will be sent to the registered address from aqsdatamart@epa.gov. This service can also be used to reset passwords.
    Meta Data Returns information about the API. Is it available/up? What are the meanings of the fields in my returned data? Recent and planned changes, etc.
    List Provides information you need to construct other queries. Valid values for the required variables: parameter code, state code, etc. (See below.)
    Monitors Returns operational information about the samplers (monitors) used to collect the data. Includes identifying information, operational dates, operating organizations, etc.
    Sample Data Returns sample data - the finest grain data reported to EPA. Usually hourly, sometimes 5-minute, 12-hour, etc. This service is available in several geographic selections based on geography: site, county, state, CBSA (core based statistical area, a grouping of counties), or latitude/longitude bounding box.
    Daily Summary 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.
    Quarterly Summary Returns data summarized at the calendar quarter level (Q1 = Jan - Mar, Q2 = Apr - Jun, Q3 = Jul - Sep, Q4 = Oct - Dec). Variables include mean value, maxima, percentiles, etc.
    Annual Summary Returns data summarized at the yearly level. Variables include mean value, maxima, percentiles, etc.
    QA Annual Performance Evaluations Quality assurance data - annual performance evaluations. A performance evaluation must be conducted on each primary monitor once a year. The percent differences between known and measured concentrations at several levels are used to assess the quality of the monitoring data.
    QA Blanks Quality assurance data - blanks samples. Blanks are unexposed sample collection devices (e.g., filters) that are transported with the exposed sample devices to assess if contamination is occurring during the transport or handling of the samples.
    QA Collocated Assessments Quality assurance data - collocated assessments. Collocated assessments are pairs of samples collected by different samplers at the same time and place. (These are "operational" samplers, assessments with independently calibrated samplers are called "audits".)
    QA Flow Rate Verifications Quality assurance data - flow rate verifications. Several times per year, each PM monitor must have it's (fixed) flow rate verified by an operator taking a measurement of the flow rate.
    QA Flow Rate Audits Quality assurance data - flow rate audits. At least twice year, each PM monitor must have its flow rate measurement audited by an expert using a different method than is used for flow rate verifications.
    QA One Point QC Raw Data Quality assurance data - one point quality control check raw data. At least every two weeks, certain gaseous monitors must be challenged with a known concentration to determine monitor performance.
    QA PEP Audits Quality assurance data - performance evaluation program (PEP) audits. PEP audits are independent assessments used to estimate total measurement system bias with a primary quality assurance organization.
    Transaction - Sample AQS Submission Transaction Format for Sample Data - sample (raw) data in the AQS submission transaction format (RD). Includes data both in submitted and standard units.
    Transaction - QA Annual Performance Evaluations AQS Submission Transaction Format for Annual Performance Evaluation data. Includes data pairs for QA.

    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. someone@provider.com
    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
    bdate 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
    edate 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
    cbdate 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
    cedate 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.

    Sign Up

    This service creates an account or resets a password. Requires validation of registered email address. Email will be sent to the registered address from aqsdatamart@epa.gov.

    Service Filter Endpoint Required Variables Optional Variables
    Sign up 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 "myemail@example.com" create and request this link (Replace "myemail@example.com" in the example with your email address.):

    https://aqs.epa.gov/data/api/signup?email=myemail@example.com

    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.

    Meta Data

    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:
    Revision History metaData/revisionHistory email, key
    Examples:
    Returns a complete list of revisions to the API in reverse chronological order:
    Returned Fields by Service metaData/fieldsByService email, key, service
    Examples:
    Returns a list and definitions of fields in the Sample Data service:
    Returns a list and definitions of fields in the List service:
    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.

    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:
    Counties by State list/countiesByState email, key, state
    Example; returns all counties in North Carolina:
    Sites by County list/sitesByCounty email, key, state, county
    Example; returns all sites in Wake County, NC:
    CBSAs (Core Based Statistical Areas) list/cbsas email, key
    Parameter Classes (groups of parameters, like criteria or all) list/classes email, key
    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:
    PQAOs (primary quality assurance organizations) list/pqaos email, key
    MAs (monitoring agencies) list/mas email, key

    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):
    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:
    By State monitors/byState email, key, param, bdate, edate, state
    Example; returns SO2 monitors in Hawaii that were operating on May 01, 2015:
    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:
    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:

    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:
    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):
    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:
    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:
    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:
    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:

    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:
    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):
    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:
    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:
    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:
    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:

    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.):
    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):
    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:
    By State quarterlyData/byState email, key, param, bdate, edate, state cbdate, cedate
    Example; returns all benzene quarterly summaries from North Carolina for 1995:
    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:
    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:

    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):
    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):
    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:
    By State annualData/byState email, key, param, bdate, edate, state cbdate, cedate
    Example; returns all benzene annual summaries from North Carolina collected for 1995:
    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:
    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:

    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:
    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:
    By State qaAnnualPerformanceEvaluations/byState email, key, param, bdate, edate, state
    Example; returns annual performance evaluation data for ozone in Alabama during 2017:
    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):
    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):

    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:
    By County qaBlanks/byCounty email, key, param, bdate, edate, state, county
    Example; returns PM2.5 blank data for Colbert County, AL for January 2018:
    By State qaBlanks/byState email, key, param, bdate, edate, state
    Example; returns PM2.5 blank data for Alabama for January 2018:
    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):
    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):

    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:
    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:
    By State qaCollocatedAssessments/byState email, key, param, bdate, edate, state
    Example; returns collocated assessment data for FRM PM2.5 in Alabama for January 2013:
    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):
    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):

    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:
    By County qaFlowRateVerifications/byCounty email, key, param, bdate, edate, state, county
    Example; returns Flow Rate Verification data for Colbert County, AL for January 2018:
    By State qaFlowRateVerifications/byState email, key, param, bdate, edate, state
    Example; returns Flow Rate Verification data for Alabama for January 2018:
    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):
    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):

    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:
    By County qaFlowRateAudits/byCounty email, key, param, bdate, edate, state, county
    Example; returns Flow Rate Audit data for Jefferson County, AL for January 2018:
    By State qaFlowRateAudits/byState email, key, param, bdate, edate, state
    Example; returns Flow Rate Audit data for Alabama for January 2018:
    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):
    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):

    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:
    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:
    By State qaOnePointQcRawData/byState email, key, param, bdate, edate, state
    Example; returns One Point QC data for ozone in Massachusetts for January 2018:
    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):
    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):

    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:
    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:
    By State qaPepAudits/byState email, key, param, bdate, edate, state
    Example; returns PEP Audit data for FRM PM2.5 in Alabama for 2017:
    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):
    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):

    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:
    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):
    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:
    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:
    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:

    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:
    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:
    By State transactionsQaAnnualPerformanceEvaluations/byState email, key, param, bdate, edate, state
    Example; returns annual performance evaluation data for ozone in Alabama during 2017:
    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):
    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):

    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"
    				}
    			  ]
    			}
    		 

    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/revisionHistory?email=test@aqs.api&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/issues?email=test@aqs.api&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