全球天气查询

正常 热门NEW

全球天气查询,支持实时天气、批量查询与 7 天预报,响应快速稳定。

协议:HTTP 格式:JSON 版本:v1.0.0日调用量:1454次
¥ 0.002 / 次
按次计费
购买次数包更优惠,低至 0.0016 元/次

健康检查

服务存活探测

调用方式:在接口地址后拼接 ?key=您的API密钥 即可直接调用;也可改用 Authorization: Bearer 或 X-App-Key 请求头传递,避免密钥出现在访问日志中。
GET http://www.shujuyu.cn/v1/api/weather/ping JSON

请求参数

参数名类型必填说明
key string 是 您的API密钥,可在个人中心获取

返回参数说明

参数名类型说明
code integer 状态码,200 表示成功
msg string 返回消息
data object 业务数据
data.version string 数据版本
data.time string 数据时间

请求示例

返回示例

{"msg":"success","code":200,"data":{"time":"2026-10-22 22:45:20","version":"1.0"}}

城市列表

搜索支持的城市

调用方式:在接口地址后拼接 ?key=您的API密钥 即可直接调用;也可改用 Authorization: Bearer 或 X-App-Key 请求头传递,避免密钥出现在访问日志中。
GET http://www.shujuyu.cn/v1/api/weather/cities JSON

请求参数

参数名类型必填说明
key string 是 您的API密钥,可在个人中心获取
q string 否 搜索关键词
limit integer 否 返回条数,默认 20,最大 20;大于 20 自动钳制为 20;非数字或小于 1 返回 400(参数无效)

返回参数说明

参数名类型说明
code integer 状态码,200 表示成功
msg string 返回消息
data object 业务数据
data.total integer 总条数
data.returned integer 本次实际返回条数
data.limit integer 本次生效的返回条数上限
data.list array 数据列表
data.list[] object 列表中的单条记录
data.list[].name string 名称
data.list[].lat number 纬度
data.list[].lng number 经度
data.list[].country string 国家/地区
data.list[].timezone string 时区
data.list[].population integer 人口数量
data.list[].hot integer 是否热门城市

请求示例

返回示例

{"msg":"success","code":200,"data":{"list":[{"hot":1,"lat":28.6139,"lng":77.209,"name":"新德里","country":"IN","timezone":"Asia/Kolkata","population":32900000},{"hot":1,"lat":29.563,"lng":106.5516,"name":"重庆","country":"CN","timezone":"Asia/Shanghai","population":32054159},{"hot":1,"lat":31.2304,"lng":121.4737,"name":"上海","country":"CN","timezone":"Asia/Shanghai","population":24870000}],"limit":20,"total":150,"returned":20}}

单点天气查询

按城市名或坐标查询单点天气,返回实况、未来 24 小时逐时与 7 天逐日

调用方式:在接口地址后拼接 ?key=您的API密钥 即可直接调用;也可改用 Authorization: Bearer 或 X-App-Key 请求头传递,避免密钥出现在访问日志中。
GET http://www.shujuyu.cn/v1/api/weather/query JSON

请求参数

参数名类型必填说明
key string 是 您的API密钥,可在个人中心获取
city string 否 城市名(与 lat+lng 二选一,至少提供一项;全缺 → 400);城市不存在 → 404
lat number 否 纬度(与 lng 同时提供,替代 city),范围 -90 ~ 90;非数字 → 400,越界 → 400
lng number 否 经度(与 lat 同时提供,替代 city),范围 -180 ~ 180;非数字 → 400,越界 → 400
force boolean 否 为 true 时强制实时回源(跳过缓存),默认 false
brief boolean 否 精简模式:仅返回 current 与必要元数据,移除 hourly/daily(响应体约降 90%)
lang string 否 返回语言:zh / en(影响 weather_desc 等描述字段),默认 zh

返回参数说明

