weather-pulse#

Weather and air quality query tool. Uses two free APIs. Both require separate registration.

Two APIs, Two Registrations Required:

• Weather Data - QWeather: https://console.qweather.com
• Air Quality Data - WAQI: https://aqicn.org/api/

You need both for full features. Weather-only works without WAQI token. AQI-only works without QWeather credentials.

Quick Start#

1. Get API Credentials#

QWeather - Free 50,000 calls/month

Register to get API Host and API Key.

1. Open https://console.qweather.com and register or log in.
2. Create a project with any name (e.g. "Demo").
3. Add credentials: go to Project > Credentials > Create Credential > select API KEY.
4. Get API Host: go to Settings in the left menu > copy the value like xxxxxxx.re.qweatherapi.com.

Config ItemRequired ForWhere to GetExampleQWEATHER_API_HOSTWeatherQWeather Console > Settings > API Hostxxxxxxx.re.qweatherapi.com``QWEATHER_API_KEYWeatherQWeather Console > Project > Credentials > API KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Docs: https://dev.qweather.com/docs/start/ | Pricing: https://dev.qweather.com/docs/finance/pricing/

WAQI - Free 1,000 calls/hour

Register to get Token.

1. Open https://aqicn.org/data-platform/token/#/
2. Check the agreement box, fill in email and name, submit.
3. Check your email, click the confirmation link, get the token.

Config ItemRequired ForWhere to GetExampleWAQI_API_TOKENAir QualityWAQI email confirmation pagexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Docs: https://aqicn.org/api/ | City lookup: https://aqicn.org/city/

2. Configure Credentials#

Recommended: use environment variables. Do not put API keys in script files.

Storing API keys directly in code can cause leaks (e.g. accidental Git commits, shared devices). Use environment variables or a .env file.

Option A: Environment Variables (Recommended)

Only configure credentials for the features you need.

bash

# Weather (Linux/macOS)
export QWEATHER_API_HOST="your_api_host"
export QWEATHER_API_KEY="your_api_key"

# Weather (Windows PowerShell)
$env:QWEATHER_API_HOST = "your_api_host"
$env:QWEATHER_API_KEY = "your_api_key"

# Air Quality (all platforms)
export WAQI_API_TOKEN="your_waqi_token"
# Windows PowerShell:
$env:WAQI_API_TOKEN = "your_waqi_token"

Option B: .env File

Create a .env file in the same directory as weather.py, and load it before running:

bash

# .env file contents
QWEATHER_API_HOST=your_api_host
QWEATHER_API_KEY=your_api_key
WAQI_API_TOKEN=your_waqi_token

bash

# Linux/macOS
set -a && source .env && set +a && python scripts/weather.py ...

# Windows PowerShell
Get-Content .env | ForEach-Object { $k,$v = $_.Split('='); Set-Item "env:$k" $v }
python scripts/weather.py ...

3. Test#

bash

# Current weather (by CityId)
python scripts/weather.py 101180301

# Air quality (by city name)
python scripts/weather.py xinxiang --endpoint aqi

---

Call Method#

bash

python scripts/weather.py <location> [--endpoint ENDPOINT] [--json]

If --endpoint is omitted, defaults to now (current weather).

Location Format (Auto-Parsed)#

TypeFormatSupported EndpointsExampleCityIddigits onlyAll101180301English city nameanyAll (auto-resolved to CityId)ShanghaiChinese city nameanyAll (auto-resolved to CityId)上海Coordinateslng,lat or lat,lng (auto-detected)All113.92,35.30geo: format"geo:lat;lng" (quotes required)AQI only"geo:35.30;113.92"WAQI ID@numberAQI only@5789Current locationhereAQI onlyhere

City name input is automatically resolved to CityId via QWeather GeoAPI. No need to look up IDs manually. Coordinate input auto-detects the order (lng,lat or lat,lng both work). The geo: format uses semicolons which require quotes in shell to avoid parsing as command separator.

Available Endpoints#

EndpointSourceFree QuotaDescriptionnowQWeather50k/moCurrent weather3dQWeather50k/mo3-day daily forecast7dQWeather50k/mo7-day daily forecast10dQWeather50k/mo10-day daily forecast15dQWeather50k/mo15-day daily forecast30dQWeather50k/mo30-day daily forecast24hQWeather50k/mo24-hour hourly forecast72hQWeather50k/mo72-hour hourly forecast168hQWeather50k/mo168-hour hourly forecastindicesQWeather50k/moWeather lifestyle indices (19 types)aqiWAQI1k/hrAir quality + PM2.5/PM10 forecast

