最小可运行示例：墨迹天气 API 从实况到历史数据的全量调用

适用场景墨迹天气 API 为开发者提供了接入全国 3 万 城市天气数据的统一入口一次请求即可同时获得实况天气、空气质量、未来 7 天预报、24 小时趋势、9 项生活指数、气象预警及农历信息。典型的应用场景包括在智能家居面板上显示当地实时温湿度与穿衣建议为户外活动应用骑行、徒步提供未来 7 天逐日天气趋势农业辅助系统需要回顾过去 40 天内的历史天气记录企业内部管理后台展示各分公司的 AQI 动态与紫外线强度「最小可运行示例」意味着你只需一个 curl 命令、一个 API Key就可以快速拿到结构化数据无需搭建复杂框架即可验证接口可用性是任何天气类应用开发的起点。接口能力边界特性说明请求方式GET基础地址https://v1.apizero.cn/api/moji-weather查询模式缺省实况预报、opsearch城市搜索、ophistory历史天气实况缓存5 分钟历史缓存当月30 分钟历史缓存过去月24 小时QPS 限制5 次/秒数据来源墨迹天气官方数据注意数据仅供一般性参考不应用于农业保险、航运调度、防灾抗灾等专业决策场景。建议以当地气象台发布为准。鉴权方式该 API 通过 HTTP 请求头传递 API Key字段名为X-API-Key。获取方式登录对应平台如 该接口服务后在个人中心申请。建议将 Key 写入环境变量以避免硬编码泄露例如在终端执行export MOJI_API_KEYyour_actual_api_key_here后续所有 curl 示例均使用$MOJI_API_KEY引用该变量。参数详解Query 参数参数名必填类型说明示例city否string城市中文名支持部分县级市与id二选一。自动模糊匹配第一个结果city大化id否number城市 internal_id通过搜索模式获取。跳过城市匹配查询更快id1205op否string查询模式search城市搜索history历史天气缺省实况预报ophistorykeyword否string仅在opsearch时有效支持中文/拼音/首字母keyword大化limit否number仅在opsearch时有效返回条数 1-50默认 20limit5day否string仅在ophistory时有效目标日期YYYY-MM-DD或MM-DDmonth或DDmonthday2026-05-12month否string仅在ophistory时有效目标月份YYYYMM。当前月返回 1 号到昨天历史月返回整月 30 天month202604Header 参数参数名类型说明X-API-KeystringAPI 密钥必填通过请求头发送最小可运行示例curl1. 实况 预报查询最常用直接使用城市名进行查询接口会返回实况天气、AQI、未来 7 天逐日预报、24 小时逐时预报、生活指数和摘要。curl -sS \ -H X-API-Key: $MOJI_API_KEY \ https://v1.apizero.cn/api/moji-weather?city深圳若你知道城市的 internal_id可通过搜索模式获得建议改用 id 查询响应速度更快curl -sS \ -H X-API-Key: $MOJI_API_KEY \ https://v1.apizero.cn/api/moji-weather?id12052. 城市搜索 — 获取 internal_id在集成之前先调用搜索接口找到目标城市的确切 ID后续查询可直接使用该 ID 避免模糊匹配。curl -sS \ -H X-API-Key: $MOJI_API_KEY \ https://v1.apizero.cn/api/moji-weather?opsearchkeyword深圳limit3返回示例中data是一个城市数组每个对象包含id、name、parent、pinyin等字段。取第一个结果的id即可。3. 历史天气查询查询指定城市在指定日期的历史天气。注意历史数据范围当前月返回 1 号到昨天历史月≤ 上月返回完整 30 天。建议查询距今天 40 天以内的数据更早的月份可能无有效记录。curl -sS \ -H X-API-Key: $MOJI_API_KEY \ https://v1.apizero.cn/api/moji-weather?ophistoryid1205day2026-05-12若要查整月的数据使用month参数替代daycurl -sS \ -H X-API-Key: $MOJI_API_KEY \ https://v1.apizero.cn/api/moji-weather?ophistoryid1205month202604返回结果中data字段的结构与实况查询不同它包含一个list数组若查单日或按日期分组的对象若查整月具体字段需根据实际响应体解析。返回值解读以实况查询为例响应 JSON 结构如下节选部分字段做注释{ code: 0, msg: 成功, data: { _cached: false, city: { id: 1205, name: 大化瑶族自治县, parent: 广西壮族自治区, pinyin: dahuayaozuzizhixian, timezone: 8 }, condition: { temperature: 32, humidity: 62, condition: 多云, wind_dir: 南风, wind_level: 3, pressure: 999, real_feel: 36, uvi: 中等, sun_rise: 1778706000000, sun_set: 1778757660000, tips: 防暑||中午外出请注意防暑降温。, lunar_date: 丙午年三月廿八 }, 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, temperature: 32, condition: 多云, humidity: 62, wind_dir: 南风, wind_level: 3, aqi_value: 29 } ], index: [ { name: 限行, status: 不限行 }, { name: 穿衣, status: 炎热 } ], summary: 大化瑶族自治县多云32℃南风3级空气优。 } }关键字段说明字段路径类型含义备注data._cachedboolean本次响应是否来自缓存true 表示命中服务端缓存data.cityobject城市基础信息包括 ID、中文名、上级行政区、时区data.conditionobject实况天气temperature为摄氏温度sun_rise/sun_set为毫秒时间戳UTC8 时区data.aqiobject空气质量value为 AQI 指数level为等级1优2良…data.forecast_dayarray未来 7 天逐日预报每个元素包含白/夜间天气、温度、风向、AQIdata.forecast_hourarray未来 24 小时逐时预报每个元素包含小时时间戳、温度、湿度、风向data.indexarray生活指数包含名称如穿衣、紫外线和状态描述data.summarystring自然语言概况可直接展示给最终用户所有时间戳均为 Unix 毫秒数13 位需在客户端转换为本地时间。例如 JavaScript 中new Date(1778756400000)。常见错误处理HTTP 状态码与业务码200 code 0请求成功data为有效数据。200 code ≠ 0业务错误msg会给出具体原因。常见场景-1缺少必须参数既没有 city 也没有 id。-2城市未找到city 模糊匹配失败或 id 不存在。-3历史日期无效超出支持范围或格式错误。-100API Key 无效或未传递。429QPS 超限等待 1 秒后重试。502/503服务端临时故障建议退避重试。排查建议确保X-API-Key请求头正确传递。可以先用-v模式查看 curl 实际发送的请求头。若使用city参数注意城市名称不要包含“市”、“省”等后缀例如“北京”而非“北京市”“大化”而非“大化瑶族自治县”。模糊匹配返回第一个结果如果多个城市同名建议先用opsearch获取准确 ID。历史查询时遇到无数据注意当前月只能查昨天之前且建议日期在 40 天内。工程化注意事项缓存策略每次调用前检查_cached字段。若你的应用需要最新实况可以在 5 分钟内主动刷新若对时效要求不敏感可复用服务端缓存的数据减少调用次数。ID 重用对稳定使用的城市建议先在开发阶段通过搜索接口查询 ID然后硬编码或存储在配置中后续所有请求都使用id参数省去每次的城市匹配开销。时间戳处理所有时间字段均为 UTC8 时区的毫秒时间戳返回字段中无时区偏移量额外标注。在非东八区客户端使用时需注意手动转换。QPS 控制接口限制 5 次/秒若需要批量查询多个城市建议使用 Promise.all 或并发池控制并在失败时实现指数退避重试。数据用途声明文档明确数据不适用于专业决策场景应用内应在免责声明或使用条款中提示用户。错误重试对于 5xx 错误或 429 限流建议实现至少 3 次重试间隔 1 秒、2 秒、4 秒依次递增。参考文档接口文档页https://apizero.cn/aidocs/moji-weather原始 Markdown 文档https://apizero.cn/aidocs/moji-weather/raw.md