参数名类型说明
code integer 状态码,200 表示成功
msg string 返回消息
data object 业务数据
data.current object 当前实况数据
data.current.icon string 天气图标代码
data.current.is_day integer 是否白天
data.current.humidity integer 湿度
data.current.pressure number 气压
data.current.wind_gust number 阵风风速
data.current.wind_speed number 风速
data.current.cloud_cover integer 云量
data.current.temperature integer 温度
data.current.weather_code integer 天气现象代码
data.current.weather_desc string 天气现象描述
data.current.apparent_temp number 体感温度
data.current.precipitation integer 降水量
data.current.wind_direction integer 风向(角度)
data.current.weather_desc_en string 天气现象英文描述
data.current.weather_desc_zh string 天气现象中文描述
data.hourly array 逐小时数据(brief=true 时不返回)
data.hourly[] object 逐小时数据
data.hourly[].icon string 天气图标代码
data.hourly[].time string 时间
data.hourly[].humidity integer 湿度
data.hourly[].wind_speed number 风速
data.hourly[].temperature number 温度
data.hourly[].weather_code integer 天气现象代码
data.hourly[].weather_desc string 天气现象描述
data.hourly[].weather_desc_en string 天气现象英文描述
data.hourly[].weather_desc_zh string 天气现象中文描述
data.hourly[].precipitation_prob integer 降水概率
data.daily array 逐日数据(brief=true 时不返回)
data.daily[] object 逐日数据
data.daily[].date string 日期
data.daily[].icon string 天气图标代码
data.daily[].sunset string 日落时间
data.daily[].sunrise string 日出时间
data.daily[].temp_max number 最高温度
data.daily[].temp_min integer 最低温度
data.daily[].weather_code integer 天气现象代码
data.daily[].weather_desc string 天气现象描述
data.daily[].precipitation integer 降水量
data.daily[].wind_speed_max integer 最大风速
data.daily[].weather_desc_en string 天气现象英文描述
data.daily[].weather_desc_zh string 天气现象中文描述
data.daily[].precipitation_prob integer 降水概率
data.observed_at string 观测时间
data.timezone string 时区
data.meta object 元数据
data.meta.freshness string 数据新鲜度
data.meta.fetched_at string 数据获取时间
data.meta.data_age string 数据距今时长
data.meta.data_age_sec integer 数据距今秒数
data.meta.lang string 语言代码
data.elapsed_ms integer 服务端处理耗时(毫秒)
data.city object 城市
data.city.name string 名称
data.city.country string 国家/地区
data.city.latitude number 纬度
data.city.longitude number 经度
data.city.timezone string 时区
data.meta.brief boolean 是否为精简模式(brief=true 时为 true)
data.query object 原始查询坐标;仅按坐标(lat+lng)查询时返回,city 查询时不返回

请求示例

返回示例

{"msg":"success","code":200,"data":{"city":{"name":"北京","country":"CN","latitude":39.9042,"timezone":"Asia/Shanghai","longitude":116.4074},"meta":{"lang":"zh","data_age":"30分钟前","freshness":"stale","fetched_at":"2026-10-22 22:19:59","data_age_sec":1826},"daily":[{"date":"2026-10-22","icon":"cloud","sunset":"17:25","sunrise":"06:31","temp_max":15.6,"temp_min":4,"weather_code":3,"weather_desc":"阴","precipitation":0,"wind_speed_max":14,"weather_desc_en":"Overcast","weather_desc_zh":"阴","precipitation_prob":0},{"date":"2026-10-23","icon":"sun","sunset":"17:24","sunrise":"06:33","temp_max":15.7,"temp_min":6.6,"weather_code":1,"weather_desc":"大部晴","precipitation":0,"wind_speed_max":8.7,"weather_desc_en":"Mainly clear","weather_desc_zh":"大部晴","precipitation_prob":2},{"date":"2026-10-24","icon":"cloud","sunset":"17:22","sunrise":"06:34","temp_max":18.1,"temp_min":8.3,"weather_code":3,"weather_desc":"阴","precipitation":0,"wind_speed_max":7.6,"weather_desc_en":"Overcast","weather_desc_zh":"阴","precipitation_prob":4}],"hourly":[{"icon":"sun","time":"2026-10-22T22:00","humidity":66,"wind_speed":9.9,"temperature":10.2,"weather_code":1,"weather_desc":"大部晴","weather_desc_en":"Mainly clear","weather_desc_zh":"大部晴","precipitation_prob":0},{"icon":"sun","time":"2026-10-22T23:00","humidity":66,"wind_speed":9.4,"temperature":9.6,"weather_code":0,"weather_desc":"晴","weather_desc_en":"Clear sky","weather_desc_zh":"晴","precipitation_prob":0},{"icon":"sun","time":"2026-10-23T00:00","humidity":67,"wind_speed":8.7,"temperature":9,"weather_code":0,"weather_desc":"晴","weather_desc_en":"Clear sky","weather_desc_zh":"晴","precipitation_prob":1}],"current":{"icon":"sun","is_day":0,"humidity":66,"pressure":1023.3,"wind_gust":20.5,"wind_speed":9.9,"cloud_cover":31,"temperature":10,"weather_code":1,"weather_desc":"大部晴","apparent_temp":7.1,"precipitation":0,"wind_direction":182,"weather_desc_en":"Mainly clear","weather_desc_zh":"大部晴"},"timezone":"Asia/Shanghai","elapsed_ms":6,"observed_at":"2026-10-22 22:15:00"}}

