墨迹天气 API 参数地图：四种查询模式与响应字段逐项拆解

墨迹天气接口覆盖实况、预报、空气质量、生活指数与历史数据，一次调用即可拿到一个城市的多维天气信息。它的参数设计并不复杂，但四种查询模式的组合规则、日期参数的边界条件，以及服务端缓存策略，直接影响接入代码的健壮性。本文以参数为主线，逐一拆解各模式的使用方法，并结合请求示例与返回字段说明，整理一套可落地的接入思路。

适用场景与调用价值

这个接口适合以下场景：

• 在自有应用中展示某城市的实时温度、天气现象、风力和空气质量。
• 为出行类产品提供未来 7 天逐日预报和 24 小时逐小时趋势。
• 展示穿衣、紫外线、运动、限行等生活指数，增强内容的实用性。
• 需要按城市名模糊查找城市，并获得稳定的城市 internal_id 做后续直查。
• 做近一个月的逐日天气回顾，例如月度统计报表或历史天气对比。

接口以 JSON 数组形式返回，code为 0 时表示成功，业务数据集中在data对象中。由于实况数据 5 分钟缓存一次，短时间内的重复请求不会产生上游压力，适合在页面加载时直接调用。

接口能力边界

在接入之前，需要明确以下边界：

接口支持全国 3 万 + 城市的实况、7 天预报、24 小时趋势、AQI、9 项生活指数、气象预警及农历信息。需要说明的是，数据由墨迹天气提供，属于参考性质，不适合直接用于农业、保险、航运、防灾等对准确性有严格要求的专业决策场景。

四种查询模式的参数设计

接口通过op参数区分查询模式，缺省为实况查询。城市定位有两个维度——中文名city和数字id，二者二选一。整体参数关系如下：

模式一：按城市名查实况（缺省模式）

直接传入city参数即可，接口会做模糊匹配并返回第一个结果。例如查询“大化”，返回的城市名称是“大化瑶族自治县”。

GET https://v1.apizero.cn/api/moji-weather?city=北京

这种方式的优点是简单直观，适合城市列表不固定的场景；缺点是每次都要做一次模糊匹配，且如果城市名存在歧义（例如同名区县），可能返回的不是预期目标。

模式二：按 internal_id 直查

先用搜索拿到城市的id，后续请求直接使用该值：

GET https://v1.apizero.cn/api/moji-weather?id=1205

internal_id是接口内部的稳定城市标识，直查可以跳过搜索步骤，响应更快，也避免城市名重名带来的不确定性。对于固定城市集合的应用，建议在初始化阶段完成 id 映射，运行时全部走直查。

模式三：城市搜索（op=search）

搜索模式用于在接入前获取城市列表，参数如下：

GET https://v1.apizero.cn/api/moji-weather?op=search&keyword=大化&limit=10

keyword支持三种形式：中文全称、完整拼音、拼音首字母。例如输入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=202604

day参数有三种写法，边界规则如下：

历史数据的返回范围遵循以下约定：

• 当前月：返回 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对象包含以下字段：

实况数据（condition）

condition是当前天气的核心数据：

时间戳均为毫秒级 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