和风天气 API 配置文档

🌤️ 和风天气 API 配置文档

整理时间：2026-07-29
整理人：憨包 🤗

---

官方网站 https://console.qweather.com/
账号ccl
密码 admin

📁 一、环境变量配置（.env）

在项目 .env 文件中添加以下内容：

# ============================================
# Hermes 环境变量配置
# ============================================

# 和风天气订阅项目 API KEY
QWEATHER_API_KEY=eb01a6ba05694f26862dc962fe321c32

---

🌐 二、API 请求地址

🔗 自定义域名（推荐使用）

https://na49vknkag.re.qweatherapi.com

📡 API 接口示例

1️⃣ 城市查询 / 地理编码

自定义域名版（推荐）：

url = f"https://na49vknkag.re.qweatherapi.com/geo/v2/city/lookup?location={encoded_loc}&key={API_KEY}"

官方域名版（备选）：

url = f"https://geoapi.qweather.com/geo/v2/city/lookup?location={encoded_loc}&key={API_KEY}"

2️⃣ 其他常用接口（参考）

接口名称	路径	说明
🌆 城市查询	/geo/v2/city/lookup	按城市名/坐标查城市ID
☀️ 实时天气	/v7/weather/now	获取当前天气实况
📅 逐天预报	/v7/weather/3d / 7d	3天/7天天气预报
🕐 逐时预报	/v7/weather/24h	24小时逐时预报
💨 空气质量	/v7/air/now	实时空气质量
☁️ 分钟降水	/v7/minutely/5m	未来2小时分钟级降水

---

🔧 三、代码调用示例

import requests

# API 配置
API_KEY = "xxxxxx"
BASE_URL = "https://na49vknkag.re.qweatherapi.com"  # 自定义域名

def get_city_id(city_name: str) -> dict:
    """根据城市名查询城市ID"""
    encoded_loc = requests.utils.quote(city_name)
    url = f"{BASE_URL}/geo/v2/city/lookup?location={encoded_loc}&key={API_KEY}"
    resp = requests.get(url)
    return resp.json()

def get_current_weather(city_id: str) -> dict:
    """获取指定城市的实时天气"""
    url = f"{BASE_URL}/v7/weather/now?location={city_id}&key={API_KEY}"
    resp = requests.get(url)
    return resp.json()

---

⚠️ 四、注意事项

#	注意点	说明
1️⃣	🔑 API Key 保密	不要将API Key提交到公开仓库，建议使用 .env 管理
2️⃣	🌐 域名选择	自定义域名 na49vknkag.re.qweatherapi.com 优先使用
3️⃣	🔄 官方备用	geoapi.qweather.com 作为备用域名
4️⃣	📊 请求频率	免费订阅有调用次数限制，注意不要过度请求
5️⃣	🔒 环境变量	.env 文件不要提交到 Git，已加入 .gitignore

---

📌 五、快速参考

QWEATHER_API_KEY = xxxxxxxxx
BASE_URL        = https://na49vknkag.re.qweatherapi.com
BACKUP_URL      = https://geoapi.qweather.com

---