<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 天气查询

> 接入平台气象数据，支持全国 3 万+ 城市实况、历史天气、未来 7 天、24 小时趋势、AQI、9 项生活指数、气象预警及农历，一次调用全量返回。

支持 4 种查询模式：
- ?city=北京 · 按城市名查实况（自动模糊匹配第一个）
- ?id=33 · 按 internal_id 直查（跳过搜索，更快）
- ?op=search&keyword=北京 · 仅搜索城市列表，拿 id
- ?op=history&city=北京&day=2026-05-12 · 历史天气（支持单日 / 整月）

历史天气范围：
- 当前月：返回 1 号至昨天的数据
- 历史月（≤ 上月）：返回完整 30 天
- 建议查近 40 天以内，过早的月份可能无数据

服务端缓存策略：
- 实况：5 分钟；历史·当月：30 分钟；历史·过去月：24 小时

注意：本接口气象数据由极数本源平台提供，仅供参考，不应用于农业、保险、航运、防灾等专业决策场景。

联系站长：apizero.cn

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `moji-weather` |
| 接口名称 | 天气查询 |
| 接口地址 | `https://v1.apizero.cn/api/moji-weather` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 3000 次（已认证用户） |
| 匿名每日额度 | 1000 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名可调（每日 100 次、QPS=5）；登录后每日 30 次免费、QPS=5。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `city` | `string` | 否 | 城市中文名（支持 "北京" / "大化" / "杭州"）；与 id 二选一 | `大化` |
| `id` | `integer` | 否 | 城市 internal_id（可先调 ?op=search 查询）；与 city 二选一 | — |
| `op` | `string` | 否 | 查询模式：search=城市搜索；history=历史天气；缺省=实况天气 | `history` |
| `keyword` | `string` | 否 | 【op=search】关键字，支持中文 / 拼音 / 拼音首字母 | `大化` |
| `limit` | `integer` | 否 | 【op=search】返回条数（1-50，默认 20） | — |
| `day` | `string` | 否 | 【op=history】查某一天：YYYY-MM-DD / MM-DD（需配 month）/ DD（需配 month） | `2026-05-12` |
| `month` | `string` | 否 | 【op=history】查整月：YYYYMM。当前月返回 1 号到昨天；历史月返回完整 30 天 | `202604` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | — | — |

## 5. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

```bash
curl "https://v1.apizero.cn/api/moji-weather?city=%E5%A4%A7%E5%8C%96&id=&op=history&keyword=%E5%A4%A7%E5%8C%96&limit=&day=2026-05-12&month=202604&key=YOUR_API_KEY"
```

### Python

```python
import requests

resp = requests.get(
    "https://v1.apizero.cn/api/moji-weather",
    params={
    "city": "大化",
    "id": "",
    "op": "history",
    "keyword": "大化",
    "limit": "",
    "day": "2026-05-12",
    "month": "202604",
    "key": "YOUR_API_KEY",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const params = new URLSearchParams({
  "city": "大化",
  "id": "",
  "op": "history",
  "keyword": "大化",
  "limit": "",
  "day": "2026-05-12",
  "month": "202604",
  "key": "YOUR_API_KEY",
});

const res = await fetch(`https://v1.apizero.cn/api/moji-weather?${params}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://v1.apizero.cn/api/moji-weather", nil)
	q := req.URL.Query()
	q.Set("city", "大化")
	q.Set("id", "")
	q.Set("op", "history")
	q.Set("keyword", "大化")
	q.Set("limit", "")
	q.Set("day", "2026-05-12")
	q.Set("month", "202604")
	q.Set("key", "YOUR_API_KEY")
	req.URL.RawQuery = q.Encode()

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

### PHP

