墨迹天气 API 开发实战：从参数到工程落地的全方位解析

适用场景与接口价值在天气相关的小程序、智能家居仪表盘、旅行规划或农业辅助系统中获取准确且全面的天气数据是常见需求。墨迹天气 API 对接了官方数据源覆盖全国 3 万 城市一次调用即可同时返回实况、未来 7 天逐日预报、未来 24 小时逐时预报、AQI空气质量指数、9 项生活指数以及农历日期。对于需要快速搭建天气模块的开发者来说该接口提供了开箱即用的解决方案。接口能力边界QPS5 次/秒适用于中小流量场景。如果业务需要更高的并发建议在客户端做缓存或使用负载均衡方案。查询模式实况查询默认模式按城市名或internal_id直查。城市搜索使用opsearch通过关键字中文、拼音、首字母获取城市列表及其id。历史天气使用ophistory可查单日或整月历史数据。当月返回 1 号至昨日历史月返回完整 30 天。建议查询近 40 天内的数据更早月份可能无数据。缓存策略实况数据缓存 5 分钟当月历史数据缓存 30 分钟历史月数据缓存 24 小时。请注意接口返回的_cached字段可指示当前结果是否来自缓存。注意数据由墨迹天气官方提供仅供一般参考不可用于农业、保险、航运、防灾等专业决策场景。请求参数与鉴权方案请求 URLGET https://v1.apizero.cn/api/moji-weatherQuery 参数参数是否必填类型说明示例值city否string城市中文名如“北京”“大化”与id二选一。自动模糊匹配第一个结果。大化id否number城市 internal_id由搜索模式获取与city二选一查询速度更快。1205op否string查询模式search城市搜索history历史天气缺省为实况天气。historykeyword否stringopsearch 时必填。关键字支持中文/拼音/首字母。大化limit否numberopsearch 时可选。返回条数1-50默认 20。10day否stringophistory 时可选。查询某一天YYYY-MM-DD/MM-DD需配 month/DD需配 month。2026-05-12month否stringophistory 时可选。查询整月YYYYMM。202604鉴权方式在请求头中携带 API 密钥。认证字段为X-API-Key具体值从 API 管理后台获取。示例如下X-API-Key: your_api_key该参数在文档中标记为可选但实际生产环境必须携带否则会收到鉴权错误。curl 可运行示例以下使用curl演示四种典型场景。请将$APIZERO_API_KEY替换为你自己的密钥。1. 实况天气按城市名curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/moji-weather?city大化2. 实况天气按 internal_id速度更快curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/moji-weather?id12053. 城市搜索获取城市 idcurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/moji-weather?opsearchkeyword大化limit54. 历史天气按城市日期curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/moji-weather?ophistorycity大化day2026-05-12如果需要查整月替换day为monthcurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/moji-weather?ophistorycity大化month202605返回值解读无论哪种查询模式成功响应均为 JSON 格式顶层包含code和data字段。code为 0 表示成功非 0 则表示错误。msg字段提供可读的错误描述。实况天气返回结构data 部分字段类型说明_cachedbool是否来自缓存aqiobject空气质量详情value(指数),level(等级),description(文字描述),updatetime(更新时间戳)cityobject城市信息id,name,parent(上级行政区),pinyin,timezone(时区偏移小时)conditionobject当前天气实况condition(天气现象),temperature(摄氏),real_feel(体感温度),humidity(湿度%),pressure(气压hPa),wind_dir(风向),wind_level(风力等级),sun_rise/sun_set(日出日落时间戳),lunar_date(农历),tips(生活提示),uvi(紫外线指数描述)forecast_dayarray未来7天逐日预报每个元素包含predict_date(预测日时间戳),temp_day(日间温度),temp_night(夜间温度),condition_day/condition_night,wind_dir_day/wind_level_day,aqi_value/aqi_descforecast_hourarray未来24小时逐时预报每个元素包含predict_hour(整点时间戳),temperature,condition,aqi_value,humidity,wind_dir,wind_levelindexarray9项生活指数每个元素含name如“穿衣”“限行”和status如“炎热”“不限行”summarystring简要天气总结城市搜索返回结构当opsearch时data是一个数组每个元素包含id和name城市全称可通过limit控制返回条数。历史天气返回结构当ophistory时data是一个数组每条记录包含date(时间戳)、temp_max/temp_min、condition_day/condition_night等字段具体结构与 forecast_day 类似。常见错误处理HTTP 状态码业务 codemsg 示例可能原因及处理方式200-1城市查询不到建议使用搜索city 参数未找到匹配城市尝试opsearch获取正确 id200-2获取数据失败内部错误稍后再试401-无权限未提供有效X-API-Key或密钥过期429-请求过于频繁超出 QPS 限制请降低请求频率或加入重试机制错误时data可能为null需读取msg字段进行展示。工程化注意事项1. 优先使用id查询通过opsearch预先获取城市 id 并缓存如 localStorage 或 Redis后续实况/历史查询使用?idxxx可以跳过字符串模糊匹配响应速度更快且更稳定。2. 处理缓存标识返回的_cached字段可帮助判断数据是否为实时。对于高频轮询场景如每分钟刷新若_cached为true且数据无变化可考虑客户端直接使用上次结果减少无效解析。3. 时间戳处理返回的时间戳如sun_rise、predict_date为毫秒级 Unix 时间戳。前端使用 JavaScript 可直接new Date(timestamp)转换后段语言如 Python需/1000转换为秒。4. 历史天气查询限制当月历史数据最多只到昨日历史月支持完整 30 天。如果查询的月份跨度过大或过于久远可能返回空数据。建议客户端做好兜底展示例如显示“该时间段无历史数据”。5. 限流与重试API 的 QPS 为 5若业务场景需要更高并发可在网关层对相同城市做聚合去重或使用短时缓存如 2 秒。当收到 429 错误时建议采用指数退避策略重试初始间隔 1 秒最多重试 3 次。6. 城市名模糊匹配的潜在问题使用?city大化会自动匹配第一个结果本例为“大化瑶族自治县”。如果城市名有多个重名如“北京”只有一个建议始终先用搜索确认id避免匹配到不期望的城市。参考文档墨迹天气 API 文档页原始 Markdown 文档