# Iqair — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Monitor real-time and historical air quality data worldwide, including global rankings, city-specific pollution details, and map visualizations. Search live city rankings and access comprehensive air quality information to track pollution levels across the globe.

**Category:** Weather | **Website:** [iqair.com/](https://iqair.com/) | **Docs:** [parse.bot/marketplace/c60726f6-31ec-4942-bed3-ab85344a9a65/iqair-com-api](https://parse.bot/marketplace/c60726f6-31ec-4942-bed3-ab85344a9a65/iqair-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/iqair/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get city air quality

Full air quality details for a specific city including current conditions, pollutant breakdown with concentrations, hourly and daily forecasts, weather data, pollen indices, and health recommendations. City, state, and country are URL slugs found in the url field of ranking endpoints (e.g. '/usa/new-york/new-york-city' yields country='usa', state='new-york', city='new-york-city').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | Yes | City URL slug (e.g. 'new-york-city', 'beijing', 'santiago'). Obtainable from the url field of get_live_city_ranking or get_world_air_quality results. |
| `country` | string | Yes | Country URL slug (e.g. 'usa', 'china', 'chile'). |
| `state` | string | Yes | State/region URL slug (e.g. 'new-york', 'beijing', 'santiago-metropolitan'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/iqair/get-city-air-quality \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country":"<string>","state":"<string>"}'
```

### Get live city ranking

Real-time global city air quality rankings sorted by AQI descending. Returns up to 122 major cities with current AQI values, geographic metadata, and follower counts. Updates hourly.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/iqair/get-live-city-ranking \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get map data

Air quality station clusters for map visualization. Returns geographic clusters with aggregated AQI values and station counts within the specified bounding box. Higher zoom levels produce more granular clusters. Useful for building air quality heatmaps.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bbox` | string | No | Bounding box as comma-separated string: minLng,minLat,maxLng,maxLat (e.g. '-122.5,37.0,-121.5,38.0'). Omitting returns global data. |
| `zoom` | integer | No | Map zoom level (1-20). Higher values return more granular clusters with fewer stations per cluster. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/iqair/get-map-data \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"bbox":"<string>","zoom":"<integer>"}'
```

### Get world air quality

Global air quality overview returning the top 15 most polluted and top 15 cleanest major cities worldwide. Each city entry includes current AQI, geographic identifiers, and a URL slug path usable with get_city_air_quality. Data updates hourly.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/iqair/get-world-air-quality \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.