WAQI Air Quality Scraper

Extract current air-quality observations from the World Air Quality Index (WAQI) for cities, monitoring stations, coordinates, station searches, and map bounding boxes. The actor returns clean, agent-friendly JSON with AQI, the dominant pollutant, PM2.5, PM10, ozone, NO2, SO2, CO, weather readings, station coordinates, observation timestamps, attribution links, and optional daily forecasts.

What this actor returns

Each dataset row represents one unique WAQI feed. The main fields are:

• station_uid, station_name, city_name, city_url
• latitude, longitude, observation_time
• aqi, aqi_category, dominant_pollutant
• pm25, pm10, o3, no2, so2, and co
• temperature_c, humidity_pct, pressure_hpa, and wind_speed_mps
• forecast_daily when WAQI supplies a forecast
• attribution_names, attribution_urls, source_url, scraped_at, and warnings

Missing measurements are returned as null, while optional arrays are returned as []. Every record has the same shape so it can be consumed reliably by AI agents, CSV exports, dashboards, and scheduled workflows.

Input modes

Cities or stations

Use locations for exact city or station feeds:

{
  "locations": ["Shanghai", "London", "@12345"],
  "maxResults": 10,
  "includeForecast": true
}

You may use a station ID such as @12345, a city name, or a WAQI geo:latitude;longitude value. The actor accepts the aliases location, city, and station when called programmatically by an AI agent.

Coordinates

Use coordinates to ask WAQI for the nearest feed to one or more points:

{
  "coordinates": [
    { "latitude": 31.2304, "longitude": 121.4737 },
    { "latitude": 51.5074, "longitude": -0.1278 }
  ]
}

Station search

Use searchQueries when you want WAQI to find stations by city, country, station name, or native-language text. The actor performs the search and then fetches the full feed for each matching station.

{ "searchQueries": ["Bangalore", "Bulgaria"], "maxResults": 25 }

Map bounds

Use bounds for station inventories inside a rectangle. Values are south,west,north,east:

{ "bounds": ["22.01,112.69,22.37,113.02"], "maxResults": 50 }

The actor also accepts a WAQI API URL or a public aqicn.org/city/{slug} URL through startUrls.

WAQI token and responsible use

Set WAQI_TOKEN as an Apify actor environment variable. Without a token, city inputs use the public AQICN city-page fallback; coordinates, searches, bounds, forecasts, and richer station fields require your own token. Register at aqicn.org/data-platform/register before scheduled or production runs. Do not put a private token in normal input; environment variables keep it out of input history and ordinary logs.

WAQI requires attribution to the World Air Quality Index project and the originating EPA or agency. The actor keeps attribution names and URLs in every row and includes the source URL for traceability. Review the current WAQI API terms before using the results. Those terms restrict redistribution, cached or archived data, paid applications, and public for-profit use unless the required agreement or permission is in place. This actor is therefore intended for authorized, compliant use; Apify PPE does not override WAQI’s terms.

Pricing

The actor defines two billable events: a small actor-start event and air-quality-record at $0.005 per unique dataset row. Your final Apify bill may also include the platform’s normal compute and proxy usage charges. The maximum result-event cost is maxResults × $0.005; for example, 25 records has a result-event cap of $0.125.

API and automation

The actor can be run from the Apify Console, API, CLI, schedules, or MCP-compatible agents. A typical API input is:

curl "https://api.apify.com/v2/acts/YOUR_USERNAME~waqi-air-quality-scraper/runs?token=YOUR_APIFY_TOKEN" \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"locations":["London"],"maxResults":1}'

Use the dataset output for current readings, and the OUTPUT key-value record for the run summary. The actor stops at maxResults, deduplicates repeated stations, retries transient HTTP failures, and reports non-fatal API warnings without adding error objects to the dataset.

JavaScript callers can use the Apify API with the same input:

const response = await fetch(
  `https://api.apify.com/v2/acts/${process.env.APIFY_USERNAME}~waqi-air-quality-scraper/runs?token=${process.env.APIFY_TOKEN}`,
  {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ locations: ['London'], maxResults: 1 }),
  },
);
console.log(await response.json());

FAQ

Does this actor need a browser or login?

No. The primary path uses the official WAQI JSON API through a lightweight HTTP crawler. A public AQICN city-page fallback is available for city inputs when no token is configured. The actor does not bypass login walls, captchas, or access controls.

What is the difference between locations and searchQueries?

Use locations for an exact city, station name, station ID, or geo feed. Use searchQueries when you want WAQI to discover matching stations by keyword, country, or native-language name. Search, coordinate, and map-bounds modes require WAQI_TOKEN.

Are pollutant values concentrations?

WAQI’s iaqi fields and the public fallback values are pollutant-specific AQI values. They are not guaranteed raw mass concentrations in a particular unit. Use the attribution and source URL fields when interpreting or displaying them.

Can I resell the data?

Review WAQI’s current terms before any redistribution, caching, paid application, or public commercial use. The actor’s Apify pricing does not grant rights beyond the source’s terms.

Local development

npm install
npm test
apify run

For production, set WAQI_TOKEN in the actor environment and use a current Apify build. The default empty input intentionally runs a small Shanghai city-page health check so Apify’s automated health test has a valid sample without additional configuration.