批量查询

批量查询最多 10 个坐标

调用方式:在接口地址后拼接 ?key=您的API密钥 即可直接调用;也可改用 Authorization: Bearer 或 X-App-Key 请求头传递,避免密钥出现在访问日志中。
POST http://www.shujuyu.cn/v1/api/weather/batch JSON

请求参数

参数名类型必填说明
key string 是 您的API密钥,可在个人中心获取
locations array 是 坐标数组,最多 10 个;超过 10 个 → 400;非法项(缺 lat/lng、非数字、超出范围)跳过并计入 invalid / invalid_count;全部非法 → 400(无有效坐标);部分合法时返回 200 并附 invalid 清单

返回参数说明

参数名类型说明
code integer 状态码,200 表示成功
msg string 返回消息
data object 业务数据
data.total integer 总条数
data.returned integer 本次实际返回条数
data.invalid_count integer 无效数量
data.truncated boolean 保留字段,当前恒为 false(超过 10 条时直接返回 4002 错误,不会截断)
data.max_limit integer 允许返回的最大条数
data.elapsed_ms integer 服务端处理耗时(毫秒)
data.invalid array 无效数量
data.list object 按坐标聚合的天气数据,键为「纬度,经度」各保留两位小数
data.list.{lat},{lng} object 单个坐标点的天气数据,键为「纬度,经度」各保留两位小数(如 `39.90,116.40`)
data.list.{lat},{lng}.current object 当前实况数据
data.list.{lat},{lng}.current.temperature number 温度
data.list.{lat},{lng}.current.humidity integer 湿度
data.list.{lat},{lng}.current.apparent_temp number 体感温度
data.list.{lat},{lng}.current.is_day integer 是否白天
data.list.{lat},{lng}.current.precipitation integer 降水量
data.list.{lat},{lng}.current.weather_code integer 天气现象代码
data.list.{lat},{lng}.current.weather_desc string 天气现象描述
data.list.{lat},{lng}.current.weather_desc_zh string 天气现象中文描述
data.list.{lat},{lng}.current.weather_desc_en string 天气现象英文描述
data.list.{lat},{lng}.current.icon string 天气图标代码
data.list.{lat},{lng}.current.cloud_cover integer 云量
data.list.{lat},{lng}.current.pressure number 气压
data.list.{lat},{lng}.current.wind_speed number 风速
data.list.{lat},{lng}.current.wind_direction integer 风向(角度)
data.list.{lat},{lng}.current.wind_gust number 阵风风速
data.list.{lat},{lng}.hourly array 逐小时数据
data.list.{lat},{lng}.hourly[] object 逐小时数据
data.list.{lat},{lng}.hourly[].time string 时间
data.list.{lat},{lng}.hourly[].temperature number 温度
data.list.{lat},{lng}.hourly[].humidity integer 湿度
data.list.{lat},{lng}.hourly[].precipitation_prob integer 降水概率
data.list.{lat},{lng}.hourly[].weather_code integer 天气现象代码
data.list.{lat},{lng}.hourly[].weather_desc string 天气现象描述
data.list.{lat},{lng}.hourly[].weather_desc_zh string 天气现象中文描述
data.list.{lat},{lng}.hourly[].weather_desc_en string 天气现象英文描述
data.list.{lat},{lng}.hourly[].icon string 天气图标代码
data.list.{lat},{lng}.hourly[].wind_speed number 风速
data.list.{lat},{lng}.daily array 逐日数据
data.list.{lat},{lng}.daily[] object 逐日数据
data.list.{lat},{lng}.daily[].date string 日期
data.list.{lat},{lng}.daily[].weather_code integer 天气现象代码
data.list.{lat},{lng}.daily[].weather_desc string 天气现象描述
data.list.{lat},{lng}.daily[].weather_desc_zh string 天气现象中文描述
data.list.{lat},{lng}.daily[].weather_desc_en string 天气现象英文描述
data.list.{lat},{lng}.daily[].icon string 天气图标代码
data.list.{lat},{lng}.daily[].temp_max number 最高温度
data.list.{lat},{lng}.daily[].temp_min integer 最低温度
data.list.{lat},{lng}.daily[].sunrise string 日出时间
data.list.{lat},{lng}.daily[].sunset string 日落时间
data.list.{lat},{lng}.daily[].precipitation integer 降水量
data.list.{lat},{lng}.daily[].precipitation_prob integer 降水概率
data.list.{lat},{lng}.daily[].wind_speed_max integer 最大风速
data.list.{lat},{lng}.observed_at string 观测时间
data.list.{lat},{lng}.timezone string 时区
data.list.{lat},{lng}.meta object 元数据
data.list.{lat},{lng}.meta.freshness string 数据新鲜度
data.list.{lat},{lng}.meta.fetched_at string 数据获取时间
data.list.{lat},{lng}.meta.data_age string 数据距今时长
data.list.{lat},{lng}.meta.data_age_sec integer 数据距今秒数
data.list.{lat},{lng}.meta.lang string 语言代码

