Difference between revisions of "实况天气接口/v2.5"
Mengqingye (talk | contribs) (→返回结构和说明) (Tag: Visual edit) |
(→常量、变量详细说明) |
||
(16 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
+ | {{导览}} | ||
+ | |||
{{彩云天气 API 版本状态}} | {{彩云天气 API 版本状态}} | ||
− | == | + | == 授权与认证 == |
− | |||
请先至彩云开放平台[https://dashboard.caiyunapp.com/user/sign_up/ 注册],注册后可以获得 token 。 | 请先至彩云开放平台[https://dashboard.caiyunapp.com/user/sign_up/ 注册],注册后可以获得 token 。 | ||
− | 把您的 token 拼到 API 请求的 URL 中,如 | + | 把您的 token 拼到 API 请求的 URL 中,如 |
− | <code | + | <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/realtime.json</code> |
− | |||
− | </code> | ||
其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人! | 其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人! | ||
− | == | + | == API 请求 == |
+ | |||
+ | === 示例 === | ||
+ | |||
+ | 这里是测试 token ,即 <code>TAkhjf8d1nlSlspN</code> | ||
+ | |||
+ | * <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/realtime.json</code> | ||
+ | * <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/realtime.jsonp?callback=MYCALLBACK</code> | ||
+ | |||
+ | === 请求参数 === | ||
+ | |||
+ | * 经纬度:必须,无缺省值,经度在前,纬度在后,中间用半角逗号隔开,如 <code>121.6544,25.1552</code> | ||
+ | * 返回格式:必须,无缺省值,可选项目包括json 或者 jsonp,jsonp 需提供回调函数名 | ||
+ | * 语言选项 lang: 可选,缺省值是 <code>zh_CN</code>,可选项目包括简体中文(zh_CN,默认)、繁体中文(zh_TW)、美式英语(en_US)、英式英语(en_GB)、日语(ja) | ||
+ | ** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/-74.0060,40.7128/realtime.json?lang=en_US</code> | ||
+ | ** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/139.7690,35.6804/realtime.json?lang=ja</code> | ||
+ | * 单位制选项 unit: 可选,缺省值是 <code>metric</code>, 可选项目包括公制<code>metric</code>,英制<code>imperial</code>,和科学单位制 <code>SI</code> | ||
+ | ** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/-74.0060,40.7128/realtime.json?lang=en_US&unit=imperial</code> | ||
− | ==== | + | == API 返回值 == |
− | |||
− | ==== | + | === 返回结构说明 === |
− | |||
− | |||
<syntaxhighlight lang="yaml"> | <syntaxhighlight lang="yaml"> | ||
Line 34: | Line 47: | ||
result: | result: | ||
realtime: | realtime: | ||
− | status: ok | + | status: ok # 实况模块返回状态 |
− | temperature: 28.0 | + | temperature: 28.0 # 温度 |
− | apparent_temperature: 27.0 | + | apparent_temperature: 27.0 # 体感温度 |
− | + | pressure: 100991.3 # 气压 | |
− | humidity: 0.92 | + | humidity: 0.92 # 相对湿度 |
wind: | wind: | ||
− | direction: 25.33 | + | direction: 25.33 # 风向,单位是度。正北方向为0度,顺时针增加到360度。 |
− | speed: 83.3 | + | speed: 83.3 # 风速,米制下是公里每小时 |
precipitation: | precipitation: | ||
nearest: | nearest: | ||
status: ok | status: ok | ||
− | distance: 0.77 | + | distance: 0.77 # 最近的降水带距离 |
− | intensity: 0.3125 | + | intensity: 0.3125 # 最近的降水带降水强度(单位为雷达降水强度) |
local: | local: | ||
status: ok | status: ok | ||
− | intensity: 0.2812 | + | intensity: 0.2812 # 本地降水强度(单位为雷达降水强度) |
− | datasource: radar | + | datasource: radar # 本地降水观测的数据源(radar,GFS) |
− | cloudrate: 0.51 | + | cloudrate: 0.51 # 云量 |
− | dswrf: 8.3 | + | dswrf: 8.3 # 向下短波辐射通量 |
− | visibility: 8.3 | + | visibility: 8.3 # 能见度 |
− | skycon: RAIN | + | skycon: RAIN # 主要天气现象 |
life_index: | life_index: | ||
− | comfort: | + | comfort: # 舒适度指数及其自然语言描述 |
index: 7 | index: 7 | ||
desc: 冷 | desc: 冷 | ||
− | ultraviolet: | + | ultraviolet: # 紫外线指数及其自然语言描述 |
index: 0 | index: 0 | ||
desc: 无 | desc: 无 | ||
air_quality: | air_quality: | ||
− | pm25: 18 | + | pm25: 18 # pm25,质量浓度值 |
− | pm10: 46 | + | pm10: 46 # pm10,质量浓度值 |
− | o3: 47 | + | o3: 47 # 臭氧,质量浓度值 |
− | no2: 14 | + | no2: 14 # 二氧化氮,质量浓度值 |
− | so2: 1 | + | so2: 1 # 二氧化硫,质量浓度值 |
− | co: 0.3 | + | co: 0.3 # 一氧化碳,质量浓度值 |
aqi: | aqi: | ||
− | chn: 8 | + | chn: 8 # AQI(中国标准) |
− | usa: 0 | + | usa: 0 # AQI(美国标准) |
description: | description: | ||
usa: "" | usa: "" | ||
Line 78: | Line 91: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | == | + | === 返回错误 === |
− | + | === 天气变量 === | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | {{:实况天气接口/v2.5/天气变量}} | |
− | {{ | ||
− | == | + | == 变量详细说明 == |
+ | |||
+ | ===支持的单位制=== | ||
{{Template:彩云天气 API/支持的单位制}} | {{Template:彩云天气 API/支持的单位制}} | ||
+ | |||
+ | ===雷达降水强度=== | ||
+ | |||
+ | {{:雷达降水强度}} | ||
+ | |||
+ | == 常量详细说明 == | ||
+ | |||
+ | ===天气现象代码=== | ||
+ | |||
+ | {{:天气现象代码表}} | ||
+ | |||
+ | ===生活指数等级=== | ||
+ | |||
+ | {{:生活指数等级}} | ||
[[Category:API 产品]] | [[Category:API 产品]] |
Latest revision as of 05:08, 15 April 2020
本文版本:实况天气接口/v2.5,当前稳定版本版本:v2.5,历史版本:v2.2,v2.3,和 v2.4。
Contents
授权与认证
请先至彩云开放平台注册,注册后可以获得 token 。
把您的 token 拼到 API 请求的 URL 中,如
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/realtime.json
其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人!
API 请求
示例
这里是测试 token ,即 TAkhjf8d1nlSlspN
-
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/realtime.json
-
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/realtime.jsonp?callback=MYCALLBACK
请求参数
- 经纬度:必须,无缺省值,经度在前,纬度在后,中间用半角逗号隔开,如
121.6544,25.1552
- 返回格式:必须,无缺省值,可选项目包括json 或者 jsonp,jsonp 需提供回调函数名
- 语言选项 lang: 可选,缺省值是
zh_CN
,可选项目包括简体中文(zh_CN,默认)、繁体中文(zh_TW)、美式英语(en_US)、英式英语(en_GB)、日语(ja) - 单位制选项 unit: 可选,缺省值是
metric
, 可选项目包括公制metric
,英制imperial
,和科学单位制SI
API 返回值
返回结构说明
status: ok
api_version: v2.5 # 版本号
api_status: active # 版本号状态
lang: zh_CN # 语言
unit: metric # 单位制
location: [25.1552 121.6544] # 经纬度
server_time: 1443418222 # 服务器本次返回的utc时间戳
tzshift: 28800 # 时区的偏移秒数,如东八区就是 28800 秒
result:
realtime:
status: ok # 实况模块返回状态
temperature: 28.0 # 温度
apparent_temperature: 27.0 # 体感温度
pressure: 100991.3 # 气压
humidity: 0.92 # 相对湿度
wind:
direction: 25.33 # 风向,单位是度。正北方向为0度,顺时针增加到360度。
speed: 83.3 # 风速,米制下是公里每小时
precipitation:
nearest:
status: ok
distance: 0.77 # 最近的降水带距离
intensity: 0.3125 # 最近的降水带降水强度(单位为雷达降水强度)
local:
status: ok
intensity: 0.2812 # 本地降水强度(单位为雷达降水强度)
datasource: radar # 本地降水观测的数据源(radar,GFS)
cloudrate: 0.51 # 云量
dswrf: 8.3 # 向下短波辐射通量
visibility: 8.3 # 能见度
skycon: RAIN # 主要天气现象
life_index:
comfort: # 舒适度指数及其自然语言描述
index: 7
desc: 冷
ultraviolet: # 紫外线指数及其自然语言描述
index: 0
desc: 无
air_quality:
pm25: 18 # pm25,质量浓度值
pm10: 46 # pm10,质量浓度值
o3: 47 # 臭氧,质量浓度值
no2: 14 # 二氧化氮,质量浓度值
so2: 1 # 二氧化硫,质量浓度值
co: 0.3 # 一氧化碳,质量浓度值
aqi:
chn: 8 # AQI(中国标准)
usa: 0 # AQI(美国标准)
description:
usa: ""
chn: "优"
返回错误
天气变量
名称 | 健值路径(jsonpath) | 量 | 时间粒度 | 地理范围 | 注释 |
---|---|---|---|---|---|
温度 | $.result.realtime.temperature | 温度 | 实况 | 全球 | 地表2米气温 |
体感温度 | $.result.realtime.apparent_temperature | 温度 | 实况 | 全球 | |
气压 | $.result.realtime.pressure | 气压(Pa) | 实况 | 全球 | 地面气压 |
相对湿度 | $.result.realtime.humidity | 相对湿度(%) | 实况 | 全球 | 地表2米湿度 |
风向 | $.result.realtime.wind.direction | 风向 | 实况 | 全球 | 地表10米风向 |
风速 | $.result.realtime.wind.speed | 风速 | 实况 | 全球 | 地表10米风速 |
最近降水距离 | $.result.realtime.precipitation.nearest.distance | 距离 | 实况 | 全球 | 最近降水带与本地的距离 |
最近降水强度 | $.result.realtime.precipitation.nearest.intensity | 降水强度 | 实况 | 全球 | 最近降水处的降水强度 |
本地降水强度 | $.result.realtime.precipitation.local.intensity | 雷达降水强度 | 实况 | 全球 | 最近降水处的降水强度 |
云量 | $.result.realtime.cloudrate | 云量(0.0-1.0) | 实况 | 全球 | 全天总云量 |
短波辐射 | $.result.realtime.dswrf | 向下短波辐射通量(W/M2) | 实况 | 全球 | 地表向下短波辐射通量 |
能见度 | $.result.realtime.visibility | 能见度 | 实况 | 全球 | 地表水平能见度 |
天气状况 | $.result.realtime.skycon | 天气状况 | 实况 | 全球 | 参见#天气现象代码 |
舒适度指数 | $.result.realtime.life_index.comfort.index | 舒适度指数自然语言 | 实况 | 全球 | 参见#生活指数等级 |
紫外线指数 | $.result.realtime.life_index.ultraviolet.index | 紫外线指数自然语言 | 实况 | 全球 | 参见#生活指数等级 |
PM25浓度 | $.result.realtime.air_quality.pm25 | PM25浓度(μg/m3) | 实况 | 大陆、港澳台、印度、日本,美国、阿拉斯加、夏威夷、加拿大 | PM25浓度 |
PM10浓度 | $.result.realtime.air_quality.pm10 | PM10浓度(μg/m3) | 实况 | 大陆、港澳台、印度、日本,美国、阿拉斯加、夏威夷、加拿大 | PM10浓度 |
臭氧浓度 | $.result.realtime.air_quality.o3 | 臭氧浓度(μg/m3) | 实况 | 大陆、港澳台、印度、日本,美国、阿拉斯加、夏威夷、加拿大 | 臭氧浓度 |
二氧化氮浓度 | $.result.realtime.air_quality.no2 | 二氧化氮浓度(μg/m3) | 实况 | 大陆、港澳台、印度、日本,美国、阿拉斯加、夏威夷、加拿大 | 二氧化氮浓度 |
二氧化硫浓度 | $.result.realtime.air_quality.so2 | 二氧化硫浓度(μg/m3) | 实况 | 大陆、港澳台、印度、日本,美国、阿拉斯加、夏威夷、加拿大 | 二氧化硫浓度 |
一氧化碳浓度 | $.result.realtime.air_quality.co | 一氧化碳浓度(mg/m3) | 实况 | 大陆、港澳台、印度、日本,美国、阿拉斯加、夏威夷、加拿大 | 一氧化碳浓度 |
AQI | $.result.realtime.air_quality.aqi | 国标AQI | 实况 | 大陆、港澳台、印度、日本,美国、阿拉斯加、夏威夷、加拿大 | 国标AQI |
变量详细说明
支持的单位制
1.目前支持的单位制包括:科学单位体系(SI,大写)、英制(imperial)、公制(不带参数&unit默认公制,公制还包括: metric:v1和metric:v2):
单位制 要素
|
SI(科学单位体系) | imperial(英制) | metric:v1(公制v1) | metric:v2(公制v2) | default metric(默认公制) |
---|---|---|---|---|---|
实况降水量 | 米/秒(meter/sec) | 英寸/小时(in/hr) | 雷达降水强度(0~1) | 毫米/小时(mm/hr) | 雷达降水强度(0~1) |
逐分钟降水短临预报降水量 | 米/秒(meter/sec) | 英寸/小时(in/hr) | 雷达降水强度(0~1) | 毫米/小时(mm/hr) | 雷达降水强度(0~1) |
逐小时预报降水量 | 米/秒(meter/sec) | 英寸/小时(in/hr) | 雷达降水强度(0~1) | 毫米/小时(mm/hr) | 毫米/小时(mm/hr) |
逐日预报降水量 | 米/秒(meter/sec) | 英寸/小时(in/hr) | 雷达降水强度(0~1) | 毫米/小时(mm/hr) | 毫米/小时(mm/hr) |
距离 | 米(m) | 英里(mi) | 公里(km) | 公里(km) | 公里(km) |
温度 | 开尔文(K) | 华氏度(℉) | 摄氏度(℃) | 摄氏度(℃) | 摄氏度(℃) |
气压 | 帕(Pa) | 帕(Pa) | 帕(Pa) | 帕(Pa) | 帕(Pa) |
相对湿度 | 0~1 | 0~1 | 0~1 | 0~1 | 0~1 |
风向 | 从北顺时针(0~360°) | 从北顺时针(0~360°) | 从北顺时针(0~360°) | 从北顺时针(0~360°) | 从北顺时针(0~360°) |
风速 | 米/秒(m/s) | 英里/小时(mi/hr) | 公里/小时(km/hr) | 公里/小时(km/hr) | 公里/小时(km/hr) |
云量 | 0~1 | 0~1 | 0~1 | 0~1 | 0~1 |
能见度 | 米(m) | 英里(mi) | 公里(km) | 公里(km) | 公里(km) |
unit=metric:v1时,所有类型中precipitation的单位都是:雷达降水强度(0~1)
unit=metric:v2时,所有类型中precipitation的单位都是:毫米/小时(mm/hr)
2.判断降水等级:
- 带参数&unit=metric:v1,请求实况、分钟级、逐小时和逐日降水强度,单位都为雷达降水强度(0 ~ 1);
- 雷达降水强度(0 ~ 1)判断降水等级:0.03~0.25 小雨(雪), 0.25~0.35 中雨(雪), 0.35~0.48大雨(雪), >0.48 暴雨(雪);
- v2.4版本中,本地存在降水时,可以根据skycon(存在于realtime、hourly、daily字段),和skycon_08h_20h和skycon_20h_32h(存在于daily字段),中的:LIGHT_RAIN, MODERATE_RAIN, HEAVY_RAIN, STORM_RAIN(LIGHT_SNOW, MODERATE_SNOW, HEAVY_SNOW,STORM_SNOW)直接获取降水等级
- 大暴雨(雪)和特大暴雨(雪),需要根据24小时累计公制降水量(mm/24hr)来判断,研发中...
雷达降水强度
雷达降水强度是在雷达回波反照率基础上由彩云科技定义的一个度量值,它可以简单的描述降雨的相对强弱。
雷达降水强度 | 降水量 mm/h | 天气现象 |
<0.031 | <0.08 | 无雨/雪 |
0.031~0.25 | 0.08~3.44 | 小雨/雪 |
0.25~0.35 | 3.44~11.33 | 中雨/雪 |
0.35~0.48 | 11.33~51.30 | 大雨/雪 |
>=0.48 | >=51.30 | 暴雨/雪 |
- 雨雪相态判断使用 SKYCON 表示,
RAIN
表示雨,SNOW
表示雪,详见天气现象。 - API 默认返回雷达降水强度,如果需要 API 返回降水量需要在 API URL 增加参数
unit=metric:v2
,详见 API 单位制转换
常量详细说明
天气现象代码
天气现象 | 代码 | 备注 |
---|---|---|
晴(白天) | CLEAR_DAY | cloudrate < 0.2 |
晴(夜间) | CLEAR_NIGHT | cloudrate < 0.2 |
多云(白天) | PARTLY_CLOUDY_DAY | 0.8 >= cloudrate > 0.2 |
多云(夜间) | PARTLY_CLOUDY_NIGHT | 0.8 >= cloudrate > 0.2 |
阴 | CLOUDY | cloudrate > 0.8 |
轻度雾霾 | LIGHT_HAZE | PM2.5 100~150 |
中度雾霾 | MODERATE_HAZE | PM2.5 150~200 |
重度雾霾 | HEAVY_HAZE | PM2.5 > 200 |
小雨 | LIGHT_RAIN | |
中雨 | MODERATE_RAIN | |
大雨 | HEAVY_RAIN | |
暴雨 | STORM_RAIN | |
雾 | FOG | 能见度低,湿度高,风速低,温度低 |
小雪 | LIGHT_SNOW | |
中雪 | MODERATE_SNOW | |
大雪 | HEAVY_SNOW | |
暴雪 | STORM_SNOW | |
浮尘 | DUST | aqi > 150,pm10 > 150,湿度 < 30%,风速 < 6 m/s |
沙尘 | SAND | aqi > 150,pm10 > 150,湿度 < 30%,风速 > 6 m/s |
大风 | WIND |
- 主要天气现象的优先级:降雪 > 降雨 > 雾 > 沙尘 > 浮尘 > 雾霾 > 大风 > 阴 > 多云 > 晴
生活指数等级
生活指数名称 | 等级 | 等级描述 |
紫外线(实况级别) | ultraviolet0 | 无 |
ultraviolet1 | 很弱 | |
ultraviolet2 | 很弱 | |
ultraviolet3 | 弱 | |
ultraviolet4 | 弱 | |
ultraviolet5 | 中等 | |
ultraviolet6 | 中等 | |
ultraviolet7 | 强 | |
ultraviolet8 | 强 | |
ultraviolet9 | 很强 | |
ultraviolet10 | 很强 | |
ultraviolet11 | 极强 | |
紫外线(天级别) | ultraviolet1 | 最弱 |
ultraviolet2 | 弱 | |
ultraviolet3 | 中等 | |
ultraviolet4 | 强 | |
ultraviolet5 | 很强 | |
穿衣 | dressing0 | 极热 |
dressing1 | 极热 | |
dressing2 | 很热 | |
dressing3 | 热 | |
dressing4 | 温暖 | |
dressing5 | 凉爽 | |
dressing6 | 冷 | |
dressing7 | 寒冷 | |
dressing8 | 极冷 | |
感冒 | coldRisk1 | 少发 |
coldRisk2 | 较易发 | |
coldRisk3 | 易发 | |
coldRisk4: | 极易发 |