适用场景与接口定位墨迹天气 API 面向需要实时或历史天气数据的应用场景例如智能家居面板、户外活动提醒、农业辅助决策非专业级、个人天气助手等。它一次调用即可返回实况、未来 7 天逐日预报、24 小时逐时趋势、AQI、9 项生活指数、气象预警及农历信息极大减少客户端对接口的并发请求次数。接口能力边界能力项说明城市覆盖全国 3 万 城市及区县查询模式城市名模糊city、城市 ID 直查id、城市搜索opsearch、历史天气ophistory实况数据温度、体感温度、天气现象、湿度、气压、紫外线、风向风力等预报数据未来 7 天逐日预报含 AQI、24 小时逐时预报生活指数穿衣、限行、防晒、运动等 9 项指数历史天气支持单日或整月查询范围当前月到过去几个月建议 40 天内QPS 限制5 请求/秒缓存策略实况 5 分钟当月历史 30 分钟历史月 24 小时数据说明由墨迹天气提供仅供参考不可用于农业、保险、航运、防灾等专业决策请求参数与鉴权接口地址https://v1.apizero.cn/api/moji-weather请求方法GETQuery 参数详解参数必填类型说明示例city否与 id 二选一string城市中文名支持模糊匹配匹配第一个结果大化id否与 city 二选一number城市 internal_id通过 opsearch 获取直查更快1205op否string查询模式空实况search搜索城市history历史天气historykeyword否string当 opsearch 时必填支持中文、拼音、拼音首字母大化limit否number当 opsearch 时生效返回条数 1-50默认 205day否string当 ophistory 时必填单日查询格式 YYYY-MM-DD 或 MM-DD配合 month2026-05-12month否string当 ophistory 时可选整月查询格式 YYYYMM202604Header 鉴权需要在 HTTP Header 中携带 API KeyX-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?opsearchkeyword大化limit3 # 第二步用 id1205 直查跳过模糊匹配响应更快 curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/moji-weather?id12053. 查询历史天气单日curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/moji-weather?ophistorycity北京day2026-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 毫秒UTC8如sun_rise: 1778706000000对应 2026‑05‑12 06:00:00 CST。forecast_day数组长度固定为 7未来 7 天forecast_hour为 24 个条目。aqi的updatetime是 AQI 的更新时间戳不为实时数据。index数组具体项目与数量可能随城市和季节变化建议代码中做动态渲染。当查询ophistory时返回结构略有不同data下会多出history字段包含date、condition等历史数据。实际响应结构以官方文档为准。常见错误与排查错误表现可能原因排查方案HTTP 401Header 中未传或传错X-API-Key检查 Key 是否正确是否已过期HTTP 400必填参数缺失或格式错误如day不是有效日期对照 Query 参数表检查必填项和格式code ≠ 0 且 msg 含“城市不可识别”城市名不在数据库中或拼音不完全匹配先用opsearch找到准确的城市名和 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原始 Markdownhttps://apizero.cn/aidocs/moji-weather/raw.md接口调试地址https://v1.apizero.cn/api/moji-weather需携带 API Key
