天气预报
查询指定坐标的实时天气、分钟级降水、逐小时预报、未来 7 日预报及气象预警。
- 稳定可用
- 会员额度
- 实时
- 分钟降水
- 24 小时
- 7 天
500 次/月
每月免费额度
用完后按次计费。
接口概述
基于彩云天气数据服务,提供指定地理位置的实时天气、分钟级降水预报、逐小时天气趋势、未来 7 日天气预报及气象预警信息。接口采用统一 JSON 数据格式,支持通过经纬度查询,适用于天气应用、智能设备、自动化任务、出行服务及其他需要气象数据的业务场景。
接口概览
| 接口名称 | 天气预报 |
|---|---|
| 请求地址 | https://api.yibudo.com/v1/weather |
| 请求方式 | GET |
| 响应格式 | JSON |
| 身份认证 | 请求头 Bearer,或查询参数 key |
| 查询方式 | 经纬度坐标 |
| 默认位置 | 经度 118.946778,纬度 25.850346 |
| 调用限制 | 见计费说明 |
| 数据更新 | 以实际更新频率为准 |
功能说明
| 功能模块 | 数据内容 |
|---|---|
| 实时天气 | 当前气温、体感温度、天气状况、相对湿度、风速、风向、空气质量 |
| 分钟级降水 | 未来 2 小时逐分钟雷达降水强度及降水趋势描述 |
| 逐小时预报 | 未来 24 小时逐小时气温、天气状况及趋势信息 |
| 未来 7 日预报 | 每日天气状况、最高气温、最低气温、日出日落、降水量与降水概率 |
| 气象预警 | 当前有效的气象预警。无预警时返回空数组 |
不同地理位置及数据源状态可能影响部分气象数据的可用性,具体以接口实际响应为准。
调用规则
身份认证
请求头 Authorization: Bearer <API_KEY>,或查询参数 key。公开调用时,key 填控制台签发的 ybdo_pub_ 值,并附带 bind。
数据时效
天气数据由彩云天气提供。更新时间受地区覆盖、数据周期和网络状态影响。
使用声明
结果仅供参考,不作为专业判断依据。请自行核实后再使用。 预报结果不应单独用于灾害应急、航空航海或其他专业安全决策。数据异常请发到 complaint@yibudo.com,并附上当次 request_id。
计费说明
买断套餐
| 档位 | 次数 | 单价 | 合计 |
|---|---|---|---|
| 基础套餐 | 10,000 次 | ¥0.00080/次 | ¥8.00 |
| 进阶套餐 | 50,000 次 | ¥0.00060/次 | ¥30.00 |
| 大额套餐 | 200,000 次 | ¥0.00045/次 | ¥90.00 |
一次买断。基础套餐 ¥8.00。超额按次 ¥0.00150。
请求频率
| 项目 | 额度 |
|---|---|
| 登录用户 | 每月 500 次 |
| 黄金会员 | 每天 10,000 次,每秒 5 次 |
| 铂金会员 | 每天 36,000 次,每秒 20 次 |
| 钻石会员 | 每天 80,000 次,每秒 40 次 |
预报、语音、台风、雷达、闪电、空气共用。与已购套餐分别计算。
请求参数
参数与线上接口一致。
| 参数名 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| longitude | number | 否 | 118.946778 | 东经,十进制度,范围 -180~180。不填则使用默认位置 |
| latitude | number | 否 | 25.850346 | 北纬,十进制度,范围 -90~90。不填则使用默认位置 |
| lang | string | 否 | zh_CN | 语言代码。不填为 zh_CN |
| dailystart | number | 否 | 0 | 从第几天开始,0 是今天,最大 6。不填为 0 |
| hourlysteps | number | 否 | 24 | 逐小时条数,1~24。不填为 24 |
| dailysteps | number | 否 | 7 | 逐日条数,1~7。不填为 7 |
| alert | string | 否 | true | 是否带预警。true 或 false,不填为 true |
| key | string | 否 | <API_KEY> | 密钥,或 ybdo_pub_ 公开值。与请求头二选一,同时携带时必须相同 |
| bind | string | 否 | 开源示例 | key 为公开值时必填,须与控制台绑定说明中的一条一致 |
参数规则
- 经纬度采用十进制度。
- 未传入经纬度时,使用默认位置:经度 118.946778,纬度 25.850346。
- 建议同时传入
longitude和latitude。 - 经度超出 -180~180,或纬度超出 -90~90,返回 400,
error为bad_coordinates。 - 查询位置使用经纬度。返回里的省、市、县是结果中的行政区,不能用城市名代替坐标。
- 语言、日起点、小时数、天数和预警不填时,按默认值:zh_CN、0、24、7、true。
- 请求头
Authorization: Bearer <API_KEY>,或查询参数key。公开调用时key填ybdo_pub_,并附带bind。
请求示例
GEThttps://api.yibudo.com/v1/weather?longitude=118.946778&latitude=25.850346&lang=zh_CN&dailystart=0&hourlysteps=24&dailysteps=7&alert=true&key=<API_KEY>
响应字段
完整字段见下表,对象和数组可以展开。分钟降水数组是雷达降水强度,不是毫米降水量。7 日预报包含每日降水、空气质量和生活指数。
| 字段 | 类型 | 说明 |
|---|---|---|
request_id | string | 请求标识。每次请求单独生成的十六进制串,互不重复,用于问题排查 |
notice | string | 数据使用声明 |
contact | string | 服务投诉及问题反馈邮箱 |
name | string | 接口名称,固定为「天气预报」 |
source | string | 气象数据来源,当前为彩云天气 |
headline | string | 天气趋势摘要 |
issued_at | number | 数据生成时间,Unix 时间戳,单位秒 |
| object | 查询位置及所属时区 | |
lng | number | 东经 |
lat | number | 北纬 |
zone | string | 时区 |
| object | 实时天气 | |
temp_c | number | 气温,摄氏度 |
feels_c | number | 体感温度,摄氏度 |
moisture | number | 湿度,0 到 1 |
cloud | number | 云量,0 到 1 |
code | string | 天气现象代码 |
text | string | 天气现象 |
sight_km | number | 能见度,公里 |
shortwave | number | 短波辐射 |
gust_kph | number | 阵风,公里每小时 |
dew_c | number | 露点,摄氏度 |
sea_pa | number | 海平面气压,帕 |
ground_pa | number | 地面气压,帕 |
| object | 风 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 附近降水 | |
source | string | 降水数据来源 |
rate | number | 本地降水强度 |
nearest_km | number | 最近降水距离,公里 |
nearest_rate | number | 最近降水强度 |
| object | 空气 | |
fine | number | 细颗粒物 |
coarse | number | 粗颗粒物 |
ozone | number | 臭氧 |
sulfur | number | 二氧化硫 |
nitrogen | number | 二氧化氮 |
monoxide | number | 一氧化碳 |
index_cn | number | 空气质量指数,中国 |
index_us | number | 空气质量指数,美国 |
grade_cn | string | 空气质量等级,中国 |
grade_us | string | 空气质量等级,美国 |
| object | 生活指数 | |
| object | 紫外线 | |
rank | number | 等级 |
note | string | 说明 |
| object | 舒适度 | |
rank | number | 等级 |
note | string | 说明 |
| object | 分钟级降水预报 | |
origin | string | 降水数据来源 |
note | string | 两小时降水说明 |
next_hour | array | 未来 60 分钟逐分钟雷达降水强度。按时间先后排列,0 表示该分钟无降水。不是毫米降水量 |
next_two_hours | array | 未来 120 分钟逐分钟雷达降水强度。按时间先后排列,不是毫米降水量 |
hour_totals | array | 逐小时累计降水强度,与分钟数组同一套数值 |
chance | array | 逐分钟降水概率,0 到 1 |
| object | 未来 24 小时逐小时预报 | |
note | string | 24 小时说明 |
| array | 逐小时,最多 24 条 | |
at | string | 时间 |
temp_c | number | 气温,摄氏度 |
feels_c | number | 体感温度,摄氏度 |
code | string | 天气现象代码 |
text | string | 天气现象 |
rain_mm | number | 降水量,毫米 |
rain_chance | number | 降水概率 |
moisture | number | 湿度,0 到 1 |
cloud | number | 云量,0 到 1 |
breeze_kph | number | 风速,公里每小时 |
breeze_deg | number | 风向角度 |
gust_kph | number | 阵风,公里每小时 |
dew_c | number | 露点,摄氏度 |
sea_pa | number | 海平面气压,帕 |
ground_pa | number | 地面气压,帕 |
sight_km | number | 能见度,公里 |
shortwave | number | 短波辐射 |
index_cn | number | 空气质量指数,中国 |
index_us | number | 空气质量指数,美国 |
fine | number | 细颗粒物 |
uv_rank | number | 紫外线等级 |
uv_note | string | 紫外线说明 |
| array | 未来 7 日预报。含每日天气、气温、降水、空气质量和生活指数 | |
on | string | 日期 |
rise | string | 日出 |
set | string | 日落 |
code | string | 全天天气现象代码 |
text | string | 全天天气现象 |
day_code | string | 白天天气现象代码 |
day_text | string | 白天天气现象 |
night_code | string | 夜间天气现象代码 |
night_text | string | 夜间天气现象 |
| object | 全天气温,摄氏度 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 白天气温,摄氏度 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 夜间气温,摄氏度 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 全天体感,摄氏度 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 白天体感,摄氏度 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 夜间体感,摄氏度 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 湿度,0 到 1 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 云量,0 到 1 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 地面气压,帕 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 能见度,公里 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 短波辐射 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 阵风,公里每小时 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 露点,摄氏度 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 海平面气压,帕 | |
high | number | 最高 |
low | number | 最低 |
mean | number | 平均 |
| object | 全天降水量,毫米,含降水概率 | |
high | number | 最高降水量,毫米 |
low | number | 最低降水量,毫米 |
mean | number | 平均降水量,毫米 |
chance | number | 降水概率,0 到 1 |
| object | 白天降水量,毫米,含降水概率 | |
high | number | 最高降水量,毫米 |
low | number | 最低降水量,毫米 |
mean | number | 平均降水量,毫米 |
chance | number | 降水概率,0 到 1 |
| object | 夜间降水量,毫米,含降水概率 | |
high | number | 最高降水量,毫米 |
low | number | 最低降水量,毫米 |
mean | number | 平均降水量,毫米 |
chance | number | 降水概率,0 到 1 |
| object | 全天的风 | |
| object | 最大 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 最小 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 平均 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 白天的风 | |
| object | 最大 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 最小 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 平均 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 夜间的风 | |
| object | 最大 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 最小 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 平均 | |
kph | number | 风速,公里每小时 |
deg | number | 风向角度 |
| object | 当天空气 | |
high_cn | number | 空气质量指数最高,中国 |
mean_cn | number | 空气质量指数平均,中国 |
low_cn | number | 空气质量指数最低,中国 |
fine_high | number | 细颗粒物最高 |
fine_mean | number | 细颗粒物平均 |
fine_low | number | 细颗粒物最低 |
| object | 生活指数 | |
| object | 紫外线 | |
rank | number | 等级 |
note | string | 说明 |
| object | 洗车 | |
rank | number | 等级 |
note | string | 说明 |
| object | 穿衣 | |
rank | number | 等级 |
note | string | 说明 |
| object | 舒适度 | |
rank | number | 等级 |
note | string | 说明 |
| object | 感冒 | |
rank | number | 等级 |
note | string | 说明 |
| array | 当前有效的气象预警。无预警时为空数组 | |
heading | string | 预警标题 |
detail | string | 预警正文 |
state | string | 预警状态 |
signal | string | 预警信号代码 |
响应示例
一次成功调用返回 JSON,同时包含实时天气、分钟降水、逐小时预报、未来 7 日预报和气象预警。request_id 为当次生成的十六进制标识。
{
"request_id": "104a8c2e01a1c84a4cf81",
"notice": "结果仅供参考,不作为专业判断依据。请自行核实后再使用。",
"contact": "complaint@yibudo.com",
"name": "天气预报",
"headline": "未来两小时不会下雨,放心出门吧",
"issued_at": 1794361675,
"place": {
"lng": 118.946778,
"lat": 25.850346,
"zone": "Asia/Shanghai"
},
"now": {
"temp_c": 18.34,
"feels_c": 18.4,
"moisture": 0.73,
"cloud": 0.91,
"code": "CLOUDY",
"text": "阴",
"sight_km": 16.2,
"shortwave": 42.1,
"gust_kph": 9.4,
"dew_c": 13.2,
"sea_pa": 101820,
"ground_pa": 100640,
"breeze": { "kph": 5.65, "deg": 37.23 },
"rain": { "source": "radar", "rate": 0, "nearest_km": 28.4, "nearest_rate": 0.2 },
"air": {
"fine": 10,
"coarse": 18,
"ozone": 41,
"sulfur": 4,
"nitrogen": 12,
"monoxide": 0.4,
"index_cn": 30,
"index_us": 42,
"grade_cn": "优",
"grade_us": "Good"
},
"living": { "uv": { "rank": 2, "note": "弱" }, "ease": { "rank": 3, "note": "舒适" } }
},
"soon": {
"origin": "radar",
"note": "未来两小时不会下雨,放心出门吧",
"next_hour": [0, 0, 0, 0],
"next_two_hours": [0, 0, 0, 0],
"hour_totals": [0, 0],
"chance": [0, 0, 0.05, 0.05]
},
"hours": {
"note": "未来24小时阴",
"rows": [
{
"at": "2026-11-11T09:00+08:00",
"temp_c": 18.34,
"feels_c": 18.4,
"code": "CLOUDY",
"text": "阴",
"rain_mm": 0,
"rain_chance": 0,
"moisture": 0.73,
"cloud": 0.91,
"breeze_kph": 5.65,
"breeze_deg": 37.23,
"gust_kph": 9.4,
"dew_c": 13.2,
"sea_pa": 101820,
"ground_pa": 100640,
"sight_km": 16.2,
"shortwave": 42.1,
"index_cn": 30,
"index_us": 42,
"fine": 10,
"uv_rank": 2,
"uv_note": "弱"
},
{
"at": "2026-11-11T10:00+08:00",
"temp_c": 18.8,
"feels_c": 18.9,
"code": "CLOUDY",
"text": "阴",
"rain_mm": 0,
"rain_chance": 0.05,
"moisture": 0.71,
"cloud": 0.88,
"breeze_kph": 6.1,
"breeze_deg": 40,
"gust_kph": 10.2,
"dew_c": 13.1,
"sea_pa": 101790,
"ground_pa": 100610,
"sight_km": 16.4,
"shortwave": 86.5,
"index_cn": 31,
"index_us": 43,
"fine": 11,
"uv_rank": 3,
"uv_note": "弱"
}
]
},
"days": [
{
"on": "2026-11-11T00:00+08:00",
"rise": "06:19",
"set": "17:17",
"code": "CLOUDY",
"text": "阴",
"day_text": "阴",
"night_text": "多云",
"temp": { "high": 21.14, "low": 13.89 },
"rain": { "mm": 0, "chance": 0.1 },
"air": { "high_cn": 42, "mean_cn": 30, "low_cn": 18, "fine_high": 16, "fine_mean": 10, "fine_low": 6 },
"living": { "uv": { "rank": 3, "note": "弱" }, "wash": { "rank": 2, "note": "较适宜" }, "clothes": { "rank": 4, "note": "舒适" }, "ease": { "rank": 3, "note": "舒适" }, "chill": { "rank": 2, "note": "低" } }
},
{
"on": "2026-11-12T00:00+08:00",
"rise": "06:20",
"set": "17:16",
"code": "PARTLY_CLOUDY_DAY",
"text": "多云",
"day_text": "多云",
"night_text": "阴",
"temp": { "high": 22.4, "low": 14.2 },
"rain": { "mm": 0.2, "chance": 0.2 },
"air": { "high_cn": 48, "mean_cn": 34, "low_cn": 20, "fine_high": 18, "fine_mean": 12, "fine_low": 7 },
"living": { "uv": { "rank": 4, "note": "中等" }, "wash": { "rank": 2, "note": "较适宜" }, "clothes": { "rank": 4, "note": "舒适" }, "ease": { "rank": 3, "note": "舒适" }, "chill": { "rank": 2, "note": "低" } }
}
],
"warnings": []
}错误码
| 状态码 | 说明 |
|---|---|
| 400 | 经纬度超出范围。error 为 bad_coordinates。 |
| 400 | 语言、日起点、小时数、天数或预警不在可填范围内。error 为 bad_query。 |
| 401 | 未提供密钥,密钥无效或已吊销,或请求头与 key 不一致。error 为 unauthorized。 |
| 403 | 未开通、不在白名单,或余额与额度不足。error 为 forbidden。 |
| 429 | 超过当前密钥的每秒请求次数。error 为 slow_down。 |
| 429 | 超过接口频率策略。error 为 rate_limited。 |
| 502 | 服务没有返回可用结果。error 为 upstream。 |
| 503 | 天气服务未配置。error 为 weather_unconfigured。 |
代码示例
curl -G "https://api.yibudo.com/v1/weather" \
-H "Authorization: Bearer <token>" \
--data-urlencode "longitude=118.946778&latitude=25.850346&lang=zh_CN&dailystart=0&hourlysteps=24&dailysteps=7&alert=true"const url = new URL("https://api.yibudo.com/v1/weather");
url.search = "longitude=118.946778&latitude=25.850346&lang=zh_CN&dailystart=0&hourlysteps=24&dailysteps=7&alert=true";
const res = await fetch(url, {
headers: { Authorization: "Bearer <token>" }
});
const data = await res.json();import requests
res = requests.get(
"https://api.yibudo.com/v1/weather",
params={"longitude": "118.946778", "latitude": "25.850346", "lang": "zh_CN", "dailystart": "0", "hourlysteps": "24", "dailysteps": "7", "alert": "true"},
headers={"Authorization": "Bearer <token>"},
)
print(res.json())SDK 下载
安装包按下面的说明获取。没有包时,先用代码示例里的 HTTP 调用。
- Pythonpip 包未发布
- JavaScriptnpm 包未发布
- JavaMaven 包未发布
- Go模块未发布
在线调试
开通后点运行,返回的是实时天气。还没开通时,运行不会去查。
登录后选择已有密钥才能运行。 去登录
选择密钥并运行后,返回内容显示在这里。常见问题
密钥怎么传?
请求头 Authorization: Bearer,或查询参数 key。只传一个即可,两个都传时必须相同。没有后端又不想暴露密钥时,在控制台生成公开值,key 传 ybdo_pub_ 开头的那一串,并带上 bind。
不填经纬度会怎样?
用服务里保存的默认位置。经度超出 -180 到 180,或纬度超出 -90 到 90,返回 400。
会员和按次怎么一起算?
登录用户每月 500 次,可以开通,开通后直接调用。黄金、铂金、钻石每天另有 1 万、3.6 万、8 万次,预报、语音、台风、雷达、闪电、空气共用,当天作废。用完之后按 0.0015 元一次。一次买断走套餐,单价更低。
扣费按什么顺序?
按会员赠送、指定 API 套餐、点数、余额。只在已允许的来源里扣,用第一个够付的,不会改用未授权的来源。
这个页面点运行会查天气吗?
开通之后会。点运行查询的是实时天气。还没开通时,运行只说明不能调用。
