IQAir Getting Started: API Key and First Request (2026)

Getting started overview

Integrating with the IQAir AirVisual API involves a series of steps to ensure proper access and data retrieval. This guide outlines the process from account creation and API key acquisition to making your initial API call. The IQAir API provides access to real-time and forecast air quality data for over 10,000 locations globally, suitable for various applications including environmental monitoring and health platforms. The API utilizes a RESTful architecture, authenticating requests via an API key appended as a query parameter.

Before making requests, developers need to review the IQAir API documentation to understand the available endpoints and data structures. The process typically involves:

1. Signing up for an IQAir account.
2. Generating or locating your API key within the developer dashboard.
3. Constructing an API request to a specific endpoint, including your API key.
4. Processing the JSON response.

Here is a quick reference table for the getting started process:

Create an account and get keys

To begin using the IQAir AirVisual API, you must first create an account and obtain an API key. IQAir offers a Developer Plan that provides 500 API calls per day for free, which is suitable for initial testing and development.

1. Navigate to the IQAir API Pricing Page: Go to the IQAir Air Quality Data API pricing page. This page lists the available plans, including the free Developer Plan and paid tiers such as the Startup Plan.

2. Select a Plan: Choose the Developer Plan to sign up for a free account. Follow the prompts to register with your email address and create a password. If you require higher call limits or additional features, you can select one of the paid plans, such as the Startup Plan, which starts at $99/month for 50,000 API calls/day.

3. Access Your Dashboard: After successful registration, you will be directed to your IQAir developer dashboard.

4. Locate Your API Key: Your API key is prominently displayed within your developer dashboard. It is a unique alphanumeric string that authenticates your requests to the API. Keep this key secure, as it grants access to your API call quota and data.

The API key is a crucial component for all requests. It is typically passed as a query parameter named key in your API calls. For example, a request might look like https://api.iqair.com/v2/KEY_ENDPOINT?key=YOUR_API_KEY.

Your first request

Once you have an API key, you can make your first request to the IQAir AirVisual API. This example demonstrates how to retrieve current air quality data for a specific location using the city,state,country endpoint. We will use cURL for this example, which is a command-line tool for making HTTP requests and is commonly available on most operating systems. This method aligns with the IQAir API reference for making requests.

For this example, we will query the current air quality data for London, England, United Kingdom.

curl "https://api.iqair.com/v2/city?city=London&state=England&country=United%20Kingdom&key=YOUR_API_KEY"

Replace YOUR_API_KEY with the actual API key from your IQAir developer dashboard.

Expected JSON Response

A successful request will return a JSON object containing current air quality data. The structure will generally resemble the following (truncated for brevity):

{
  "status": "success",
  "data": {
    "city": "London",
    "state": "England",
    "country": "United Kingdom",
    "location": {
      "type": "Point",
      "coordinates": [
        -0.127758,
        51.507351
      ]
    },
    "current": {
      "weather": {
        "ts": "2026-05-29T10:00:00.000Z",
        "pr": 1013,
        "hu": 65,
        "ws": 3.6,
        "wd": 270,
        "ic": "04d"
      },
      "pollution": {
        "ts": "2026-05-29T10:00:00.000Z",
        "aqius": 35,
        "mainus": "o3",
        "aqicn": 11,
        "maincn": "o3"
      }
    }
  }
}

This response includes details such as the city, state, country, coordinates, current weather conditions (e.g., pressure, humidity, wind speed), and pollution levels (e.g., AQI US, main pollutant). For a comprehensive understanding of all fields, consult the IQAir API reference documentation.

Common next steps

After successfully making your first API call, you can explore more advanced features and integrations with the IQAir AirVisual API:

• Explore Other Endpoints: The IQAir API offers various endpoints for different data needs. Besides current city data, you can retrieve forecast data, data for specific stations, or even a list of supported countries, states, and cities. Refer to the API reference for a full list of available endpoints and their parameters.

• Integrate with an SDK: While cURL is useful for testing, integrating an official SDK can streamline development. IQAir provides SDKs for Python, JavaScript, Java, PHP, Go, Ruby, and C#. Using an SDK can simplify request construction, error handling, and data parsing.

• Handle Rate Limits: Be aware of the API rate limits associated with your plan (e.g., 500 calls/day for the Developer Plan). Implement retry logic with exponential backoff for transient errors to ensure your application remains resilient. The IETF RFC 7231 discusses retry mechanisms in HTTP.

• Error Handling: Implement robust error handling in your application. The API returns specific status codes and error messages for issues such as invalid API keys, incorrect parameters, or rate limit excesses. Check the status field in the JSON response and handle non-success values appropriately.

• Data Visualization: Consider integrating the retrieved air quality data into a front-end application for visualization. Libraries like D3.js or Leaflet.js can be used to display air quality maps or charts, providing a user-friendly experience.

• Upgrade Your Plan: If your application requires higher API call volumes or access to commercial features, consider upgrading to one of the paid plans offered by IQAir.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to troubleshoot some frequent problems:

• Invalid API Key:

  • Symptom: The API returns an error message indicating an invalid or missing API key, often with a 401 Unauthorized or similar status.
  • Solution: Double-check that you have copied your API key correctly from your IQAir developer dashboard. Ensure there are no leading or trailing spaces, and that the key is exactly as provided. Verify that the key query parameter is present in your request URL.

• Incorrect Endpoint or Parameters:

  • Symptom: The API returns an error indicating a resource not found (404 Not Found) or an invalid parameter, often with a 400 Bad Request status.
  • Solution: Review the IQAir API reference documentation to ensure you are using the correct endpoint URL and that all required parameters (e.g., city, state, country) are spelled correctly and provided in the expected format. Remember to URL-encode special characters in parameters, such as spaces (e.g., United%20Kingdom).

• Rate Limit Exceeded:

  • Symptom: The API returns an error indicating that your rate limit has been exceeded, often with a 429 Too Many Requests status.
  • Solution: If you are on the free Developer Plan, you are limited to 500 calls per day. Wait until your daily limit resets, or consider upgrading your IQAir plan for higher call quotas. For development, cache responses to avoid repetitive calls for static data.

• Network Issues:

  • Symptom: The request times out or fails to connect to the API server.
  • Solution: Verify your internet connection. If you are behind a firewall or proxy, ensure that it allows outgoing connections to api.iqair.com. Try making a simple request to another public API (e.g., a Google Maps Geocoding API call) to confirm general network connectivity.

• JSON Parsing Errors:

  • Symptom: Your application receives the response but fails to parse the JSON data.
  • Solution: Ensure your JSON parser is correctly configured. Use a JSON linter or validator (available online) to inspect the raw response and confirm it is valid JSON. This can help identify issues like malformed responses, though the IQAir API typically returns well-formed JSON.