# Air Quality & Environmental Data Feeds (`datapilot/air-quality-environmental-data-feeds`) Actor

Fetches real-time air quality data for cities worldwide using Open-Meteo. Returns location, US AQI, PM2.5 levels, measurement time, and scrape timestamp.

- **URL**: https://apify.com/datapilot/air-quality-environmental-data-feeds.md
- **Developed by:** [Data Pilot](https://apify.com/datapilot) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 result scrapes

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

🌫️ **Air Quality & Environmental Data** Feeds is a powerful Apify Actor designed to discover, track, and collect real-time **Air Quality & Environmental Data** directly from the Open-Meteo geocoding and air-quality APIs. This tool provides comprehensive **Air Quality & Environmental Data** intelligence including station location, US Air Quality Index (AQI), and PM2.5 concentration for any city or keyword search. Whether you're building an environmental dashboard, tracking pollution trends, or conducting public-health research, the Air Quality & Environmental Data Feeds actor delivers actionable **Air Quality & Environmental Data** insights efficiently.

With direct Open-Meteo API integration, single-batch multi-location queries, automatic geocoding resolution, and reliable Apify Dataset delivery, the Air Quality & Environmental Data Feeds actor ensures comprehensive **Air Quality & Environmental Data** coverage across any matching location worldwide. It focuses on key **Air Quality & Environmental Data** signals including AQI and PM2.5, making it an essential tool for environmental research and public-health intelligence.

***

### 📋 Table of Contents

- [Features](#-features)
- [Data Source](#-data-source)
- [How It Works](#-how-it-works)
- [Input](#-input)
- [Output](#-output)
- [Technical Stack](#-technical-stack)
- [Data Fields](#-data-fields-explained)
- [Use Cases](#-use-cases)
- [Quick Start](#-quick-start)
- [Configuration](#-configuration)
- [Performance](#-performance)
- [Important Notes](#-important-notes)
- [License & Legal](#-license--legal)

***

### 🔥 Features

- **Open-Meteo API Integration** – Direct, key-less integration with Open-Meteo's geocoding and air-quality endpoints for accurate **Air Quality & Environmental Data**.
- **Automatic Geocoding Resolution** – Converts any city name or keyword into matching coordinates before fetching **Air Quality & Environmental Data**.
- **Single-Batch Multi-Location Queries** – Combines all matched locations into one air-quality API request for maximum efficiency.
- **Ultra-Fast Batch Mode** – Retrieves **Air Quality & Environmental Data** for dozens of locations in just two total API calls.
- **US AQI & PM2.5 Metrics** – Captures both the standardized US Air Quality Index and raw PM2.5 particulate concentration.
- **Configurable Result Cap** – Control how many matching locations to include via `maxResults`.
- **Proxy Fallback Handling** – Automatically retries without a proxy if a proxied request fails.
- **Optional Residential Proxy Support** – Apify residential proxy available for reliable **Air Quality & Environmental Data** access when needed.
- **Real-Time Dataset Push** – Pushes all harvested **Air Quality & Environmental Data** records to Apify Dataset in a single batch.
- **Detailed Logging** – Comprehensive progress logging for every stage of the **Air Quality & Environmental Data** run.
- **Graceful Error Handling** – Logs a clear warning and exits cleanly if no locations or measurements are found.

***

### 📊 Data Source

#### **Open-Meteo Geocoding & Air Quality APIs**

- **Authority**: Open-Meteo, a free and open-source weather and environmental data provider
- **Endpoints**: `geocoding-api.open-meteo.com/v1/search` and `air-quality-api.open-meteo.com/v1/air-quality`
- **Coverage**: Any city, town, or named location worldwide matching the search keyword
- **Data**: US AQI, PM2.5 concentration, and station location details
- **Access**: Public, key-less JSON APIs
- **Update Frequency**: Reflects near-real-time **Air Quality & Environmental Data** at time of run

***

### ⚙️ How It Works

The Air Quality & Environmental Data Feeds actor accepts a city name or keyword and first queries Open-Meteo's geocoding API to resolve it into a list of matching locations with coordinates. All matched coordinates are then combined into a single batched request to the air-quality API, retrieving current US AQI and PM2.5 readings for every location at once — keeping the entire run to just two API calls regardless of how many locations are matched. Each result is paired back to its originating location and normalized into a clean **Air Quality & Environmental Data** record, then pushed to the Apify Dataset in one batch.

**Key Processing Steps:**

1. **Input Parsing** – Accept a city name or keyword and a maximum result count
2. **Proxy Setup** – Configure Apify residential proxy if enabled, with automatic no-proxy fallback
3. **Session Init** – Create a Chrome-impersonated HTTP session for reliable API access
4. **Geocoding Lookup** – Resolve the keyword into matching locations and coordinates
5. **Result Capping** – Limit the matched locations to `maxResults`
6. **Batch Coordinate Assembly** – Combine all latitudes and longitudes into one comma-separated query
7. **Air Quality Query** – Fetch current AQI and PM2.5 for all locations in a single request
8. **Result Pairing** – Match each air-quality result back to its originating location
9. **Record Normalization** – Build a clean **Air Quality & Environmental Data** record per station
10. **Dataset Push** – Push all harvested records to the Dataset in a single batch
11. **Summary Logging** – Report the total number of records processed

**Key Benefits:**

- Pull **Air Quality & Environmental Data** for any city or region without manual lookups
- Retrieve dozens of locations' readings in just two total API calls
- Monitor pollution levels and air quality trends across multiple cities at once
- Feed environmental dashboards, public-health tools, or research pipelines
- Automate recurring **Air Quality & Environmental Data** checks as conditions change

***

### 📥 Input

The Actor accepts the following input parameters:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `cityOrKeyword` | string | `"London"` | City name or keyword to search for matching locations. |
| `maxResults` | integer | `40` | Maximum number of matched locations to fetch **Air Quality & Environmental Data** for. |
| `proxyConfiguration` | object | `{}` (proxy disabled by default) | Apify Proxy configuration; set `useApifyProxy: true` to enable. |

**Example Input:**

```json
{
  "cityOrKeyword": "Springfield",
  "maxResults": 25
}
```

**Search a Single Well-Known City:**

```json
{
  "cityOrKeyword": "Paris",
  "maxResults": 10
}
```

**Search with Proxy Enabled:**

```json
{
  "cityOrKeyword": "Los Angeles",
  "maxResults": 15,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

***

### 📤 Output

The Actor pushes **Air Quality & Environmental Data** records with the following structure:

| Field | Type | Description |
|-------|------|-------------|
| `portal` | string | Always `"Environmental Portals"` |
| `station` | string | Location name, formatted as "City, Region, Country" |
| `aqi` | number/string | Current US Air Quality Index value, or `"-"` if unavailable |
| `pm25` | number/string | Current PM2.5 concentration, or `"-"` if unavailable |
| `date` | string | Timestamp of the measurement, as reported by Open-Meteo |
| `scraped_at` | string | ISO 8601 timestamp of when the record was scraped |

**Example Air Quality & Environmental Data Record:**

```json
{
  "portal": "Environmental Portals",
  "station": "Springfield, Illinois, United States",
  "aqi": 42,
  "pm25": 9.8,
  "date": "2026-08-17 09:00",
  "scraped_at": "2026-08-17T09:00:00.000Z"
}
```

***

### 🧰 Technical Stack

- **APIs:** Open-Meteo Geocoding API and Open-Meteo Air Quality API (JSON format)
- **HTTP Client:** `curl_cffi` with Chrome TLS fingerprint impersonation for reliable **Air Quality & Environmental Data** access
- **Batching:** Single combined multi-coordinate request for all matched locations
- **Date Handling:** `datetime` with timezone-aware UTC timestamps
- **Async:** `asyncio` with executor-run blocking requests for non-blocking API calls
- **Proxy:** Optional Apify Proxy with automatic no-proxy fallback on failure
- **Logging:** Apify Actor logging system
- **Platform:** Apify Actor serverless environment

***

### 📊 Data Fields Explained

#### **Location**

- **station**: The resolved location name, combining city, region, and country
- **portal**: A fixed label identifying the data category as environmental

#### **Measurements**

- **aqi**: The current US Air Quality Index — higher values indicate worse air quality
- **pm25**: The current fine particulate matter (PM2.5) concentration

#### **Timing**

- **date**: When the underlying measurement was recorded
- **scraped\_at**: When this **Air Quality & Environmental Data** record was collected

***

### 🎯 Use Cases

- **Public Health Monitoring** – Track air quality trends across cities relevant to health advisories
- **Environmental Research** – Study pollution patterns and PM2.5 levels at scale
- **Travel Planning** – Check air quality conditions before visiting or relocating to a city
- **Smart City Dashboards** – Feed live **Air Quality & Environmental Data** into municipal monitoring tools
- **Academic Studies** – Build datasets for climate, health, or urban-planning research
- **Journalism** – Source authoritative air-quality figures for environmental reporting
- **Real Estate Research** – Cross-reference neighborhood air quality with property value or desirability
- **Personal Health Tracking** – Monitor conditions in your own city or frequently visited locations

***

### 🚀 Quick Start

#### **1. Prepare Input**

Go to Apify Console and enter:

```json
{
  "cityOrKeyword": "Chicago",
  "maxResults": 20
}
```

#### **2. Run the Actor**

Click **Start**. The Actor will:

- Resolve the city or keyword into matching locations via geocoding
- Batch-query air quality for all matched locations in one request
- Normalize AQI and PM2.5 readings into clean records
- Push all results to the Dataset in a single batch

#### **3. Monitor Progress**

Console shows:

```
⚡ Fetching air quality for 'Chicago' in ultra-fast batch mode...
✅ Successfully harvested 20 records in one single batch!
🎉 Complete! Processed 20 records.
```

#### **4. View & Download Results**

- **Results Tab**: All **Air Quality & Environmental Data** records
- **Export**: JSON, CSV, Excel, or HTML
- **Filter**: By AQI level, PM2.5 value, or station
- **API Access**: Available via the Apify API

***

### ⚙️ Configuration

Single city, default result cap:

```json
{
  "cityOrKeyword": "Berlin"
}
```

Broader search with more matches:

```json
{
  "cityOrKeyword": "Springfield",
  "maxResults": 40
}
```

With proxy enabled for reliability:

```json
{
  "cityOrKeyword": "Delhi",
  "maxResults": 10,
  "proxyConfiguration": {"useApifyProxy": true}
}
```

***

### 📈 Performance

#### **Processing Speed**

- Just two total API calls per run — one geocoding lookup, one batched air-quality query
- No per-location delay needed, since all locations are fetched together
- Scales efficiently even with dozens of matched locations in a single request

#### **Resource Usage**

- Memory: Low, since only two lightweight JSON responses are processed
- Network: Two requests total per run, regardless of `maxResults`
- Proxy: Optional, with automatic fallback to a direct connection on failure

***

### ⚠️ Important Notes

#### **Legal & Compliance**

- **Fair Use**: Respects Open-Meteo's public, key-less API endpoints
- **Public Data Only**: Retrieves only publicly available **Air Quality & Environmental Data**
- **Legal**: Not medical, public-health, or legal advice — consult official environmental agencies for health-related decisions

#### **Data Quality**

- **Freshness**: Reflects Open-Meteo's near-real-time measurements at time of run
- **Completeness**: Some locations may return `"-"` for AQI or PM2.5 if no sensor data is currently available
- **Accuracy**: Sourced directly from Open-Meteo's public air-quality models and monitoring network
- **Verification**: Cross-check high-stakes figures against official government air-quality monitors

#### **Best Practices**

- Use specific, well-known city names for the most reliable geocoding matches
- Increase `maxResults` to capture more nearby stations or ambiguous city name matches
- Enable the proxy only if you experience rate limiting or connectivity issues
- Re-run periodically to track changing **Air Quality & Environmental Data** throughout the day
- Cross-reference results with local air-quality authorities for health-sensitive decisions

***

### 📄 License & Legal

**Terms of Use:**

- Use for legitimate research, monitoring, and informational purposes
- Respect Open-Meteo's API terms of use
- Attribute Open-Meteo as the original data source where required
- Use data responsibly

**Disclaimer:**
Air Quality & Environmental Data Feeds is provided as-is for research and informational purposes. Users are responsible for compliance with Open-Meteo's terms of use. This is not medical, public-health, or legal advice — always consult official environmental agencies for health-related decisions.

***

### ⚖️ Air Quality & Environmental Data Excellence

This Actor is optimized for **Air Quality & Environmental Data** research with:

- ✅ Automatic geocoding-to-coordinates resolution
- ✅ Single-batch multi-location queries for maximum speed
- ✅ US AQI and PM2.5 metrics in one clean record
- ✅ Proxy fallback for reliable access
- ✅ Real-time, single-batch Dataset push
- ✅ Production-ready code

# Actor input Schema

## `cityOrKeyword` (type: `string`):

City or station keyword (e.g., 'New York', 'London', 'Dhaka', 'Tokyo', 'Berlin').

## `maxResults` (type: `integer`):

Maximum number of stations/records to collect.

## `proxyConfiguration` (type: `object`):

Proxy settings to bypass restrictions.

## Actor input object example

```json
{
  "cityOrKeyword": "New York",
  "maxResults": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `crawlResults` (type: `string`):

No description

## `environmentalOverview` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cityOrKeyword": "New York",
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("datapilot/air-quality-environmental-data-feeds").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "cityOrKeyword": "New York",
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("datapilot/air-quality-environmental-data-feeds").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cityOrKeyword": "New York",
  "maxResults": 20
}' |
apify call datapilot/air-quality-environmental-data-feeds --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datapilot/air-quality-environmental-data-feeds"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/0HDfMLli3HgVpxE9c/builds/5ludmpHQzzOpB9VSZ/openapi.json