# EPA Air Quality Index Scraper (`crawlerbros/epa-air-quality-scraper`) Actor Scrape US EPA annual Air Quality Index (AQI) data from the public EPA AQS database - no API key required. Get AQI statistics, pollutant breakdowns (PM2.5, PM10, ozone, NO2, CO), and health category day counts for US counties, metro areas (CBSAs), and states. Historical data from 1980 to present. - **URL**: https://apify.com/crawlerbros/epa-air-quality-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## EPA Air Quality Index Scraper Scrape annual **Air Quality Index (AQI)** statistics for every US county, metropolitan area (CBSA), and state from the [EPA Air Quality System (AQS)](https://aqs.epa.gov) public database. No API key or registration required. Historical data from 1980 through 2024. ### What You Can Scrape - **By County** — AQI statistics for every US county (3,100+ counties), including good/moderate/unhealthy day counts, pollutant breakdowns, and AQI percentiles. - **By Metro Area** — same statistics aggregated for 400+ Core-Based Statistical Areas (CBSAs), the standard US metro/micropolitan regions. - **By State** — aggregate AQI statistics derived by state (50 states + DC), including average median AQI and worst county max AQI. ### Output Fields #### County records (`recordType: "countyAqi"`) | Field | Type | Description | |---|---|---| | `state` | string | US state name (e.g. `California`) | | `county` | string | County name (e.g. `Los Angeles`) | | `year` | integer | Calendar year | | `daysWithAqi` | integer | Number of days with AQI data available | | `goodDays` | integer | Days classified as AQI "Good" (0–50) | | `moderateDays` | integer | Days classified as AQI "Moderate" (51–100) | | `unhealthyForSensitiveGroupsDays` | integer | Days classified as "Unhealthy for Sensitive Groups" (101–150) | | `unhealthyDays` | integer | Days classified as "Unhealthy" (151–200) | | `veryUnhealthyDays` | integer | Days classified as "Very Unhealthy" (201–300) | | `hazardousDays` | integer | Days classified as "Hazardous" (301+) | | `maxAqi` | integer | Highest single-day AQI in the year | | `percentile90Aqi` | integer | 90th percentile AQI | | `medianAqi` | integer | Median AQI across all monitored days | | `medianAqiCategory` | string | Health category label for median AQI | | `daysCo` | integer | Days where CO was the primary pollutant | | `daysNo2` | integer | Days where NO2 was the primary pollutant | | `daysOzone` | integer | Days where ozone was the primary pollutant | | `daysPm25` | integer | Days where PM2.5 was the primary pollutant | | `daysPm10` | integer | Days where PM10 was the primary pollutant | | `dominantPollutant` | string | Pollutant with the most monitoring days | | `sourceUrl` | string | EPA AQS zip file URL for this year | | `scrapedAt` | string | UTC timestamp when record was scraped | | `recordType` | string | Always `"countyAqi"` | #### Metro area records (`recordType: "metroAqi"`) Same fields as county records, plus: | Field | Type | Description | |---|---|---| | `cbsa` | string | CBSA name (e.g. `Los Angeles-Long Beach-Anaheim, CA`) | | `cbsaCode` | string | CBSA numeric code | | `stateAbbreviations` | array | State abbreviations in this CBSA | #### State records (`recordType: "stateAqi"`) | Field | Type | Description | |---|---|---| | `state` | string | US state name | | `year` | integer | Calendar year | | `countyCount` | integer | Number of counties included in the aggregation | | `avgMedianAqi` | integer | Average of county median AQI values | | `avgMedianAqiCategory` | string | Health category for average median AQI | | `stateMaxAqi` | integer | Highest max AQI among all counties | | `avgDaysWithAqi` | integer | Average days with monitoring data per county | | `totalGoodDays` | integer | Sum of good days across all counties | | `totalUnhealthyDays` | integer | Sum of unhealthy days across all counties | ### Input Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `mode` | select | `byCounty` | `byCounty`, `byMetro`, or `byState` | | `year` | integer | `2024` | Year to fetch (1980–2024) | | `years` | array | — | Multiple years for a single run | | `stateFilter` | string | — | Filter to one state (e.g. `California`) | | `minMedianAqi` | integer | — | Minimum median AQI | | `maxMedianAqi` | integer | — | Maximum median AQI | | `minDaysWithAqi` | integer | — | Minimum monitoring days | | `minMaxAqi` | integer | — | Minimum max AQI (find worst air quality) | | `pollutantFilter` | select | — | Filter by dominant pollutant: `co`, `no2`, `ozone`, `pm25`, `pm10` | | `sortBy` | select | `medianAqi` | Sort field: `medianAqi`, `maxAqi`, `unhealthyDays`, `goodDays`, `daysWithAqi`, `state` | | `maxItems` | integer | `500` | Maximum records to emit | ### Example Inputs #### Counties with worst air quality in California for 2023 ```json { "mode": "byCounty", "year": 2023, "stateFilter": "California", "sortBy": "medianAqi", "maxItems": 50 } ```` #### All US metro areas for 2024 sorted by worst AQI ```json { "mode": "byMetro", "year": 2024, "sortBy": "maxAqi", "maxItems": 100 } ``` #### Historical data: California AQI by county for 2015–2024 ```json { "mode": "byCounty", "years": ["2015", "2016", "2017", "2018", "2019", "2020", "2021", "2022", "2023", "2024"], "stateFilter": "California", "maxItems": 5000 } ``` #### State-level summary for 2024 ```json { "mode": "byState", "year": 2024, "sortBy": "medianAqi", "maxItems": 51 } ``` #### Find counties with the most PM2.5 pollution days ```json { "mode": "byCounty", "year": 2023, "pollutantFilter": "pm25", "sortBy": "medianAqi", "maxItems": 100 } ``` ### Use Cases - **Air quality research** — analyze long-term trends in US air quality at county and metro levels. - **Public health** — identify areas with high numbers of unhealthy air days for sensitive populations. - **Policy analysis** — compare AQI improvements across states and metro areas over time. - **Environmental journalism** — find the cleanest and most polluted areas in the US. - **Real estate / relocation** — evaluate air quality history when choosing where to live. - **Academic research** — build datasets linking air quality to health outcomes, demographics, or economic activity. ### AQI Health Categories | AQI Range | Category | |---|---| | 0–50 | Good — Air quality is satisfactory | | 51–100 | Moderate — Acceptable quality; some pollutants may concern sensitive people | | 101–150 | Unhealthy for Sensitive Groups — At-risk populations may experience health effects | | 151–200 | Unhealthy — Everyone may experience health effects | | 201–300 | Very Unhealthy — Health warnings of emergency conditions | | 301+ | Hazardous — Serious health effects for entire population | ### Data Source Data comes directly from the [EPA Air Quality System (AQS)](https://aqs.epa.gov/aqsweb/airdata/download_files.html) public bulk data files, which are freely available without registration or API keys. Data is published annually and covers all EPA monitoring stations across the United States. ### FAQ **Does this require an API key?** No. The EPA AQS bulk data files are publicly accessible ZIP archives — no registration or API key is needed. **What years are available?** Annual AQI data is available from 1980 through 2024. Set `year` or provide a list in `years`. **How current is the data?** Annual data is published by the EPA for the previous year. The most recent available year is typically published by Q2 of the following year. **How many counties does the US have?** The US has approximately 3,143 counties/county-equivalents. Not all have EPA monitoring stations, but 2,000+ typically appear in the annual dataset. **What is a CBSA?** A Core-Based Statistical Area is the standard US geographic unit for metropolitan and micropolitan statistical areas, defined by the US Office of Management and Budget. The AQI dataset covers 400+ CBSAs. **Can I get data for multiple years at once?** Yes — use the `years` input to provide a list of years. Each year is fetched as a separate EPA download and all records are emitted in the same run. # Actor input Schema ## `mode` (type: `string`): What geographic level to scrape. ## `year` (type: `integer`): Calendar year for which to fetch AQI data. EPA publishes data for 1980–present. Defaults to most recent available year (2024). ## `years` (type: `array`): Fetch data for multiple years in one run. Each year produces separate records. Leave empty to use the single `year` field. ## `stateFilter` (type: `string`): Only include records for this US state name (e.g. `California`, `Texas`). Case-insensitive. Leave empty for all states. ## `minMedianAqi` (type: `integer`): Only include records where Median AQI is at or above this value (e.g. 50). ## `maxMedianAqi` (type: `integer`): Only include records where Median AQI is at or below this value. ## `minDaysWithAqi` (type: `integer`): Only include records with at least this many days of AQI monitoring. ## `minMaxAqi` (type: `integer`): Only include records where Max AQI is at or above this value (useful for finding worst-air-quality areas). ## `pollutantFilter` (type: `string`): Only include records where this pollutant has the most monitoring days. ## `sortBy` (type: `string`): Field to sort records by (descending). Applied after filtering. ## `maxItems` (type: `integer`): Maximum number of records to emit. ## Actor input object example ```json { "mode": "byCounty", "year": 2024, "years": [], "pollutantFilter": "", "sortBy": "medianAqi", "maxItems": 500 } ``` # Actor output Schema ## `records` (type: `string`): Dataset containing AQI statistics by county, metro area, or state. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "byCounty", "year": 2024, "years": [], "pollutantFilter": "", "sortBy": "medianAqi", "maxItems": 500 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/epa-air-quality-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "byCounty", "year": 2024, "years": [], "pollutantFilter": "", "sortBy": "medianAqi", "maxItems": 500, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/epa-air-quality-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "byCounty", "year": 2024, "years": [], "pollutantFilter": "", "sortBy": "medianAqi", "maxItems": 500 }' | apify call crawlerbros/epa-air-quality-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/epa-air-quality-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "EPA Air Quality Index Scraper", "description": "Scrape US EPA annual Air Quality Index (AQI) data from the public EPA AQS database - no API key required. Get AQI statistics, pollutant breakdowns (PM2.5, PM10, ozone, NO2, CO), and health category day counts for US counties, metro areas (CBSAs), and states. Historical data from 1980 to present.", "version": "1.0", "x-build-id": "txpOqprG3pBfg0dyb" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~epa-air-quality-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-epa-air-quality-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~epa-air-quality-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-epa-air-quality-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~epa-air-quality-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-epa-air-quality-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "byCounty", "byMetro", "byState" ], "type": "string", "description": "What geographic level to scrape.", "default": "byCounty" }, "year": { "title": "Year", "minimum": 1980, "maximum": 2024, "type": "integer", "description": "Calendar year for which to fetch AQI data. EPA publishes data for 1980–present. Defaults to most recent available year (2024).", "default": 2024 }, "years": { "title": "Multiple years", "type": "array", "description": "Fetch data for multiple years in one run. Each year produces separate records. Leave empty to use the single `year` field.", "default": [], "items": { "type": "string" } }, "stateFilter": { "title": "State filter", "type": "string", "description": "Only include records for this US state name (e.g. `California`, `Texas`). Case-insensitive. Leave empty for all states." }, "minMedianAqi": { "title": "Min median AQI", "minimum": 0, "maximum": 500, "type": "integer", "description": "Only include records where Median AQI is at or above this value (e.g. 50)." }, "maxMedianAqi": { "title": "Max median AQI", "minimum": 0, "maximum": 500, "type": "integer", "description": "Only include records where Median AQI is at or below this value." }, "minDaysWithAqi": { "title": "Min days with AQI data", "minimum": 1, "maximum": 366, "type": "integer", "description": "Only include records with at least this many days of AQI monitoring." }, "minMaxAqi": { "title": "Min max AQI", "minimum": 0, "maximum": 500, "type": "integer", "description": "Only include records where Max AQI is at or above this value (useful for finding worst-air-quality areas)." }, "pollutantFilter": { "title": "Dominant pollutant filter", "enum": [ "", "co", "no2", "ozone", "pm25", "pm10" ], "type": "string", "description": "Only include records where this pollutant has the most monitoring days.", "default": "" }, "sortBy": { "title": "Sort results by", "enum": [ "medianAqi", "maxAqi", "unhealthyDays", "goodDays", "daysWithAqi", "state" ], "type": "string", "description": "Field to sort records by (descending). Applied after filtering.", "default": "medianAqi" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of records to emit.", "default": 500 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```