# qwather
**Repository Path**: lucasliu71/qwather
## Basic Information
- **Project Name**: qwather
- **Description**: 和风天气预报
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-26
- **Last Updated**: 2026-02-11
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 和风天气 API 接口调用封装的 Python CLI 工具
## 第三方库安装
- [rich](https://rich.readthedocs.io/en/stable/introduction.html)>=14.0.0
- [requests](https://docs.python-requests.org/en/latest/index.html)>=2.32.3
- [pandas](https://pandas.pydata.org/docs/user_guide/index.html)>=2.3.0
- [PyJWT](https://pyjwt.readthedocs.io/en/stable/)>=2.10.1
- python-dotenv>=1.0.1
- [geocoder](https://geocoder3.readthedocs.io/en/stable/)>=1.38.1
```bash
pip install -r requirements.txt
```
> [!IMPORTANT]
>
> 请将 `QWEATHER_BASE_URL`, `QWEATHER_KEY_ID`, `QWEATHER_PROJECT_ID` 填写成你自己的值
>
> [QWEATHER_BASE_URL](https://console.qweather.com/setting?lang=zh), [QWEATHER_KEY_ID, QWEATHER_PROJECT_ID](https://console.qweather.com/project?lang=zh)
>
> `PRIVATE_KEY` 需要先运行该命令生成 SSH 公钥
>
> ```bash
> openssl genpkey -algorithm ED25519 -out ed25519-private.pem && \
> openssl pkey -pubout -in ed25519-private.pem > ed25519-public.pem
> ```
>
> 将 `ed25519-public.pem` 上传到项目凭据中获取 `PROJECT_ID`
>
> 并将 `ed25519-private.pem` 保存到 `data` 目录中
## 运行
```bash
git clone https://gitee.com/lucasliu71/qwather.git
```
安装过后无需进入项目目录, 直接运行该命令即可
```bash
$ python qweather -h
usage: qweather [-h] command ...
██████╗ ██╗ ██╗███████╗ █████╗ ████████╗██╗ ██╗███████╗██████╗
██╔═══██╗██║ ██║██╔════╝██╔══██╗╚══██╔══╝██║ ██║██╔════╝██╔══██╗
██║ ██║██║ █╗ ██║█████╗ ███████║ ██║ ███████║█████╗ ██████╔╝
██║▄▄ ██║██║███╗██║██╔══╝ ██╔══██║ ██║ ██╔══██║██╔══╝ ██╔══██╗
╚██████╔╝╚███╔███╔╝███████╗██║ ██║ ██║ ██║ ██║███████╗██║ ██║
╚══▀▀═╝ ╚══╝╚══╝ ╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝
positional arguments:
command
info Show information about the weather
now Show weather forecast for now
hours Show weather forecast for 24, 72 or 168 hours
days Show weather forecast for 3, 7, 10, 15 or 30 days
warning Show weather warning
indices Show weather indices for 1 or 3 days
history Show weather history for up to 10 days
```
## 实时天气预报
获取中国3000+市县区和海外20万个城市实时天气数据, 包括: 实时温度、体感温度、风力风向、相对湿度、大气压强、降水量、能见度、露点温度、云量等
### 参数解释
- `code`: 状态码
- `updateTime`: 当前 API 的最近更新时间
- `fxLink`: 当前数据的响应式页面, 便于嵌入网站或应用
- `now`: 实时天气预报
- `obsTime`: 数据观测时间
- `temp`: 温度, 默认单位: 摄氏度
- `feelsLike`: 体感温度, 默认单位: 摄氏度
- `icon`: 天气状况的图标代码, 另请参考天气图标项目
- `text`: 天气状况的文字描述, 包括阴晴雨雪等天气状态的描述
- `wind360`: 风向 360 度
- `windDir`: 风向
- `windScale`: 风力等级
- `windSpeed`: 风速, 公里/小时
- `humidity`: 相对湿度, 百分比数值
- `precip`: 过去 1 小时降水量, 默认单位: 毫米
- `pressure`: 大气压强, 默认单位: 百帕
- `vis`: 能见度, 默认单位: 公里
- `cloud`: 云量, 百分比数值. **可能为空**
- `dew`: 露点温度. **可能为空**
- `refer.sources`: 原始数据来源, 或数据源说明, **可能为空**
- `refer.license`: 数据许可或版权声明, **可能为空**
### 返回数据
```json
{
"code": "200",
"updateTime": "2020-06-30T22:00+08:00",
"fxLink": "http://hfx.link/2ax1",
"now": {
"obsTime": "2020-06-30T21:40+08:00",
"temp": "24",
"feelsLike": "26",
"icon": "101",
"text": "多云",
"wind360": "123",
"windDir": "东南风",
"windScale": "1",
"windSpeed": "3",
"humidity": "72",
"precip": "0.0",
"pressure": "1003",
"vis": "16",
"cloud": "10",
"dew": "21"
},
"refer": {
"sources": [
"QWeather",
"NMC",
"ECMWF"
],
"license": ["QWeather Developers License"]
}
}
```
## 每日天气预报
每日天气预报 API, 提供全球城市未来3-30天天气预报, 包括: 日出日落、月升月落、最高最低温度、天气白天和夜间状况、风力、风速、风向、相对湿度、大气压强、降水量、露点温度、紫外线强度、能见度等
### 参数解释
- `code`: 状态码
- `updateTime`: 当前 API 的最近更新时间
- `fxLink`: 当前数据的响应式页面, 便于嵌入网站或应用
- `daily`: 每日天气预报
- `fxDate`: 预报日期
- `sunrise`: 日出时间, **在高纬度地区可能为空**
- `sunset`: 日落时间, **在高纬度地区可能为空**
- `moonrise`: 当天月升时间, **可能为空**
- `moonset`: 当天月落时间, **可能为空**
- `moonPhase`: 月相名称
- `moonPhaseIcon`: 月相图标代码
- `tempMax`: 预报当天最高温度
- `tempMin`: 预报当天最低温度
- `iconDay`: 预报白天天气状况的图标代码
- `textDay`: 预报白天天气状况文字描述, 包括阴晴雨雪等天气状态的描述
- `iconNight`: 预报夜间天气状况的图标代码
- `textNight`: 预报晚间天气状况文字描述, 包括阴晴雨雪等天气状态的描述
- `wind360Day`: 预报白天风向 360 度
- `windDirDay`: 预报白天风向
- `windScaleDay`: 预报白天风力等级
- `windSpeedDay`: 预报白天风速, 公里/小时
- `wind360Night`: 预报夜间风向 360 度
- `windDirNight`: 预报夜间当天风向
- `windScaleNight`: 预报夜间风力等级
- `windSpeedNight`: 预报夜间风速, 公里/小时
- `precip`: 预报当天总降水量, 默认单位: 毫米
- `uvIndex`: 紫外线强度指数
- `humidity`: 相对湿度, 百分比数值
- `pressure`: 大气压强, 默认单位: 百帕
- `vis`: 能见度, 默认单位: 公里
- `cloud`: 云量, 百分比数值. **可能为空**
- `refer.sources`: 原始数据来源, 或数据源说明, **可能为空**
- `refer.license`: 数据许可或版权声明, **可能为空**
### 返回数据
```json
{
"code": "200",
"updateTime": "2021-11-15T16:35+08:00",
"fxLink": "http://hfx.link/2ax1",
"daily": [
{
"fxDate": "2021-11-15",
"sunrise": "06:58",
"sunset": "16:59",
"moonrise": "15:16",
"moonset": "03:40",
"moonPhase": "盈凸月",
"moonPhaseIcon": "803",
"tempMax": "12",
"tempMin": "-1",
"iconDay": "101",
"textDay": "多云",
"iconNight": "150",
"textNight": "晴",
"wind360Day": "45",
"windDirDay": "东北风",
"windScaleDay": "1-2",
"windSpeedDay": "3",
"wind360Night": "0",
"windDirNight": "北风",
"windScaleNight": "1-2",
"windSpeedNight": "3",
"humidity": "65",
"precip": "0.0",
"pressure": "1020",
"vis": "25",
"cloud": "4",
"uvIndex": "3"
},
... 2 more
],
"refer": {
"sources": [
"QWeather",
"NMC",
"ECMWF"
],
"license": [
"QWeather Developers License"
]
}
}
```
## 逐时天气预报
逐小时天气预报 API, 提供全球城市未来24-168小时逐小时天气预报, 包括: 温度、天气状况、风力、风速、风向、相对湿度、大气压强、降水概率、露点温度、云量
### 参数解释
- `code`: 状态码
- `updateTime`: 当前 API 的最近更新时间
- `fxLink`: 当前数据的响应式页面, 便于嵌入网站或应用
- `hourly`: 逐时天气预报
- `fxTime`: 预报时间
- `temp`: 温度, 默认单位: 摄氏度
- `icon`: 天气状况的图标代码
- `text`: 天气状况的文字描述, 包括阴晴雨雪等天气状态的描述
- `wind360`: 风向360度
- `windDir`: 风向
- `windScale`: 风力等级
- `windSpeed`: 风速, 公里/小时
- `humidity`: 相对湿度, 百分比数值
- `precip`: 当前小时累计降水量, 默认单位: 毫米
- `pop`: 逐小时预报降水概率, 百分比数值, **可能为空**
- `pressure`: 大气压强, 默认单位: 百帕
- `cloud`: 云量, 百分比数值. **可能为空**
- `dew`: 露点温度. **可能为空**
- `refer.sources`: 原始数据来源, 或数据源说明, **可能为空**
- `refer.license`: 数据许可或版权声明, **可能为空**
### 返回数据
```json
{
"code": "200",
"updateTime": "2021-02-16T13:35+08:00",
"fxLink": "http://hfx.link/2ax1",
"hourly": [
{
"fxTime": "2021-02-16T15:00+08:00",
"temp": "2",
"icon": "100",
"text": "晴",
"wind360": "335",
"windDir": "西北风",
"windScale": "3-4",
"windSpeed": "20",
"humidity": "11",
"pop": "0",
"precip": "0.0",
"pressure": "1025",
"cloud": "0",
"dew": "-25"
},
...23 more
],
"refer": {
"sources": [
"QWeather",
"NMC",
"ECMWF"
],
"license": [
"QWeather Developers License"
]
}
}
```
## 天气灾害预警
天气灾害预警API可以获取中国及全球多个国家或地区官方发布的实时天气灾害预警数据。
### 参数解释
- `code`: 状态码
- `updateTime`: 当前 API 的最近更新时间
- `fxLink`: 当前数据的响应式页面，便于嵌入网站或应用
- `warning`: 天气灾害预警
- `id`: 本条预警的唯一标识，可判断本条预警是否已经存在
- `sender`: 预警发布单位，**可能为空**
- `pubTime`: 预警发布时间
- `title`: 预警信息标题
- `startTime`: 预警开始时间，**可能为空**
- `endTime`: 预警结束时间，**可能为空**
- `status`: 预警信息的发布状态
- `level`: 预警等级
- `severity`: 预警严重等级
- `severityColor`: 预警严重等级颜色，**可能为空**
- `type`: 预警类型 ID
- `typeName`: 预警类型名称
- `urgency`: 预警信息的紧迫程度，**可能为空**
- `certainty`: 预警信息的确定性，**可能为空**
- `text` 预警详细文字描述
- `related` 与本条预警相关联的预警 ID，当预警状态为 cancel 或 update 时返回。**可能为空**
- `refer.sources` 原始数据来源，或数据源说明，**可能为空**
- `refer.license` 数据许可或版权声明，**可能为空**
### 返回数据
```json
{
"code": "200",
"updateTime": "2023-04-03T14:20+08:00",
"fxLink": "https://www.qweather.com/severe-weather/shanghai-101020100.html",
"warning": [
{
"id": "10102010020230403103000500681616",
"sender": "上海中心气象台",
"pubTime": "2023-04-03T10:30+08:00",
"title": "上海中心气象台发布大风蓝色预警[Ⅳ级/一般]",
"startTime": "2023-04-03T10:30+08:00",
"endTime": "2023-04-04T10:30+08:00",
"status": "active",
"level": "",
"severity": "Minor",
"severityColor": "Blue",
"type": "1006",
"typeName": "大风",
"urgency": "",
"certainty": "",
"text": "上海中心气象台2023年04月03日10时30分发布大风蓝色预警[Ⅳ级/一般]：受江淮气旋影响，预计明天傍晚以前本市大部地区将出现6级阵风7-8级的东南大风，沿江沿海地区7级阵风8-9级，请注意防范大风对高空作业、交通出行、设施农业等的不利影响。",
"related": ""
}
],
"refer": {
"sources": [
"12379"
],
"license": [
"QWeather Developers License"
]
}
}
```
## 天气指数预报
获取中国和全球城市天气生活指数预报数据。
- 中国天气生活指数：舒适度指数、洗车指数、穿衣指数、感冒指数、运动指数、旅游指数、紫外线指数、空气污染扩散条件指数、空调开启指数、过敏指数、太阳镜指数、化妆指数、晾晒指数、交通指数、钓鱼指数、防晒指数
- 海外天气生活指数：运动指数、洗车指数、紫外线指数、钓鱼指数
### 参数解释
- `code`: 状态码
- `updateTime`: 当前 API 的最近更新时间
- `fxLink`: 当前数据的响应式页面，便于嵌入网站或应用
- `daily`: 天气指数
- `date`: 预报日期
- `type`: 生活指数类型 ID
- `name`: 生活指数类型的名称
- `level`: 生活指数预报等级
- `category`: 生活指数预报级别名称
- `text`: 生活指数预报的详细描述，**可能为空**
- `refer.sources`: 原始数据来源，或数据源说明，**可能为空**
- `refer.license`: 数据许可或版权声明，**可能为空**
### 返回数据
```json
{
"code": "200",
"updateTime": "2021-12-16T18:35+08:00",
"fxLink": "http://hfx.link/2ax2",
"daily": [
{
"date": "2021-12-16",
"type": "1",
"name": "运动指数",
"level": "3",
"category": "较不宜",
"text": "天气较好，但考虑天气寒冷，风力较强，推荐您进行室内运动，若户外运动请注意保暖并做好准备活动。"
},
{
"date": "2021-12-16",
"type": "2",
"name": "洗车指数",
"level": "3",
"category": "较不宜",
"text": "较不宜洗车，未来一天无雨，风力较大，如果执意擦洗汽车，要做好蒙上污垢的心理准备。"
}
],
"refer": {
"sources": [
"QWeather"
],
"license": [
"QWeather Developers License"
]
}
}
```
## 天气时光机
获取最近10天的天气历史再分析数据。
### 参数解释
- `code`: 状态码
- `fxLink`: 当前数据的响应式页面，便于嵌入网站或应用
- `weatherDaily`: 当天天气数据
- `date`: 当天日期
- `sunrise`: 当天日出时间，**在高纬度地区可能为空**
- `sunset`: 日落时间，**在高纬度地区可能为空**
- `moonrise`: 当天月升时间，**可能为空**
- `moonset`: 当天月落时间，**可能为空**
- `moonPhase`: 当天月相名称
- `tempMax`: 当天最高温度
- `tempMin`: 当天最低温度
- `precip`: 当天总降水量，默认单位：毫米
- `pressure`: 大气压强，默认单位：百帕
- `humidity`: 当天相对湿度，百分比数值
- `weatherHourly`: 当天逐时天气数据
- `time`: 当天时间
- `temp`: 当天每小时温度，默认单位：摄氏度
- `icon`: 当天每小时天气状况的图标代码
- `text`: 当天每小时天气状况的文字描述，包括阴晴雨雪等天气状态的描述
- `wind360`: 当天每小时风向360角度
- `windDir`: 当天每小时风向
- `windScale`: 当天每小时风力等级
- `windSpeed`: 当天每小时风速，公里/小时
- `humidity`: 当天每小时相对湿度，百分比数值
- `precip`: 当天每小时累计降水量，默认单位：毫米
- `pressure`: 大气压强，默认单位：百帕
- `refer.sources`: 原始数据来源，或数据源说明，**可能为空**
- `refer.license`: 数据许可或版权声明，**可能为空**
### 返回数据
```json
{
"code": "200",
"fxLink": "http://hfx.link/2ax6",
"weatherDaily": {
"date": "2020-07-25",
"sunrise": "05:08",
"sunset": "19:33",
"moonrise": "09:54",
"moonset": "22:40",
"moonPhase": "峨眉月",
"tempMax": "33",
"tempMin": "23",
"humidity": "52",
"precip": "0.0",
"pressure": "1000"
},
"weatherHourly": [
{
"time": "2020-07-25 00:00",
"temp": "28",
"icon": "100",
"text": "晴",
"precip": "0.0",
"wind360": "246",
"windDir": "西南风",
"windScale": "2",
"windSpeed": "8",
"humidity": "49",
"pressure": "1001"
},
... 23 more
],
"refer": {
"sources": [
"QWeather"
],
"license": [
"QWeather Developers License"
]
}
}
```
