# Weather — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.

> Get real-time weather conditions, 7-day to 40-day forecasts, air quality data, and weather alerts for any city in China. Track hourly observations and life indices to plan your activities with complete weather intelligence.

**Category:** Weather | **Website:** [weather.com.cn/](https://weather.com.cn/) | **Docs:** [parse.bot/marketplace/5532c3ea-5fff-43d7-9600-e1b2368220ff/weather-com-cn-api](https://parse.bot/marketplace/5532c3ea-5fff-43d7-9600-e1b2368220ff/weather-com-cn-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_air_quality

Retrieves national real-time Air Quality Index (AQI) rankings for Chinese cities. Results are sorted into four categories: best air quality, worst air quality, PM10 concentration ranking, and PM2.5 concentration ranking. Each city entry includes city_code, name, province, province code, and AQI/concentration value.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/get_air_quality \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_current_weather

Retrieves comprehensive weather data for a city including real-time station observations (temperature, humidity, wind, AQI), daily life indices (comfort, UV, clothing, travel, etc.), today's brief forecast with alarm info, and a short-range forecast array. Requires a city_code from search_city_weather.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_code` | string | Yes | 9-digit city code obtained from search_city_weather (e.g. '101010100' for Beijing). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/get_current_weather \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"<string>"}'
```

### get_forecast_15day

Retrieves the 15-day extended weather forecast including day/night weather codes, high/low temperatures, wind info, sunrise/sunset times, and lunar calendar dates. Requires a city_code from search_city_weather.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_code` | string | Yes | 9-digit city code obtained from search_city_weather (e.g. '101010100' for Beijing). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/get_forecast_15day \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"<string>"}'
```

### get_forecast_40day

Retrieves the 40-day long-range weather calendar for a city including historical temperature averages, lunar calendar, almanac (suit/insuit days), rain probability, and observed/forecast temperatures. Requires a city_code from search_city_weather.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_code` | string | Yes | 9-digit city code obtained from search_city_weather (e.g. '101010100' for Beijing). |
| `month` | string | No | Month in 2-digit MM format (e.g. '01' for January, '12' for December). Omitting defaults to the current month. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/get_forecast_40day \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"<string>","month":"<string>"}'
```

### get_forecast_7day

Retrieves the 5-7 day daily weather forecast for a city. Each day includes day/night weather codes, high/low temperatures, wind direction and wind speed. Requires a city_code from search_city_weather.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_code` | string | Yes | 9-digit city code obtained from search_city_weather (e.g. '101010100' for Beijing). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/get_forecast_7day \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"<string>"}'
```

### get_hourly_observations

Retrieves hourly weather observations for the past 24 hours including temperature, humidity, wind speed/direction, and AQI for each hour. May also include hourly forecast data when available. Requires a city_code from search_city_weather.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_code` | string | Yes | 9-digit city code obtained from search_city_weather (e.g. '101010100' for Beijing). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/get_hourly_observations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"<string>"}'
```

### get_weather_alerts

Retrieves all active nationwide weather alerts and warnings currently in effect across China. Each alert entry contains the location name, alert ID filename, and geographic coordinates. Returns a count of total active alerts.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/get_weather_alerts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_city_weather

Search for a city by name to retrieve its city code and metadata. Accepts Chinese characters or pinyin. Returns all matching cities, districts, and scenic spots. The returned city_code is required for all other weather endpoints.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | City name to search for, in Chinese characters or pinyin (e.g. '北京', 'shanghai', '广州'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-weather-com-cn-api-5532c3ea/search_city_weather \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```