请求示例

返回示例

{"msg":"success","code":200,"data":{"list":{"39.90,116.40":{"meta":{"lang":"zh","data_age":"29秒前","freshness":"realtime","fetched_at":"2026-10-22 22:45:29","data_age_sec":29},"daily":[{"date":"2026-10-22","icon":"cloud","sunset":"17:25","sunrise":"06:31","temp_max":15.6,"temp_min":4,"weather_code":3,"weather_desc":"阴","precipitation":0,"wind_speed_max":14,"weather_desc_en":"Overcast","weather_desc_zh":"阴","precipitation_prob":0},{"date":"2026-10-23","icon":"sun","sunset":"17:24","sunrise":"06:33","temp_max":15.7,"temp_min":6.6,"weather_code":1,"weather_desc":"大部晴","precipitation":0,"wind_speed_max":8.7,"weather_desc_en":"Mainly clear","weather_desc_zh":"大部晴","precipitation_prob":2},{"date":"2026-10-24","icon":"cloud","sunset":"17:22","sunrise":"06:34","temp_max":18.1,"temp_min":8.3,"weather_code":3,"weather_desc":"阴","precipitation":0,"wind_speed_max":7.6,"weather_desc_en":"Overcast","weather_desc_zh":"阴","precipitation_prob":4}],"hourly":[{"icon":"sun","time":"2026-10-22T22:00","humidity":66,"wind_speed":9.9,"temperature":10.2,"weather_code":1,"weather_desc":"大部晴","weather_desc_en":"Mainly clear","weather_desc_zh":"大部晴","precipitation_prob":0},{"icon":"sun","time":"2026-10-22T23:00","humidity":66,"wind_speed":9.4,"temperature":9.6,"weather_code":0,"weather_desc":"晴","weather_desc_en":"Clear sky","weather_desc_zh":"晴","precipitation_prob":0},{"icon":"sun","time":"2026-10-23T00:00","humidity":67,"wind_speed":8.7,"temperature":9,"weather_code":0,"weather_desc":"晴","weather_desc_en":"Clear sky","weather_desc_zh":"晴","precipitation_prob":1}],"current":{"icon":"sun","is_day":0,"humidity":66,"pressure":1023.3,"wind_gust":20.5,"wind_speed":9.6,"cloud_cover":11,"temperature":9.8,"weather_code":0,"weather_desc":"晴","apparent_temp":6.9,"precipitation":0,"wind_direction":183,"weather_desc_en":"Clear sky","weather_desc_zh":"晴"},"timezone":"Asia/Shanghai","observed_at":"2026-10-22T22:45"}},"total":1,"invalid":[],"returned":1,"max_limit":10,"truncated":false,"elapsed_ms":754,"invalid_count":0}}

