AQICN Getting Started: Real-time Air Quality Data (2026)

Getting started overview

Integrating with the AQICN API involves a sequence of steps designed to provide access to its air quality data services. The process begins with account creation on the AQICN platform, followed by the generation of an API key. This key authenticates requests and manages usage limits. Developers then construct and execute an initial API call, typically to retrieve real-time air quality data for a specified location. The API supports various query parameters, including geographic coordinates or specific monitoring station IDs, to tailor the data retrieval. Understanding the structure of these requests and the expected JSON response is fundamental for successful integration.

The AQICN API provides data for the Air Quality Index (AQI) and specific pollutants like PM2.5, PM10, ozone, and carbon monoxide, among others. It supports use cases ranging from personal projects to environmental monitoring and research, with a free tier available for initial development and lower-volume applications. For more extensive usage, various paid plans are offered, scaling with the number of API calls per day. The official AQICN API reference documentation details available endpoints, request parameters, and response formats.

Quick reference table

Create an account and get keys

Accessing the AQICN API requires an API key, which is obtained after creating an account. The process is initiated by visiting the AQICN API section of their website.

1. Navigate to the Signup Page: On the AQICN API page, locate the option to sign up or get an API key. This typically directs you to a registration form.

2. Complete Registration: Provide the required information, which usually includes an email address and a password. After submitting, you may need to verify your email address through a link sent to your inbox.

3. Access Your Dashboard: Once registered and logged in, you will be directed to your user dashboard. This dashboard is the central location for managing your API key and monitoring your usage.

4. Generate API Key: Within the dashboard, there will be a section dedicated to API tokens or keys. Click the button or link to generate a new API key. The key is a unique alphanumeric string that you will include in all your API requests for authentication.

5. Store Your Key Securely: It is critical to store your API key securely. Avoid hardcoding it directly into client-side code or public repositories. Environment variables or secure configuration management systems are recommended practices for handling sensitive credentials in applications, as highlighted in general API key security best practices.

AQICN offers a free tier that includes up to 500 API calls per day, suitable for development and small-scale projects. For higher request volumes, various paid plans are available, starting at $20 per month for 5000 API calls per day.

Your first request

After obtaining your API key, you can make your first request to retrieve air quality data. The primary endpoint for real-time data is typically based on geographic coordinates or a known station ID. This example demonstrates fetching real-time data for a specific location using latitude and longitude.

API endpoint structure

The general structure for a real-time data request is:

https://api.waqi.info/feed/<location>/?token=<your_api_token>

Where <location> can be a specific station ID (e.g., @2861 for Beijing US Embassy) or geographic coordinates (e.g., geo:39.9042,116.4074 for Beijing). For your first request, using geo coordinates is often the most straightforward.

Example request using cURL

Replace YOUR_API_TOKEN with the actual key you obtained from your AQICN dashboard.

curl "https://api.waqi.info/feed/geo:40.7128;-74.0060/?token=YOUR_API_TOKEN"

This cURL command requests air quality data for New York City (latitude 40.7128, longitude -74.0060).

Example request using Python

This Python script uses the requests library to make the API call and print the JSON response.

import requests
import json

API_TOKEN = "YOUR_API_TOKEN"  # Replace with your actual API token
LATITUDE = 40.7128
LONGITUDE = -74.0060

url = f"https://api.waqi.info/feed/geo:{LATITUDE};{LONGITUDE}/?token={API_TOKEN}"

try:
    response = requests.get(url)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Example response

A successful response will return a JSON object containing the air quality data. The exact structure can vary slightly but generally includes the AQI, pollutant concentrations, and station information. An abbreviated example:

{
  "status": "ok",
  "data": {
    "aqi": 52,
    "idx": 9283,
    "attributions": [
      {
        "url": "https://www.airnow.gov/",
        "name": "AirNow"
      }
    ],
    "city": {
      "geo": [
        40.7128,
        -74.0060
      ],
      "name": "New York, New York",
      "url": "https://aqicn.org/city/new-york/new-york/"
    },
    "iaqi": {
      "co": {
        "v": 2.3
      },
      "o3": {
        "v": 45.6
      },
      "pm25": {
        "v": 12.5
      }
    },
    "time": {
      "s": "2026-05-29 14:00:00",
      "tz": "-04:00",
      "v": 1685376000
    }
  }
}

The aqi field provides the overall Air Quality Index. The iaqi (individual air quality index) section details specific pollutant levels. For comprehensive details on response fields, consult the AQICN API documentation on data formats.

Common next steps

Once you have successfully made your first API call and received data, consider these common next steps for integrating AQICN data into your application:

• Error Handling: Implement robust error handling to gracefully manage API rate limits, invalid tokens, or unavailable data. The AQICN API typically returns a status: "error" along with a descriptive message in such cases.

• Data Parsing and Display: Develop logic to parse the JSON response and extract the relevant air quality metrics. You might want to display the AQI, individual pollutant levels (PM2.5, O3, CO), and the time of the last update in a user interface.

• Location-Based Queries: Explore different ways to query data. Beyond static geo-coordinates, you can integrate location services (e.g., from a user's device or a mapping API like Google Maps Geocoding API) to fetch air quality data relevant to the user's current position.

• Historical and Forecast Data: Investigate the AQICN API's capabilities for historical air quality data and forecasts, if your application requires it. These typically involve different endpoints and parameters.

• Caching: To optimize API usage and reduce the number of calls, implement client-side or server-side caching for frequently requested data, especially for locations where air quality doesn't change rapidly.

• Rate Limit Management: Monitor your API call usage against your free or paid tier limits. Implement a mechanism, such as exponential backoff, to manage requests if you encounter rate limiting errors.

• Frontend Integration: If building a web application, consider how to integrate the data into your frontend framework (e.g., React, Vue, Angular) or directly into HTML/JavaScript for display.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems:

• Invalid API Token: Double-check that you have copied your API token correctly from your AQICN dashboard. A common error is a typo or an extra space. The API will return an error status if the token is invalid or missing.

• Incorrect Endpoint or Parameters: Verify that the API endpoint URL is correct and that all required parameters (like location and token) are properly formatted. Refer to the AQICN API documentation for endpoint specifics.

• Rate Limit Exceeded: If you are on the free tier, you are limited to 500 calls per day. If you make too many requests within a short period, you might hit this limit. The API will return an error indicating a rate limit issue. Wait a while before retrying or consider upgrading your plan if sustained higher volume is needed.

• Network Issues: Ensure your development environment has an active internet connection and that no firewalls or proxy settings are blocking outgoing HTTP requests to api.waqi.info.

• CORS Issues (Client-Side): If you are making requests directly from a web browser (client-side JavaScript), you might encounter Cross-Origin Resource Sharing (CORS) errors. The AQICN API supports CORS, but ensure your browser is not blocking the request due to other security policies. Server-side requests typically avoid CORS issues.

• Location Not Found: If you are querying by geographic coordinates, ensure they are valid and within an area where AQICN has data. For station IDs, confirm the ID is correct. An error message like "Unknown station" or "Invalid geo position" might indicate this.

• Check Response Status Code: Always inspect the HTTP status code of the response. A 200 OK indicates success, while 4xx or 5xx codes point to client-side or server-side errors, respectively. For instance, a 401 Unauthorized might mean an invalid token, and a 429 Too Many Requests indicates rate limiting.