Com APIweather.com.cn ↗
Access real-time weather, 7–40 day forecasts, AQI rankings, hourly observations, and active alerts for any Chinese city via the weather.com.cn API.
What is the Com API?
The weather.com.cn API provides 8 endpoints covering real-time conditions, multi-range forecasts (7-day, 15-day, 40-day), hourly observations, air quality rankings, and nationwide weather alerts for cities across China. Start with search_city_weather to resolve a city name or pinyin string into the 9-digit city code required by every other endpoint, then pull station-level temperature, humidity, wind, and AQI alongside daily life indices like UV, comfort, and clothing recommendations.
curl -X GET 'https://api.parse.bot/scraper/91fc294e-bc9f-47ba-b48e-d6ab94bebab7/search_city_weather?query=%E5%8C%97%E4%BA%AC' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace weather-com-cn-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: WeatherChina SDK — bounded, re-runnable; every call capped."""
from parse_apis.weather_china_api import WeatherChina, CityNotFound
client = WeatherChina()
# Search for a city by name — get the first result.
city = client.cities.search(query="北京", limit=3).first()
print(f"Found city: {city.city_name} ({city.city_code}), province: {city.province}")
# Drill into 7-day forecast via the sub-resource.
for day in city.forecasts.seven_day(limit=5):
print(f" {day.fi} ({day.fj}): high {day.fc}°C, low {day.fd}°C, wind {day.fe}")
# Extended 15-day forecast with aliased fields.
forecast = city.forecasts.fifteen_day(limit=1).first()
if forecast:
print(f"15-day first: {forecast.date} — high {forecast.high_temp}°C, sunrise {forecast.sunrise}")
# 40-day calendar with almanac data.
cal_day = city.forecasts.forty_day(month="06", limit=1).first()
if cal_day:
print(f"Calendar: {cal_day.date}, high {cal_day.hmax}°C, rain prob {cal_day.hgl}")
# Hourly observations for the city.
hourly = city.hourly.get()
print(f"Hourly data available: observations_24h present = {hourly.observations_24h is not None}")
# Nationwide air quality rankings.
aqi = client.airqualities.get()
print(f"Best AQI city: {aqi.best[0].name} ({aqi.best[0].value}), Worst: {aqi.worst[0].name} ({aqi.worst[0].value})")
# Weather alerts across China.
alerts = client.weatheralerts.get()
print(f"Active weather alerts: {alerts.count}")
# Typed error handling — catch CityNotFound for an invalid city code.
try:
client.cities.get(city_code="000000000")
except CityNotFound as exc:
print(f"City not found: {exc}")
print("exercised: cities.search / forecasts.seven_day / forecasts.fifteen_day / forecasts.forty_day / hourly.get / airqualities.get / weatheralerts.get / cities.get")
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.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | City name to search for, in Chinese characters or pinyin (e.g. '北京', 'shanghai', '广州'). |
{
"type": "object",
"fields": {
"results": "array of city objects each containing city_code, pinyin, city_name, en_name, district, province, full_info"
},
"sample": {
"data": {
"results": [
{
"pinyin": "beijing",
"en_name": "Beijing",
"district": "北京",
"province": "北京",
"city_code": "101010100",
"city_name": "北京",
"full_info": "101010100~beijing~北京~Beijing~北京~Beijing~10~100000~BJ~北京"
}
]
},
"status": "success"
}
}About the Com API
City Resolution and Real-Time Conditions
Every data request in this API is keyed on a 9-digit city_code. Use search_city_weather with a Chinese-character name or pinyin string (e.g. '北京' or 'shanghai') to get back matching cities, districts, and scenic spots, each with city_code, pinyin, city_name, en_name, district, and province fields. Once you have a code, get_current_weather returns five response objects: dataSK (real-time station observations: temp, humidity, wind, AQI), dataZS (daily life indices: comfort, UV, clothing, travel), cityDZ (today's brief forecast and any active alarm info), fc (short-range daily forecast array), and sk_detailed (extended station data).
Forecast Ranges
get_forecast_7day returns a 5–7 day array where each object carries fa (day weather code), fb (night weather code), fc (high temp), fd (low temp), and wind fields. get_forecast_15day extends this to 15 days and adds sunrise/sunset times and lunar calendar dates encoded under numeric keys (001 for day weather code, 003/004 for high/low temps, 009 for date in YYYYMMDD format). get_forecast_40day produces a calendar array covering up to 40 days and includes historical average highs/lows (hmax/hmin), lunar day (nl), almanac data (nlyf), and both observed and forecast temperatures — useful for agricultural or travel planning tools that need longer-horizon context.
Hourly Observations and Air Quality
get_hourly_observations returns up to 24 hours of station records under observations_24h.od.od2, with per-hour fields od21 (hour), od22 (temp), od23 (wind speed), od24 (wind direction), and AQI. get_air_quality requires no inputs and returns national AQI rankings split into four arrays: af (best air quality cities), ab (worst), p10 (ranked by PM10), and p25 (ranked by PM2.5). Each entry includes a (city_code), n (name), p (province), and v (AQI value). get_weather_alerts also requires no inputs and returns all currently active nationwide alerts as an array of entries with location name, alert ID, and longitude, plus a count field.
Coverage Scope
All endpoints are scoped to mainland China cities, districts, and scenic spots indexed by weather.com.cn. The city search covers Chinese-character input and pinyin, but results are limited to locations that weather.com.cn tracks — smaller townships or newly established administrative areas may not appear. The 40-day forecast includes historical baselines alongside forward projections, making it distinct from the 7-day and 15-day endpoints which carry only forecast data.
The Com API is a managed, monitored endpoint for weather.com.cn — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when weather.com.cn changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official weather.com.cn API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display real-time temperature, humidity, and AQI for a Chinese city in a travel or logistics dashboard using
get_current_weather. - Build a clothing or activity recommendation feature using the
dataZSlife indices (UV, comfort, clothing) returned byget_current_weather. - Render a 15-day forecast calendar with lunar dates and sunrise/sunset times for a Chinese-market calendar app via
get_forecast_15day. - Plot a 40-day temperature range chart against historical averages using
hmax/hminfields fromget_forecast_40day. - Monitor nationwide air quality trends by polling
get_air_qualityfor ranked PM2.5 and PM10 city lists. - Surface active weather alerts on a map by parsing the location and coordinates returned by
get_weather_alerts. - Back-fill a 24-hour temperature and wind time series for a city using the
od2hourly records fromget_hourly_observations.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does weather.com.cn have an official developer API?+
How do I look up the city code for a specific location?+
search_city_weather accepts a query parameter in either Chinese characters or pinyin and returns an array of matching cities, districts, and scenic spots. Each result includes a city_code (9-digit string) that is the required input for all other endpoints. For example, querying '北京' returns Beijing's code 101010100.What does the 40-day forecast endpoint actually include versus the 7-day and 15-day endpoints?+
get_forecast_40day is a calendar-style view: each day entry combines historical average high/low (hmax/hmin), lunar calendar information (nl, nlyf), almanac data, and forecast or observed temperatures. The 7-day and 15-day endpoints focus on day/night weather codes, actual forecast temperatures, and wind data without the historical baseline or lunar fields. The 40-day endpoint also accepts an optional month parameter to fetch a specific month's calendar.Does the API cover weather data for Taiwan, Hong Kong, or Macau?+
Does `get_weather_alerts` let me filter alerts by province or city?+
get_weather_alerts returns all active nationwide alerts in a single response; there is no input parameter to filter by region, severity, or alert type. The response includes a location name and alert ID per entry that you can filter client-side. You can fork this API on Parse and revise it to add a filtered alerts endpoint that accepts a province or city code.