---

Data Reference#

Current Weather now#

FieldDescriptionUnittempTemperature°CfeelsLikeFeels-like temperature°Ctext / iconWeather description / icon—windDir / windScaleWind direction / wind scaleBeaufortwindSpeedWind speedkm/hhumidityHumidity%precipPrecipitation in last 1 hourmmpressureAir pressurehPavisVisibilitykmcloudCloud cover%dewDew point temperature°C

Daily Forecast 3d/7d/10d/15d/30d#

FieldDescriptionUnitfxDateDate—sunrise / sunsetSunrise / SunsetHH:MMmoonrise / moonsetMoonrise / MoonsetHH:MMmoonPhaseMoon phase—tempMax / tempMinMax temp / Min temp°CtextDay / textNightDaytime / Nighttime weather—windDirDay / windDirNightDaytime / Nighttime wind direction—windScaleDay / windScaleNightDaytime / Nighttime wind scaleBeauforthumidityHumidity%precipTotal precipitation for the daymmuvIndexUV index—pressureAir pressurehPavisVisibilitykm

Hourly Forecast 24h/72h/168h#

FieldDescriptionUnitfxTimeForecast time (ISO8601)—tempTemperature°CtextWeather description—windDir / windScaleWind direction / wind scaleBeauforthumidityHumidity%popProbability of precipitation%precipPrecipitationmmpressureAir pressurehPacloudCloud cover%dewDew point temperature°C

Lifestyle Indices indices#

19 index types available in China: exercise, car washing, dressing, fishing, UV, travel, allergy, comfort, cold/flu, pollution diffusion, air conditioning, sunglasses, makeup, clothes drying, traffic, sunscreen, etc. Overseas locations support only 5 types: exercise, car washing, dressing, fishing, UV.

FieldDescriptionnameIndex type namecategoryLevel labeltextDetailed suggestion

Air Quality aqi#

Source: WAQI (aqicn.org)

FieldDescriptionUnitaqiAir Quality Index—dominentpolDominant pollutantpm25/pm10/o3/no2pm25PM2.5μg/m³pm10PM10μg/m³coCOmg/m³no2 / o3 / so2NO₂ / O₃ / SO₂μg/m³t / hTemperature / Humidity°C / %p / wAir pressure / Wind speedhPa / km/hforecast.pm25[]7-day PM2.5 forecastavg/min/maxforecast.pm10[]7-day PM10 forecastavg/min/max

AQI levels: Good (≤50) · Moderate (≤100) · Unhealthy for Sensitive (≤150) · Unhealthy (≤200) · Very Unhealthy (≤300) · Hazardous (>300)

---

Examples#

bash

# Current weather by CityId
python scripts/weather.py 101180301

# Current weather by English city name (auto-resolved)
python scripts/weather.py Shanghai

# Current weather by Chinese city name (auto-resolved)
python scripts/weather.py 上海

# 7-day forecast
python scripts/weather.py 101180301 --endpoint 7d

# 24-hour hourly forecast
python scripts/weather.py 101180301 --endpoint 24h

# 15-day forecast by coordinates (auto-detect order)
python scripts/weather.py 113.92,35.30 --endpoint 15d
python scripts/weather.py 35.30,113.92 --endpoint 15d

# Lifestyle indices
python scripts/weather.py 101180301 --endpoint indices

# Air quality by city name
python scripts/weather.py xinxiang --endpoint aqi
python scripts/weather.py 新乡 --endpoint aqi

# Air quality by coordinates
python scripts/weather.py "geo:35.30;113.92" --endpoint aqi

# Raw JSON output
python scripts/weather.py 101180301 --json

Error Codes#

QWeather codeWAQI statusMeaning200okSuccess400errorBad parameters401errorAuthentication failed (check key or token)402—Quota exceeded403—Wrong API Host

FAQ#

Q: "Configuration item not set" error? A: You need to set the corresponding environment variables or use a .env file.

Q: How to find CityId? A: No need! Just enter the city name (Chinese or English), the script will automatically resolve it.

Q: What cities are supported? A: Beijing, Shanghai, Guangzhou, Shenzhen, Chengdu, Hangzhou, Nanjing, Zhengzhou, Xi'an, Chongqing, Wuhan, Kunming, Dubai, Singapore, Moscow, Rio de Janeiro, New York, Los Angeles, Chicago, London, Manchester, Edinburgh, Paris, Lyon, Marseille, Tokyo, Osaka, Kyoto, Berlin, Munich, Frankfurt, Sydney, Melbourne, Brisbane, all cities recognized by QWeather GeoAPI are supported.