AirNow API - Frequently Asked Questions

You can reset your website password or retrieve your API key via the Log In page. Your API key is also automatically included in example URLs when using the Query Tool.

Users of the AirNow API web services and data feeds are expected to follow the AirNow Data Use Guidelines. In addition, data users should adhere to the following best practices for rate limiting and caching:

Rate limiting

Users must limit web service calls for a given API key to the maximum permitted for the web service (see documentation for each web service). If this limit is met within a specific hour, the web service will not return data until the next hour. Users consistently exceeding this limit may be contacted and encouraged to use alternative data sources.

Caching recommendations

In general, air quality observations are updated once per hour and forecasts are issued once per day. Therefore, we recommend users cache daily or hourly air quality observation or forecast data retrieved via web services. For example, air quality observations for the previous hour are generally available between 10 and 30 minutes past the hour. One possible caching mechanism is to populate your own database. For data users needing large data sets, additional data sources such as nationwide file products may be appropriate (see File Products). If your objective is to populate your own database with air quality data using a web service, please contact the AirNow Data Management Center at dmc@airnowtech.org for other options.

Air quality agencies report information to the public via reporting areas. Reporting areas vary by size and population, covering anywhere from part of a city to an entire county area.

Air quality agencies issue air quality forecasts to the public via reporting areas; however, forecasts are not necessarily available for all reporting areas. In addition, the forecast for each reporting area is unique:

• Forecasts may not be issued every day or may be seasonal (e.g. winter or summer only).
• Forecasts may cover from one to six days.
• Forecasts may cover one or more pollutants (e.g. ozone, PM_2.5).
• Forecasts may include an AQI number (e.g., 51) or simply an AQI category (e.g., Moderate or Unhealthy).
• A forecast discussion may or may not be included.

The air quality agency responsible for a reporting area assigns one or more zip codes to be associated with that area.

Air quality agencies decide whether to report observed real-time and peak air quality data for a given reporting area. When observations are reported, the information can include one or more monitoring stations. The observation for any given hour is the maximum observed AQI reported across all monitoring stations within the reporting area. More information about the AQI can be found on the Air Quality 101 page.

To obtain observations by monitoring site, you may use one of the nationwide file products available on the File Products page.

If your objective is to maintain a database of forecasts or observations by reporting area (the same data currently returned by the zip code and latitude/longitude web services), please do NOT attempt to the use the web services for this purpose. The web services presently included in the AirNow API were designed for end users to make requests for forecasts or data for a selected area, not for looping through all zip codes to populate a database.

It is important to note that while there are many zip codes, there are actually relatively few reporting areas to which those zip codes are assigned. For example, in the state of Texas there are nearly 2600 zip codes; however, there are only 14 different AirNow reporting areas. The current observation web services return the peak Air Quality Index value for a reporting area. Local air quality agencies determine the zip codes assigned to their reporting areas, and this relationship is used to look for an observation within or near the user's requested zip code. Therefore, making 2600 zip code requests to get data for Texas is overkill - there are only 14 different data returns.

To populate a database of zip codes based forecasts or observations, we recommend you use the following file outputs from the AirNow system:

• reportingarea.dat - This file is available on files.airnowtech.org, and information about the file is on the airnowapi.org website under the File Products tab. This file is updated twice per hour at :55 and :25 and contains current observations and forecasts. The online documentation explains which records are observations versus forecasts.
• cityzipcodes.csv - This file is available on the EPA's website at: https://files.airnowtech.org/airnow/today/cityzipcodes.csv - The file contains the zip codes that are assigned to each reporting area. It also contains the latitude/longitude (centroid) for each zip code. The file is updated once per day, although agencies do not change their reporting area/zip code associations that often.

These files can be used to populate a database with current AQI values for each reporting area (with reportingarea.dat), and lookup data for a zip code directly associated with a reporting area using the cityzipcodes.csv file. If a direct zip code/reporting area association does not exist, you may do a distance lookup to the reporting area zip code centroid (also included in reportingarea.dat). Of course, to do that look up, you will need to maintain your own master zip code table to reference the latitude/longitude of the user's requested zip code. Zip code geographic information can be retrieved via the U.S. Census Bureau's Topologically Integrated Geographic Encoding and Referencing (TIGER) product portal (https://www.census.gov/geo/maps-data/data/tiger.html).

If your objective is to maintain a database of observations by monitoring site and/or data across a date/time range (e.g., graphs of hourly data values), you may use one of the outputs on the File Products page, such as the "Hourly Data Values" or "Daily Data Values."

If an error occurs when using a web service, an XML-formatted message will be returned describing the error.

The AirNow Gateway web services have been replaced by the AirNow API web services described on the Web Services page. In order to give data users the ability to transition over to the new AirNow API web services, AirNow Gateway web services will continue to operate until mid-2014. For more information, please contact the AirNow Data Management Center at dmc@airnowtech.org.