墨迹天气 API 参数地图：四种查询模式与响应字段逐项拆解
墨迹天气接口覆盖实况、预报、空气质量、生活指数与历史数据，一次调用即可拿到一个城市的多维天气信息。它的参数设计并不复杂，但四种查询模式的组合规则、日期参数的边界条件，以及服务端缓存策略，直接影响接入代码的健壮性。本文以参数为主线，逐一拆解各模式的使用方法，并结合请求示例与返回字段说明，整理一套可落地的接入思路。
适用场景与调用价值
这个接口适合以下场景：
- 在自有应用中展示某城市的实时温度、天气现象、风力和空气质量。
- 为出行类产品提供未来 7 天逐日预报和 24 小时逐小时趋势。
- 展示穿衣、紫外线、运动、限行等生活指数，增强内容的实用性。
- 需要按城市名模糊查找城市，并获得稳定的城市 internal_id 做后续直查。
- 做近一个月的逐日天气回顾，例如月度统计报表或历史天气对比。
接口以 JSON 数组形式返回，code为 0 时表示成功，业务数据集中在data对象中。由于实况数据 5 分钟缓存一次，短时间内的重复请求不会产生上游压力，适合在页面加载时直接调用。
接口能力边界
在接入之前，需要明确以下边界：
| 项目 | 约定 |
|---|---|
| 请求方法 | GET |
| 请求地址 | https://v1.apizero.cn/api/moji-weather |
| QPS | 5 / s，超出后可能被限流 |
| 实况缓存 | 5 分钟 |
| 历史·当月缓存 | 30 分钟 |
| 历史·过去月缓存 | 24 小时 |
接口支持全国 3 万 + 城市的实况、7 天预报、24 小时趋势、AQI、9 项生活指数、气象预警及农历信息。需要说明的是，数据由墨迹天气提供，属于参考性质，不适合直接用于农业、保险、航运、防灾等对准确性有严格要求的专业决策场景。
四种查询模式的参数设计
接口通过op参数区分查询模式，缺省为实况查询。城市定位有两个维度——中文名city和数字id，二者二选一。整体参数关系如下：
| 参数 | 类型 | 必填 | 适用模式 | 说明 |
|---|---|---|---|---|
city | string | 二选一 | 实况、历史 | 城市中文名，支持“北京”“大化”“杭州”等 |
id | number | 二选一 | 实况、历史 | 城市 internal_id，可先通过 search 获取 |
op | string | 否 | 全部 | search、history，缺省为实况 |
keyword | string | 是（search） | search | 中文、拼音、拼音首字母均可 |
limit | number | 否 | search | 返回条数，1-50，默认 20 |
day | string | 否 | history | 查询日期，支持YYYY-MM-DD、MM-DD、DD |
month | string | 否 | history | 查询整月，格式YYYYMM |
模式一：按城市名查实况（缺省模式）
直接传入city参数即可，接口会做模糊匹配并返回第一个结果。例如查询“大化”，返回的城市名称是“大化瑶族自治县”。
GET https://v1.apizero.cn/api/moji-weather?city=北京这种方式的优点是简单直观，适合城市列表不固定的场景；缺点是每次都要做一次模糊匹配，且如果城市名存在歧义（例如同名区县），可能返回的不是预期目标。
模式二：按 internal_id 直查
先用搜索拿到城市的id，后续请求直接使用该值：
GET https://v1.apizero.cn/api/moji-weather?id=1205internal_id是接口内部的稳定城市标识，直查可以跳过搜索步骤，响应更快，也避免城市名重名带来的不确定性。对于固定城市集合的应用，建议在初始化阶段完成 id 映射，运行时全部走直查。
模式三：城市搜索（op=search）
搜索模式用于在接入前获取城市列表，参数如下：
GET https://v1.apizero.cn/api/moji-weather?op=search&keyword=大化&limit=10keyword支持三种形式：中文全称、完整拼音、拼音首字母。例如输入dahua、dh或“大化”都能命中目标城市。limit控制返回条数，合理设置可以避免响应体过大。
搜索结果的用途有两个：一是确认城市是否存在并拿到标准名称，二是提取id用于后续直查。建议在应用启动或城市配置变更时执行一次搜索，将结果持久化到本地配置或数据库。
模式四：历史天气（op=history）
历史查询支持单日和整月两种粒度：
GET https://v1.apizero.cn/api/moji-weather?op=history&city=北京&day=2026-05-12 GET https://v1.apizero.cn/api/moji-weather?op=history&city=北京&month=202604day参数有三种写法，边界规则如下：
| day 写法 | 是否需要 month | 示例 |
|---|---|---|
YYYY-MM-DD | 不需要 | 2026-05-12 |
MM-DD | 需要 | 05-12&month=202605 |
DD | 需要 | 12&month=202605 |
历史数据的返回范围遵循以下约定：
- 当前月：返回 1 号至昨天的数据。
- 历史月（早于当月）：返回完整的 30 天数据，不区分大小月。
- 建议查询近 40 天以内的数据，过早的月份可能无数据返回。
鉴权方式与请求示例
接口使用 Header 传递 API Key，具体字段名与申请方式以官方文档为准。素材中的 curl 示例使用X-API-Key作为请求头，完整的实况查询如下：
curl -sS -X GET \ -H "X-API-Key: $API_KEY" \ "https://v1.apizero.cn/api/moji-weather?city=北京"将$API_KEY替换为实际的 Key 即可运行。历史查询的 curl 示例：
curl -sS -X GET \ -H "X-API-Key: $API_KEY" \ "https://v1.apizero.cn/api/moji-weather?op=history&city=北京&day=2026-05-12"如果需要集成到服务端，Python 是非常合适的选择。以下代码使用标准库urllib，不依赖第三方 HTTP 库：
import json import urllib.parse import urllib.request API_KEY = "your_api_key_here" BASE_URL = "https://v1.apizero.cn/api/moji-weather" def fetch_weather(city: str): params = urllib.parse.urlencode({"city": city}) url = f"{BASE_URL}?{params}" req = urllib.request.Request(url, headers={"X-API-Key": API_KEY}) with urllib.request.urlopen(req, timeout=10) as resp: data = json.loads(resp.read().decode("utf-8")) if data.get("code") == 0: return data["data"] raise RuntimeError(data.get("msg")) weather = fetch_weather("北京") print(weather["summary"])响应字段解读
响应体是一个 JSON 数组，整体结构如下：
[ { "code": 0, "msg": "成功", "data": { "_cached": false, "city": {}, "condition": {}, "forecast_day": [], "forecast_hour": [], "index": [], "aqi": {}, "summary": "" } } ]城市信息（city）
city对象包含以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
id | number | 城市 internal_id，可用于后续直查 |
name | string | 城市标准中文名 |
parent | string | 所属省级行政区 |
pinyin | string | 城市拼音全称 |
timezone | number | 时区偏移，东八区为 8 |
实况数据（condition）
condition是当前天气的核心数据：
| 字段 | 类型 | 说明 |
|---|---|---|
condition | string | 天气现象，如“多云” |
temperature | number | 当前温度，单位摄氏度 |
humidity | number | 相对湿度 |
wind_dir | string | 风向 |
wind_level | number | 风力等级 |
pressure | number | 气压 |
real_feel | number | 体感温度 |
uvi | string | 紫外线强度描述 |
sun_rise | number | 日出时间，Unix 毫秒时间戳 |
sun_set | number | 日落时间，Unix 毫秒时间戳 |
tips | string | 温馨提示，使用 ` |
lunar_date | string | 农历日期 |
时间戳均为毫秒级 Unix 时间戳，在东八区解析时可直接使用北京时间。
未来预报（forecast_day / forecast_hour）
forecast_day是一个数组，每个元素代表一天的预报，主要字段包括：
predict_date：预报日期temp_day/temp_night：白天 / 夜间温度condition_day/condition_night：白天 / 夜间天气现象wind_dir_day/wind_level_day：白天风向与风力aqi_value/aqi_desc：空气质量数值与等级描述
forecast_hour是逐小时趋势，关键字段为predict_hour（小时时间戳）、temperature、condition、humidity、wind_dir、wind_level、aqi_value，适合绘制温度曲线或展示未来几小时的天气变化。
生活指数与空气质量
index数组以键值对形式返回生活指数：
[ { "name": "限行", "status": "不限行" }, { "name": "穿衣", "status": "炎热" } ]常见指数包括穿衣、限行、运动、紫外线等 9 项。aqi对象则包含value、level、description和updatetime，其中updatetime同样是毫秒级时间戳。
summary字段是一句可直接展示给用户的话，例如“大化瑶族自治县，多云，32℃，南风3级，空气优”，适合作为 UI 上的默认文案。
历史天气的日期边界
历史查询是使用中容易出错的部分，需要特别注意以下几点：
- 当前月查询只会返回 1 号到昨天的数据，今天的数据尚未归档。
- 历史月按完整 30 天返回，不区分大小月。
- 月份过久可能没有数据，建议控制在近 40 天以内。
month参数格式固定为YYYYMM，例如202604表示 2026 年 4 月。- 使用
MM-DD或DD格式时必须配合month参数，否则无法定位到具体年份。
服务端的缓存策略决定了数据的新鲜度：实况 5 分钟更新，当月历史 30 分钟更新，过去月份 24 小时更新。如果发现获取到的历史数据与预期不完全一致，可以先判断是否命中了缓存。
常见错误与排查思路
接口的详细错误码列表以官方文档为准，以下是接入阶段最常见的几类问题及排查方向：
参数二选一冲突或缺失
city与id必须至少提供一个，同时传两个时应确认优先级是否符合预期。op=search模式下必须提供keyword，否则无法执行搜索。
日期格式不合法
day参数如果使用MM-DD或DD格式但未传month，服务端无法确定年份；YYYY-MM-DD则需要保证日期真实存在，例如2026-02-30属于非法日期。
响应结果与预期城市不符
city参数是模糊匹配的，同名的县级市、区可能返回第一个匹配项。如果对精准度有要求，先调用op=search拿到目标的id，再走id直查。
限流与超时
接口 QPS 为 5/s，批量抓取时必须做本地限流，否则可能触发服务端保护。网络超时建议设置 10 秒左右的读取超时，并配合指数退避重试。
历史数据为空
排查顺序为：日期是否在近 40 天内、month格式是否为YYYYMM、day与month是否配套、查询的月份是否早于可提供范围。
工程化注意事项
缓存策略叠加
服务端已经有分钟级缓存，客户端可以在此之上再做一层短缓存。例如实况数据缓存 2 分钟、7 天预报缓存 1 小时，可以显著降低 QPS 压力。
用 id 替代城市名
固定城市列表的接入方，建议在启动时执行一次搜索，将城市名与id的映射关系持久化。运行时全部使用id直查，减少模糊匹配的不确定性，也降低请求延迟。
整点错峰
天气数据通常在整点前后更新，大量客户端会在整点集中请求。服务端任务建议在整点后的 10-20 秒再发起请求，避开高峰窗口。
降级策略
当接口超时或限流时，可以考虑以下降级方案：
- 使用上一次成功获取的预报数据，并标记数据时间。
- 缓存 24 小时内的最近一次完整响应，作为兜底。
- 页面展示层对
condition、temperature、summary等关键字段做空值保护。
数据用途合规
接口数据仅供一般参考，不应用于农业、保险、航运、防灾等专业决策场景。在页面中展示天气信息时，建议同时展示数据时间，让用户对数据时效有明确感知。
参考文档
- 接口文档：https://apizero.cn/aidocs/moji-weather
- 原始文档：https://apizero.cn/aidocs/moji-weather/raw.md