# weather_fetch

**Repository Path**: hiddenlong/weather_fetch

## Basic Information

- **Project Name**: weather_fetch
- **Description**: 通过模拟网页的方式访问天气网站并返回固定格式的数据
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 天气查询 API

简洁的天气查询 HTTP API，支持全国所有城市（包括县级市）。

## 核心特性

- ✅ **支持全国城市** - 3137个城市/区县，包括所有县级市
- ✅ **智能缓存** - 30分钟缓存，减少网络请求
- ✅ **城市别名** - 自动处理历史名称（郫县→郫都）
- ✅ **简洁响应** - JSON格式，易于解析

## 快速开始

### 启动服务

```bash
python api.py [端口]
# 默认端口 8080
```

### 查询天气

```bash
# 查询城市天气
curl "http://localhost:8080/api/weather?city=成都"
curl "http://localhost:8080/api/weather?city=郫县"
curl "http://localhost:8080/api/weather?city=都江堰"
curl "http://localhost:8080/api/weather?city=简阳"
```

### 响应示例

```json
{
  "city": "成都",
  "temperature": 23.0,
  "weather": "多云",
  "wind_direction": "南",
  "wind_power": "<3 级",
  "humidity": null,
  "report_time": "2026-03-10 16:50:00",
  "cached": false,
  "source": "weather.com.cn",
  "today": {
    "date": "2026-03-10",
    "day_weather": "多云",
    "night_weather": "多云",
    "day_temp": 23.0,
    "night_temp": 10.0,
    "temperature_range": "10°C~23°C"
  },
  "tomorrow": {
    "date": "2026-03-11",
    "day_weather": "晴转多云",
    "night_weather": "多云",
    "day_temp": 25.0,
    "night_temp": 9.0,
    "temperature_range": "9°C~25°C"
  }
}
```

## 支持的城市

支持全国 **3137 个城市/区县**，包括：

- **直辖市**: 北京、天津、上海、重庆（含所有区）
- **省会城市**: 广州、成都、杭州、南京、武汉、西安等
- **地级市**: 苏州、青岛、大连、厦门、宁波等
- **县级市**: 郫都、都江堰、简阳、彭州、崇州等

**城市别名支持**：
- 郫县 → 郫都
- 灌县 → 都江堰
- 崇庆 → 崇州

## 项目结构

```
weather_fetch/
├── api.py                          # API 入口
├── src/weather_fetch/
│   ├── __init__.py                 # 包初始化
│   ├── weather_service.py          # 天气服务（核心）
│   ├── weather_scraper.py          # 天气抓取
│   ├── weather_data.py             # 数据模型
│   ├── city_code_mapper.py         # 城市编码映射
│   ├── city_database.py            # 城市数据库
│   ├── city_aliases.py             # 城市别名
│   ├── cache_manager.py            # 缓存管理
│   ├── exceptions.py               # 异常定义
│   └── data/
│       └── city_data.json          # 城市数据库（3137个城市）
└── .gitignore
```

## 代码调用

```python
from weather_fetch.weather_service import WeatherService

# 创建服务实例
service = WeatherService(skip_ssl_verify=True)

# 获取天气
weather = service.get_weather('郫县')

# 打印天气信息
print(f"{weather.city}: {weather.current.temperature}°C")
print(f"天气: {weather.current.weather}")

# 获取 JSON 格式
json_data = weather.to_json()

# 搜索城市
cities = service.search_cities('郫', limit=5)
for name, code in cities:
    print(f"{name}: {code}")
```

## 技术栈

- **数据源**: 中国天气网 (weather.com.cn)
- **城市数据库**: 3137个城市/区县
- **缓存**: 本地文件缓存（30分钟）
- **HTTP服务**: Python 内置 http.server

## 错误处理

```json
{
  "error": "City Not Found",
  "message": "未找到城市：xxx，请检查城市名称是否正确"
}
```

## 注意事项

1. **首次查询**: 某个城市首次查询时会从网络抓取数据，可能需要1-2秒
2. **缓存**: 后续查询会使用缓存，响应速度很快
3. **缓存过期**: 默认30分钟过期
4. **城市别名**: 支持历史名称（如"郫县"和"郫都"都能查询）
5. **数据来源**: 天气数据来源于中国天气网，仅供参考

## 许可证

MIT License

## 更新日志

### v2.0.0 (2026-03-10)

- ✨ 重构核心代码，简化架构
- 🏙️ 支持全国 3137 个城市/区县（包括所有县级市）
- 🎯 专注 API 功能，移除命令行工具
- 📦 内置完整城市数据库，无需在线查询
- 🔄 智能缓存机制，减少网络请求
- 🏷️ 支持城市别名（郫县→郫都）

### v1.0.0 (2026-03-10)

- ✨ 初始版本发布
- 🏙️ 支持全国主要城市
- 💾 智能缓存机制