---
name: openaq-api-ingestion
description: "How to get OpenAQ API v3 data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Query OpenAQ v3 locations with a free API key

Source entry: https://signal-lab.qdt.ai/datasets/openaq-api
Provider: https://docs.openaq.org/about/about
Checked against the provider's documentation: 2026-11-06

## Access
- Needs a free API key (sign up at explore.openaq.org/register), read from the OPENAQ_API_KEY environment variable and sent in the X-API-Key header; never hardcode it.
- v1 and v2 were retired 2025-01-31 (now HTTP 410); only v3 at api.openaq.org is live.

## Request
```bash
curl -H "X-API-Key: $OPENAQ_API_KEY" 'https://api.openaq.org/v3/locations?limit=100'
```

## Format
JSON response from v3 endpoints (for example /v3/locations); exact result-object schema was not confirmed here since the endpoint was probed without a key.

## Load into pandas and Parquet
Needs Python 3 with requests, pandas and pyarrow.
```python
"""OpenAQ API v3 locations -> pandas -> Parquet. Needs a free API key in OPENAQ_API_KEY; v1/v2 are retired."""
import os
import requests
import pandas as pd

API_KEY = os.environ["OPENAQ_API_KEY"]
URL = "https://api.openaq.org/v3/locations"
params = {"limit": 100}
r = requests.get(URL, params=params, headers={"X-API-Key": API_KEY}, timeout=60)
r.raise_for_status()
results = r.json().get("results", [])
df = pd.json_normalize(results, sep=".")
df.to_parquet("openaq_locations.parquet", index=False)
print(len(df), "OpenAQ locations")
```
Needs a personal API key (OPENAQ_API_KEY); not run here.

## Limits
- Free "General use" key: 60 requests/minute, 2,000/hour (from OpenAQ rate-limits plan table); a custom paid tier covers higher use.
- One API key per individual (terms).

## Quirks
- v1 and v2 are retired (HTTP 410 since 2025-01-31); only v3 is live and it always requires a key.
- Key goes in the X-API-Key header, read from OPENAQ_API_KEY; never embed a key in code or commit it.

## Terms and attribution
- "Attribution to OpenAQ as the source data is also required when using OpenAQ services for accessing the data."
- Users "must therefore review and comply with any terms published by data providers" since per-source licences vary (CC, open-government, bespoke).
- "we provide no assurance that the data provided may be used free of any third-party claims."
- "However, utilizing our official, hosted API implementation to develop products or services that substantially duplicate or directly compete with OpenAQ’s core offerings is prohibited." "This restriction applies specifically to the use of our hosted API service, not to self-hosted instances or modified versions of the open-source code."
- "An individual is permitted to register for only one API key."
- Terms page: https://docs.openaq.org/about/terms

## Sources
- https://docs.openaq.org/about/terms: "Attribution to OpenAQ as the source data is also required when using OpenAQ services for accessing the data."
- https://docs.openaq.org/about/terms: "However, utilizing our official, hosted API implementation to develop products or services that substantially duplicate or directly compete with OpenAQ’s core offerings is prohibited."
- https://docs.openaq.org/about/terms: "This restriction applies specifically to the use of our hosted API service, not to self-hosted instances or modified versions of the open-source code."
- https://docs.openaq.org/using-the-api/api-key: "Sign up at explore.openaq.org/register to get your API key."
- https://docs.openaq.org/using-the-api/api-key: "Include your API key in the X-API-Key header of each request."
- https://docs.openaq.org/about/terms: "An individual is permitted to register for only one API key."

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab.qdt.ai/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.