墨迹天气 API 最小可运行示例：实况、预报与生活指数一次搞定
适用场景与接口定位
墨迹天气 API 面向需要实时或历史天气数据的应用场景，例如智能家居面板、户外活动提醒、农业辅助决策（非专业级）、个人天气助手等。它一次调用即可返回实况、未来 7 天逐日预报、24 小时逐时趋势、AQI、9 项生活指数、气象预警及农历信息，极大减少客户端对接口的并发请求次数。
接口能力边界
| 能力项 | 说明 |
|---|---|
| 城市覆盖 | 全国 3 万+ 城市及区县 |
| 查询模式 | 城市名模糊（city）、城市 ID 直查（id）、城市搜索（op=search）、历史天气（op=history） |
| 实况数据 | 温度、体感温度、天气现象、湿度、气压、紫外线、风向风力等 |
| 预报数据 | 未来 7 天逐日预报（含 AQI）、24 小时逐时预报 |
| 生活指数 | 穿衣、限行、防晒、运动等 9 项指数 |
| 历史天气 | 支持单日或整月查询（范围：当前月到过去几个月，建议 40 天内） |
| QPS 限制 | 5 请求/秒 |
| 缓存策略 | 实况 5 分钟；当月历史 30 分钟；历史月 24 小时 |
| 数据说明 | 由墨迹天气提供，仅供参考，不可用于农业、保险、航运、防灾等专业决策 |
请求参数与鉴权
接口地址：https://v1.apizero.cn/api/moji-weather
请求方法：GET
Query 参数详解
| 参数 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
city | 否（与 id 二选一） | string | 城市中文名，支持模糊匹配（匹配第一个结果） | 大化 |
id | 否（与 city 二选一） | number | 城市 internal_id，通过 op=search 获取，直查更快 | 1205 |
op | 否 | string | 查询模式：空=实况，search=搜索城市，history=历史天气 | history |
keyword | 否 | string | 当 op=search 时必填，支持中文、拼音、拼音首字母 | 大化 |
limit | 否 | number | 当 op=search 时生效，返回条数 1-50，默认 20 | 5 |
day | 否 | string | 当 op=history 时必填（单日查询），格式 YYYY-MM-DD 或 MM-DD（配合 month） | 2026-05-12 |
month | 否 | string | 当 op=history 时可选（整月查询），格式 YYYYMM | 202604 |
Header 鉴权
需要在 HTTP Header 中携带 API Key：X-API-Key: <your_api_key>
💡 若未提供 API Key，服务端可能会返回 401 或限制访问。实际使用时请在 apizero.cn 准备获取。
最小可运行示例：Curl 命令
以下三个示例覆盖最主要的使用场景，你可以直接复制到终端运行（替换$APIZERO_API_KEY为你的真实 Key）。
1. 按城市名查实况
curl -sS -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?city=杭州"返回当前杭州的实况天气、AQI、逐时预报、未来 7 天、生活指数等所有数据。
2. 先搜索城市 ID，再直查（更高效）
# 第一步：搜索“大化”拿到 id curl -sS -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?op=search&keyword=大化&limit=3" # 第二步：用 id=1205 直查（跳过模糊匹配，响应更快） curl -sS -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?id=1205"3. 查询历史天气（单日）
curl -sS -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?op=history&city=北京&day=2026-05-12"注意：历史数据范围受缓存策略影响。当月数据可查询到昨天，历史月份可查询完整月。建议查询 40 天以内的日期，更早月份可能无数据。
响应结构与字段解读
成功响应为 JSON 格式，外层code为 0 表示成功，data包含所有天气信息。以下拆解核心字段：
{ "code": 0, "msg": "成功", "data": { "_cached": false, "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, "sun_rise": 1778706000000, "sun_set": 1778757660000, "lunar_date": "丙午年三月廿八", "tips": "防暑||中午外出请注意防暑降温。", "uvi": "中等" }, "aqi": { "value": 29, "description": "优", "level": 1, "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, "temperature": 32, "condition": "多云", "humidity": 62, "wind_dir": "南风", "wind_level": "3", "aqi_value": 29 } ], "index": [ { "name": "限行", "status": "不限行" }, { "name": "穿衣", "status": "炎热" }, { "name": "紫外线", "status": "中等" } // ... 共 9 项 ], "summary": "大化瑶族自治县，多云，32℃，南风3级，空气优。" } }字段要点说明
condition中的temperature为当前温度（℃），real_feel为体感温度。- 时间戳均为 Unix 毫秒（UTC+8），如
sun_rise: 1778706000000对应 2026‑05‑12 06:00:00 CST。 forecast_day数组长度固定为 7（未来 7 天），forecast_hour为 24 个条目。aqi的updatetime是 AQI 的更新时间戳，不为实时数据。index数组具体项目与数量可能随城市和季节变化，建议代码中做动态渲染。- 当查询
op=history时，返回结构略有不同，data下会多出history字段，包含date、condition等历史数据。实际响应结构以官方文档为准。
常见错误与排查
| 错误表现 | 可能原因 | 排查方案 |
|---|---|---|
| HTTP 401 | Header 中未传或传错X-API-Key | 检查 Key 是否正确，是否已过期 |
| HTTP 400 | 必填参数缺失或格式错误（如day不是有效日期） | 对照 Query 参数表检查必填项和格式 |
| code ≠ 0 且 msg 含“城市不可识别” | 城市名不在数据库中（或拼音不完全匹配） | 先用op=search找到准确的城市名和 id |
| 历史查询返回空数据 | 日期太早超出记录范围，或查询未来日期 | 仅查询过去 40 天内的有效日期 |
| QPS 超限 | 每秒请求超过 5 次 | 添加本地限流或重试策略，减少并发 |
返回_cached: true | 走服务端缓存，数据可能滞后 | 根据业务容忍度决定是否强制刷新（当前不支持主动清除缓存） |
工程化注意事项
- 优先使用 city_id 直查：城市搜索返回的
id是稳定的数值标识，用id参数查询可避开模糊匹配的耗时，并减少重复计算。建议在本地建立城市ID映射表。 - 合理使用缓存：实况数据缓存 5 分钟，历史月数据缓存 24 小时。如果业务需要更实时，可缩短轮询间隔，但不宜低于 5 分钟。
- 异常重试策略：对于网络波动或临时限流，建议指数退避重试（如 1s、2s、4s），最多 3 次。避免重试时冲爆 QPS。
- 数据准确性说明：接口数据仅供一般参考，不应直接用于专业决策。如果需要用于农业灌溉、保险理赔、航运调度等场景，请务必与官方气象局数据交叉验证。
- timezone 字段：
city.timezone为 UTC 偏移小时数（中国为 8），若用户终端与北京时间不同，需做时区转换。 - 农历和 tips 处理：
condition.tips为字符串，用||分隔标题与内容，建议解析为结构化显示。 - JSON 解析时注意字段类型：
wind_level在 forecast_hour 中是字符串"3"，在其他位置可能是数字3，需统一处理。
参考文档
- 官方文档：https://apizero.cn/aidocs/moji-weather
- 原始 Markdown：https://apizero.cn/aidocs/moji-weather/raw.md
- 接口调试地址：https://v1.apizero.cn/api/moji-weather（需携带 API Key）