weather-pulse（天气脉冲）

weather-pulse

Weather + air quality query tool. Two free APIs — both registration links below.

⚠️ Two APIs, Two Registrations Required: - 🌤️ Weather Data → QWeather: https://console.qweather.com - 🌫️ Air Quality Data → WAQI: https://aqicn.org/api/ You need BOTH for all features. Weather-only works without WAQI token. AQI-only works without QWeather credentials.

Quick Start

1. 获取 API 凭证

和风天气 (QWeather) - 免费 50,000 次/月

注册获取 API Host + API Key

1. 打开 https://console.qweather.com 注册/登录
2. 创建项目 → 项目名任意（如 Demo）
3. 添加凭据 → 项目 → 凭据设置 → 创建凭据 → 选择 API KEY
4. 获取 API Host → 左侧菜单「设置」→ 复制 xxxxxxx.re.qweatherapi.com

📖 文档 · 定价

空气质量 (WAQI) - 免费 1,000 次/小时

注册获取 Token

1. 打开 https://aqicn.org/data-platform/token/#/
2. 勾选同意 → 填写邮箱和名字 → 提交
3. 查看邮箱 → 点击确认链接 → 获取 Token

📖 文档 · 城市查询

2. 配置凭证

⚠️ 推荐使用环境变量，不要把 KEY 写进脚本文件！

安全提醒：将 API Key 直接写入代码可能导致泄露（意外提交到 Git、共享设备等）。 请使用环境变量或 .env 文件管理凭证。

方式 A: 环境变量（推荐 · 唯一推荐）

只需配置你要用的功能对应的凭证：

# 天气功能（Linux/macOS）
export QWEATHER_API_HOST="你的API Host"
export QWEATHER_API_KEY="你的API Key"

# 天气功能（Windows PowerShell）
$env:QWEATHER_API_HOST = "你的API Host"
$env:QWEATHER_API_KEY = "你的API Key"

# 空气质量功能
$env:WAQI_API_TOKEN = "你的WAQI Token"

方式 B: .env 文件

创建 .env 文件（与 weather.py 同级），每次运行前加载：

# .env 文件内容
QWEATHER_API_HOST=你的API Host
QWEATHER_API_KEY=你的API Key
WAQI_API_TOKEN=你的WAQI Token

# 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. 运行测试

# 实况天气 (需要 CityId)
python scripts/weather.py 101180301

# 空气质量 (支持城市名)
python scripts/weather.py xinxiang --endpoint aqi

Call Method

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

Location 格式（自动智能解析）

✅ 城市名输入会自动通过和天气 GeoAPI 解析为 CityId，无需手动查 ID。 ✅ 经纬度输入自动识别顺序（经度,纬度 / 纬度,经度都支持）。 ✅ AQI 端点支持 WAQI 格式（英文城市名、@ID、geo:），无需解析。

可用端点

Data Reference

实况天气 now

逐日预报 3d/7d/10d/15d/30d

逐小时预报 24h/72h/168h

天气指数 indices

19种指数：运动、洗车、穿衣、钓鱼、紫外线、旅游、过敏、舒适度、感冒、污染扩散、空调、太阳镜、化妆、晾晒、交通、防晒。中国全部19种可用，海外仅支持 5种(运动/洗车/穿衣/钓鱼/紫外线)。

空气质量 aqi

数据来源: WAQI (aqicn.org)

AQI 等级：优(≤50) · 良(≤100) · 轻度污染(≤150) · 中度污染(≤200) · 重度污染(≤300) · 严重污染(>300)

Examples

# 实况天气 (CityId)
python scripts/weather.py 101180301

# 实况天气 (英文城市名，自动解析)
python scripts/weather.py Shanghai

# 实况天气 (中文城市名，自动解析)
python scripts/weather.py 上海

# 7天预报
python scripts/weather.py 101180301 --endpoint 7d

# 24小时逐小时
python scripts/weather.py 101180301 --endpoint 24h

# 15天预报 (经纬度，自动识别顺序)
python scripts/weather.py 113.92,35.30 --endpoint 15d
python scripts/weather.py 35.30,113.92 --endpoint 15d

# 天气指数
python scripts/weather.py 101180301 --endpoint indices

# 空气质量 (城市名)
python scripts/weather.py xinxiang --endpoint aqi
python scripts/weather.py 新乡 --endpoint aqi

# 空气质量 (经纬度方式)
python scripts/weather.py "geo:35.30;113.92" --endpoint aqi

# JSON 原始输出
python scripts/weather.py 101180301 --json

Error Codes

FAQ

Q: 提示"配置项未设置"？ A: 需要在 CONFIG 区域填写 3 个凭证，或设置环境变量。

Q: 怎么查城市 CityId？ A: 不用查了！ 直接输入城市名（中英文都行），脚本会自动解析。

Q: 支持的常用城市 A: 北京、上海、广州、深圳、天津、重庆、长沙、武汉、成都、杭州、南京、郑州、西安、新乡、东京、New York 等，只要和风天气 GeoAPI 能识别的都支持。