7 天预报

返回未来 7 天逐日预报

调用方式:在接口地址后拼接 ?key=您的API密钥 即可直接调用;也可改用 Authorization: Bearer 或 X-App-Key 请求头传递,避免密钥出现在访问日志中。
GET http://www.shujuyu.cn/v1/api/weather/forecast JSON

请求参数

参数名类型必填说明
key string 是 您的API密钥,可在个人中心获取
city string 否 城市名(与 lat+lng 二选一,至少提供一项;全缺 → 400);城市不存在 → 404
lat number 否 纬度(与 lng 同时提供,替代 city),范围 -90 ~ 90;非数字 → 400,越界 → 400
lng number 否 经度(与 lat 同时提供,替代 city),范围 -180 ~ 180;非数字 → 400,越界 → 400
lang string 否 返回语言:zh / en(影响天气描述字段),默认 zh

返回参数说明

参数名类型说明
code integer 状态码,200 表示成功
msg string 返回消息
data object 业务数据
data.city string 城市
data.lat number 纬度
data.lng number 经度
data.current_brief object 当前实况摘要
data.current_brief.temperature number 温度
data.current_brief.weather_desc string 天气现象描述
data.current_brief.wind_speed number 风速
data.current_brief.humidity integer 湿度
data.daily array 逐日数据
data.daily[] object 逐日数据
data.daily[].date string 日期
data.daily[].weather_code integer 天气现象代码
data.daily[].weather_desc string 天气现象描述
data.daily[].weather_desc_zh string 天气现象中文描述
data.daily[].weather_desc_en string 天气现象英文描述
data.daily[].icon string 天气图标代码
data.daily[].temp_max number 最高温度
data.daily[].temp_min integer 最低温度
data.daily[].sunrise string 日出时间
data.daily[].sunset string 日落时间
data.daily[].precipitation integer 降水量
data.daily[].precipitation_prob integer 降水概率
data.daily[].wind_speed_max integer 最大风速
data.meta object 元数据
data.meta.freshness string 数据新鲜度
data.meta.fetched_at string 数据获取时间
data.meta.data_age string 数据距今时长
data.meta.data_age_sec integer 数据距今秒数
data.meta.lang string 语言代码

请求示例

返回示例

{"msg":"success","code":200,"data":{"lat":39.9042,"lng":116.4074,"city":"北京","meta":{"lang":"zh","data_age":"33秒前","freshness":"realtime","fetched_at":"2026-10-22 22:45:33","data_age_sec":33},"daily":[{"date":"2026-10-22","icon":"cloud","sunset":"17:25","sunrise":"06:31","temp_max":15.6,"temp_min":4,"weather_code":3,"weather_desc":"阴","precipitation":0,"wind_speed_max":14,"weather_desc_en":"Overcast","weather_desc_zh":"阴","precipitation_prob":0},{"date":"2026-10-23","icon":"sun","sunset":"17:24","sunrise":"06:33","temp_max":15.7,"temp_min":6.6,"weather_code":1,"weather_desc":"大部晴","precipitation":0,"wind_speed_max":8.7,"weather_desc_en":"Mainly clear","weather_desc_zh":"大部晴","precipitation_prob":2},{"date":"2026-10-24","icon":"cloud","sunset":"17:22","sunrise":"06:34","temp_max":18.1,"temp_min":8.3,"weather_code":3,"weather_desc":"阴","precipitation":0,"wind_speed_max":7.6,"weather_desc_en":"Overcast","weather_desc_zh":"阴","precipitation_prob":4}],"current_brief":{"humidity":66,"wind_speed":9.6,"temperature":9.8,"weather_desc":"晴"}}}

产品说明

产品概述

全球天气查询,支持实时天气、批量查询与 7 天预报,响应快速稳定。

使用场景

