墨迹天气接口覆盖实况、预报、空气质量、生活指数与历史数据一次调用即可拿到一个城市的多维天气信息。它的参数设计并不复杂但四种查询模式的组合规则、日期参数的边界条件以及服务端缓存策略直接影响接入代码的健壮性。本文以参数为主线逐一拆解各模式的使用方法并结合请求示例与返回字段说明整理一套可落地的接入思路。适用场景与调用价值这个接口适合以下场景在自有应用中展示某城市的实时温度、天气现象、风力和空气质量。为出行类产品提供未来 7 天逐日预报和 24 小时逐小时趋势。展示穿衣、紫外线、运动、限行等生活指数增强内容的实用性。需要按城市名模糊查找城市并获得稳定的城市 internal_id 做后续直查。做近一个月的逐日天气回顾例如月度统计报表或历史天气对比。接口以 JSON 数组形式返回code为 0 时表示成功业务数据集中在data对象中。由于实况数据 5 分钟缓存一次短时间内的重复请求不会产生上游压力适合在页面加载时直接调用。接口能力边界在接入之前需要明确以下边界项目约定请求方法GET请求地址https://v1.apizero.cn/api/moji-weatherQPS5 / s超出后可能被限流实况缓存5 分钟历史·当月缓存30 分钟历史·过去月缓存24 小时接口支持全国 3 万 城市的实况、7 天预报、24 小时趋势、AQI、9 项生活指数、气象预警及农历信息。需要说明的是数据由墨迹天气提供属于参考性质不适合直接用于农业、保险、航运、防灾等对准确性有严格要求的专业决策场景。四种查询模式的参数设计接口通过op参数区分查询模式缺省为实况查询。城市定位有两个维度——中文名city和数字id二者二选一。整体参数关系如下参数类型必填适用模式说明citystring二选一实况、历史城市中文名支持“北京”“大化”“杭州”等idnumber二选一实况、历史城市 internal_id可先通过 search 获取opstring否全部search、history缺省为实况keywordstring是searchsearch中文、拼音、拼音首字母均可limitnumber否search返回条数1-50默认 20daystring否history查询日期支持YYYY-MM-DD、MM-DD、DDmonthstring否history查询整月格式YYYYMM模式一按城市名查实况缺省模式直接传入city参数即可接口会做模糊匹配并返回第一个结果。例如查询“大化”返回的城市名称是“大化瑶族自治县”。GET https://v1.apizero.cn/api/moji-weather?city北京这种方式的优点是简单直观适合城市列表不固定的场景缺点是每次都要做一次模糊匹配且如果城市名存在歧义例如同名区县可能返回的不是预期目标。模式二按 internal_id 直查先用搜索拿到城市的id后续请求直接使用该值GET https://v1.apizero.cn/api/moji-weather?id1205internal_id是接口内部的稳定城市标识直查可以跳过搜索步骤响应更快也避免城市名重名带来的不确定性。对于固定城市集合的应用建议在初始化阶段完成 id 映射运行时全部走直查。模式三城市搜索opsearch搜索模式用于在接入前获取城市列表参数如下GET https://v1.apizero.cn/api/moji-weather?opsearchkeyword大化limit10keyword支持三种形式中文全称、完整拼音、拼音首字母。例如输入dahua、dh或“大化”都能命中目标城市。limit控制返回条数合理设置可以避免响应体过大。搜索结果的用途有两个一是确认城市是否存在并拿到标准名称二是提取id用于后续直查。建议在应用启动或城市配置变更时执行一次搜索将结果持久化到本地配置或数据库。模式四历史天气ophistory历史查询支持单日和整月两种粒度GET https://v1.apizero.cn/api/moji-weather?ophistorycity北京day2026-05-12 GET https://v1.apizero.cn/api/moji-weather?ophistorycity北京month202604day参数有三种写法边界规则如下day 写法是否需要 month示例YYYY-MM-DD不需要2026-05-12MM-DD需要05-12month202605DD需要12month202605历史数据的返回范围遵循以下约定当前月返回 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?ophistorycity北京day2026-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, timeout10) 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: } } ]城市信息citycity对象包含以下字段字段类型说明idnumber城市 internal_id可用于后续直查namestring城市标准中文名parentstring所属省级行政区pinyinstring城市拼音全称timezonenumber时区偏移东八区为 8实况数据conditioncondition是当前天气的核心数据字段类型说明conditionstring天气现象如“多云”temperaturenumber当前温度单位摄氏度humiditynumber相对湿度wind_dirstring风向wind_levelnumber风力等级pressurenumber气压real_feelnumber体感温度uvistring紫外线强度描述sun_risenumber日出时间Unix 毫秒时间戳sun_setnumber日落时间Unix 毫秒时间戳tipsstring温馨提示使用 lunar_datestring农历日期时间戳均为毫秒级 Unix 时间戳在东八区解析时可直接使用北京时间。未来预报forecast_day / forecast_hourforecast_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必须至少提供一个同时传两个时应确认优先级是否符合预期。opsearch模式下必须提供keyword否则无法执行搜索。日期格式不合法day参数如果使用MM-DD或DD格式但未传month服务端无法确定年份YYYY-MM-DD则需要保证日期真实存在例如2026-02-30属于非法日期。响应结果与预期城市不符city参数是模糊匹配的同名的县级市、区可能返回第一个匹配项。如果对精准度有要求先调用opsearch拿到目标的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 墨迹天气 API 参数地图：四种查询模式与响应字段逐项拆解
墨迹天气接口覆盖实况、预报、空气质量、生活指数与历史数据一次调用即可拿到一个城市的多维天气信息。它的参数设计并不复杂但四种查询模式的组合规则、日期参数的边界条件以及服务端缓存策略直接影响接入代码的健壮性。本文以参数为主线逐一拆解各模式的使用方法并结合请求示例与返回字段说明整理一套可落地的接入思路。适用场景与调用价值这个接口适合以下场景在自有应用中展示某城市的实时温度、天气现象、风力和空气质量。为出行类产品提供未来 7 天逐日预报和 24 小时逐小时趋势。展示穿衣、紫外线、运动、限行等生活指数增强内容的实用性。需要按城市名模糊查找城市并获得稳定的城市 internal_id 做后续直查。做近一个月的逐日天气回顾例如月度统计报表或历史天气对比。接口以 JSON 数组形式返回code为 0 时表示成功业务数据集中在data对象中。由于实况数据 5 分钟缓存一次短时间内的重复请求不会产生上游压力适合在页面加载时直接调用。接口能力边界在接入之前需要明确以下边界项目约定请求方法GET请求地址https://v1.apizero.cn/api/moji-weatherQPS5 / s超出后可能被限流实况缓存5 分钟历史·当月缓存30 分钟历史·过去月缓存24 小时接口支持全国 3 万 城市的实况、7 天预报、24 小时趋势、AQI、9 项生活指数、气象预警及农历信息。需要说明的是数据由墨迹天气提供属于参考性质不适合直接用于农业、保险、航运、防灾等对准确性有严格要求的专业决策场景。四种查询模式的参数设计接口通过op参数区分查询模式缺省为实况查询。城市定位有两个维度——中文名city和数字id二者二选一。整体参数关系如下参数类型必填适用模式说明citystring二选一实况、历史城市中文名支持“北京”“大化”“杭州”等idnumber二选一实况、历史城市 internal_id可先通过 search 获取opstring否全部search、history缺省为实况keywordstring是searchsearch中文、拼音、拼音首字母均可limitnumber否search返回条数1-50默认 20daystring否history查询日期支持YYYY-MM-DD、MM-DD、DDmonthstring否history查询整月格式YYYYMM模式一按城市名查实况缺省模式直接传入city参数即可接口会做模糊匹配并返回第一个结果。例如查询“大化”返回的城市名称是“大化瑶族自治县”。GET https://v1.apizero.cn/api/moji-weather?city北京这种方式的优点是简单直观适合城市列表不固定的场景缺点是每次都要做一次模糊匹配且如果城市名存在歧义例如同名区县可能返回的不是预期目标。模式二按 internal_id 直查先用搜索拿到城市的id后续请求直接使用该值GET https://v1.apizero.cn/api/moji-weather?id1205internal_id是接口内部的稳定城市标识直查可以跳过搜索步骤响应更快也避免城市名重名带来的不确定性。对于固定城市集合的应用建议在初始化阶段完成 id 映射运行时全部走直查。模式三城市搜索opsearch搜索模式用于在接入前获取城市列表参数如下GET https://v1.apizero.cn/api/moji-weather?opsearchkeyword大化limit10keyword支持三种形式中文全称、完整拼音、拼音首字母。例如输入dahua、dh或“大化”都能命中目标城市。limit控制返回条数合理设置可以避免响应体过大。搜索结果的用途有两个一是确认城市是否存在并拿到标准名称二是提取id用于后续直查。建议在应用启动或城市配置变更时执行一次搜索将结果持久化到本地配置或数据库。模式四历史天气ophistory历史查询支持单日和整月两种粒度GET https://v1.apizero.cn/api/moji-weather?ophistorycity北京day2026-05-12 GET https://v1.apizero.cn/api/moji-weather?ophistorycity北京month202604day参数有三种写法边界规则如下day 写法是否需要 month示例YYYY-MM-DD不需要2026-05-12MM-DD需要05-12month202605DD需要12month202605历史数据的返回范围遵循以下约定当前月返回 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?ophistorycity北京day2026-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, timeout10) 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: } } ]城市信息citycity对象包含以下字段字段类型说明idnumber城市 internal_id可用于后续直查namestring城市标准中文名parentstring所属省级行政区pinyinstring城市拼音全称timezonenumber时区偏移东八区为 8实况数据conditioncondition是当前天气的核心数据字段类型说明conditionstring天气现象如“多云”temperaturenumber当前温度单位摄氏度humiditynumber相对湿度wind_dirstring风向wind_levelnumber风力等级pressurenumber气压real_feelnumber体感温度uvistring紫外线强度描述sun_risenumber日出时间Unix 毫秒时间戳sun_setnumber日落时间Unix 毫秒时间戳tipsstring温馨提示使用 lunar_datestring农历日期时间戳均为毫秒级 Unix 时间戳在东八区解析时可直接使用北京时间。未来预报forecast_day / forecast_hourforecast_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必须至少提供一个同时传两个时应确认优先级是否符合预期。opsearch模式下必须提供keyword否则无法执行搜索。日期格式不合法day参数如果使用MM-DD或DD格式但未传month服务端无法确定年份YYYY-MM-DD则需要保证日期真实存在例如2026-02-30属于非法日期。响应结果与预期城市不符city参数是模糊匹配的同名的县级市、区可能返回第一个匹配项。如果对精准度有要求先调用opsearch拿到目标的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