```php
<?php
$url = "https://v1.apizero.cn/api/moji-weather?" . http_build_query([
    "city" => "大化",
    "id" => "",
    "op" => "history",
    "keyword" => "大化",
    "limit" => "",
    "day" => "2026-05-12",
    "month" => "202604",
    "key" => "YOUR_API_KEY",
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `data.city` | `object` | 城市信息（id/name/parent/pinyin/timezone） | — |
| `data.condition` | `object` | 【实况】温度、体感、湿度、气压、风向、风级、UVI、日出日落、农历、贴士、预警 | — |
| `data.aqi` | `object` | 【实况】空气质量：value/level/description/updatetime | — |
| `data.forecast_day` | `array` | 【实况】未来 6-7 天预报 | — |
| `data.forecast_hour` | `array` | 【实况】未来 24 小时预报 | — |
| `data.index` | `array` | 【实况】生活指数（限行/穿衣/钓鱼/化妆/洗车/感冒/运动/紫外线/万年历） | — |
| `data.summary` | `string` | 一句话天气速览 | — |
| `data.cities` | `array` | 【op=search】城市搜索结果列表 | — |
| `data.mode` | `string` | 【op=history】固定 "history" | — |
| `data.day` | `string` | 【op=history 单日】查询日期 YYYY-MM-DD | — |
| `data.month` | `string` | 【op=history】所在月份 YYYYMM | — |
| `data.item` | `object` | 【op=history 单日】当日数据（date/condition/temp_high/temp_low/wind_dir/wind_level/aqi_value/aqi_level/aqi_desc） | — |
| `data.items` | `array` | 【op=history 整月】每日数据列表（同 item 结构） | — |
| `data.range` | `object` | 【op=history 整月】返回数据起止日期 {start, end} | — |
| `data.temperature_high/low` | `int` | 【op=history 整月】当月最高/最低气温 | — |
| `data.temperature_*_average` | `int` | 【op=history 整月】高低温均值 | — |
| `data.today` | `object` | 【op=history 整月】今天的快照 | — |
| `data.last_year` | `object` | 【op=history 整月】去年今天（同期对比） | — |
| `data.best_aqi / worst_aqi` | `object` | 【op=history 整月】当月最好 / 最差的一天空气质量 | — |
| `data._cached` | `bool` | 是否命中服务端缓存（实况 5 min / 历史·当月 30 min / 历史·过去月 24 h） | — |
| `data._disclaimer` | `string` | 本次响应附带的简短免责声明（完整版见详情页 disclaimer 区） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "city": {
            "id": 1205,
            "name": "大化瑶族自治县",
            "parent": "广西壮族自治区",
            "pinyin": "dahuayaozuzizhixian",
            "timezone": 8
        },
        "condition": {
            "condition": "多云",
            "temperature": 32,
            "real_feel": 36,
            "humidity": 62,
            "pressure": 999,
            "wind_dir": "南风",
            "wind_level": 3,
            "uvi": "中等",
            "sun_rise": 1778706000000,
            "sun_set": 1778757660000,
            "lunar_date": "丙午年三月廿八",
            "tips": "防暑||中午外出请注意防暑降温。"
        },
        "aqi": {
            "value": 29,
            "level": 1,
            "description": "优",
            "updatetime": 1778756400000
        },
        "forecast_day": [
            {
                "predict_date": 1778601630000,
                "condition_day": "多云",
                "condition_night": "多云",
                "temp_day": 32,
                "temp_night": 21,
                "wind_dir_day": "南风",
                "wind_level_day": 3,
                "aqi_value": 29,
                "aqi_desc": "优"
            }
        ],
        "forecast_hour": [
            {
                "predict_hour": 1778752800000,
                "condition": "多云",
                "temperature": 32,
                "humidity": 62,
                "wind_dir": "南风",
                "wind_level": "3",
                "aqi_value": 29
            }
        ],
        "index": [
            {
                "name": "限行",
                "status": "不限行"
            },
            {
                "name": "穿衣",
                "status": "炎热"
            }
        ],
        "summary": "大化瑶族自治县，多云，32℃，南风3级，空气优。",
        "_cached": false
    }
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 缺少 city / id 参数，或参数格式错误 |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5000` | `—` | 城市数据库查询失败（极少出现） |
| `5020` | `—` | 服务天气服务不可用 / 超时 |
| `5021` | `—` | 服务返回数据格式异常 / 解析失败 |

## 9. 变更日志

- **1.1.0** (2026-05-15)
  - 【重大功能】新增 op=history：查过去某一天/整月的真实历史天气
  - 支持 day=YYYY-MM-DD 单日查询，自动推月份
  - 支持 month=YYYYMM 整月查询；当前月返回 1 号 ~ 昨天，历史月返回完整 30 天
  - 返回字段：当日天气描述 / 高低温 / 风向风力 / AQI；整月还含去年同期、最好/最差空气日
  - 服务端按月缓存：当前月 30 分钟、历史月 24 小时
  - 服务能查到的最早日期约今天往前 40 天
- **1.0.0** (2026-05-14)
  - 首次上线
  - 支持城市名 / internal_id / 拼音 / 拼音首字母 检索
  - 实况一次返回：当前天气 + 未来 7 天 + 24 小时 + AQI + 9 项生活指数 + 气象预警 + 农历
  - 服务端 5 分钟缓存，device UID 复用

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/moji-weather`

Source: `https://apizero.cn/aidocs/moji-weather/raw.md`
Last updated: 2026-08-10T07:04:08+08:00