数据查询:快速集成 全球天气查询 到您的应用中
业务系统:将 全球天气查询 数据嵌入业务流程
开发工具:通过 API 接口获取 数据查询 数据
数据分析:基于 全球天气查询 数据进行分析和决策

费用计算

按次计费单价
¥0.002 / 次
每次调用接口从账户余额中扣除相应费用,VIP 用户可享折扣

扣费优先级

免费额度
次数包
余额扣费

计费方式详解

1 免费额度
· 接口每日免费额度已关闭
· VIP 用户月度免费额度:
· 个人版:每月 5000 次,本接口月上限 5000 次
· 专业版:每月 30000 次,本接口月上限 30000 次
· 企业版:每月 200000 次,本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数,会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次 的接口;接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置,未使用部分不累计至下月。
2 次数包
预付费购买固定调用次数,最高可省 20%(相对按次付费),用完为止。
次数包为独立计费,不与 VIP 折扣叠加。
请在有效期内使用,过期后未使用的次数不可再用。
3 余额扣费
按次从账户余额扣除费用;所有用户可享量折扣,VIP 用户额外享 VIP 折扣。
扣费公式:实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例),并受总折扣上限和最低利润率保护约束
VIP 折扣: 个人版9折 专业版8折 企业版7折
量折扣: 月付费调用 ≥1000 次享 2%、 月付费调用 ≥10000 次享 5%、 月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计,达到更高档位时按更高档位计算
总折扣上限:VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护:折后价不得低于成本价 × (1 + 15%);若接口售价本身低于该保护价,则取消折扣并按售价计费
余额不足时调用将失败,请及时充值。

次数包方案

方案名称调用次数价格折算单价比按次付费节省有效期
100次调用包 100 次 ¥0.2 ¥0.0020/次 - 365 天
500次调用包 500 次 ¥0.95 ¥0.0019/次 省5% 365 天
1000次调用包 1000 次 ¥1.8 ¥0.0018/次 省10% 365 天
5000次调用包 5000 次 ¥8.5 ¥0.0017/次 省15% 365 天
10000次调用包 10000 次 ¥16 ¥0.0016/次 省20% 365 天

VIP 权益对比

等级每月免费次数本接口月免费上限折扣VIP 折后单价
免费版 按接口配置 — - ¥0.002/次
个人版 5000 次 5000 次 10% ¥0.0018/次
专业版 30000 次 30000 次 20% ¥0.0016/次
* VIP 月度免费额度每月重置。每月免费次数为账号级 VIP 月额度,本接口月免费上限为其中对本接口的限制(接口可单独设置上限或关闭)。VIP 折扣仅适用于余额扣费方式,VIP 折后单价不含量折扣。 本接口已关闭接口级月度免费额度(不影响 VIP 月度免费额度)。接口每日免费额度已关闭。

费用计算示例

* 以下示例未包含量折扣,量折扣按账号当月全部接口的付费调用量另行计算。
示例1:普通用户按次付费
调用 1000 次,费用 = 0.002 × 1000 = ¥2.00
示例2:个人版用户按次付费(仅 VIP 折扣,已考虑最低利润率保护)
调用 1000 次,折扣约 10%,费用 = 0.002 × (1 - 10%) × 1000 ≈ ¥1.80
示例3:购买「500次调用包」次数包
支付 ¥0.95,获得 500 次调用,折算单价 ¥0.0019/次
同等次数按次付费需 ¥1.00,次数包可节省 ¥0.05

错误码说明

错误码说明解决方案
200 请求成功 -
400000 请求参数错误 检查参数名、格式与取值
401000 认证失败 检查 Authorization: Bearer 密钥是否正确、是否过期
402000 账户余额不足 充值后重试
403000 无访问权限 确认密钥权限、接口范围与 IP 白名单是否满足要求
404001 接口或端点不存在 检查 API 与端点的请求路径
409000 请求冲突 请稍后重试
422000 参数校验失败 检查参数格式与取值
429000 请求频率或额度超限 降低调用频率,或升级套餐提升额度
500000 服务器内部错误 携带响应中的 request_id 联系技术支持
502000 服务暂时不可用 稍后重试
503000 服务暂时不可用 稍后重试
504000 请求超时 稍后重试

更新日志

暂无更新日志