Difference between revisions of "分钟级降雨预报接口/v2.5"

Latest revision as of 05:12, 15 April 2020

快速通道：天气业务 | 天气开发者 | 小译开发者

本文版本：分钟级降雨预报接口/v2.5，当前稳定版本版本：v2.5，历史版本：v2.2，v2.3，和 v2.4。

授权与认证

请先至彩云开放平台注册，注册后可以获得 token 。

把您的 token 拼到 API 请求的 URL 中，如

https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json

其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人！

API 请求

示例

这里是测试 token ，即 TAkhjf8d1nlSlspN

请求参数

经纬度：必须，无缺省值，经度在前，纬度在后，中间用半角逗号隔开，如 121.6544,25.1552
返回格式：必须，无缺省值，可选项目包括json 或者 jsonp，jsonp 需提供回调函数名
语言选项 lang: 可选，缺省值是 zh_CN，可选项目包括简体中文（zh_CN，默认）、繁体中文（zh_TW）、美式英语（en_US）、英式英语（en_GB）、日语（ja）
- https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/-74.0060,40.7128/minutely.json?lang=en_US
- https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/139.7690,35.6804/minutely.json?lang=ja
单位制选项 unit: 可选，缺省值是 metric，可选项目包括公制metric，英制imperial，和科学单位制 SI
- https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/-74.0060,40.7128/minutely.json?lang=en_US&unit=imperial

API 返回值

返回结构说明

status: ok                                         # 返回状态
api_status: active                                 # API 服务状态
api_version: v2.5                                  # API 版本号
server_time: 1586247444                            # 响应时刻服务器时间
timezone: Asia/Taipei                              # 时区信息
tzshift: 28800                                     # 时区偏移秒数
unit: metric                                       # 单位制
lang: zh_CN                                        # 语言
location:
- 25.1552                                          # 纬度
- 121.6544                                         # 经度
result:
  minutely:
    status: ok
    datasource: radar                              # 预报依据的数据源
    description: 附近正在下雨，出门还是带把伞吧~        # 预报的自然语言描述
    probability:                                   # 降雨概率
    - 0.0                                          # 0.0~0.5 小时间的降雨概率
    - 0.0                                          # 0.5~1.0 小时间的降雨概率
    - 0.0                                          # 1.0~1.5 小时间的降雨概率
    - 0.0                                          # 1.5~2.0 小时间的降雨概率
    precipitation:                                 # 预报的分钟级别的降雨强度 00~60 分钟
    - 0.0                                          # 第 0 分钟的预报值
    - ...                                          # 共 60 个数据项
    precipitation_2h:                              # 预报的分钟级别的降雨强度 000~120 分钟
    - 0.0                                          # 第 0 分钟的预报值
    - ...                                          # 共 120 个数据项

返回错误

天气变量

名称	健值路径（jsonpath）	量	取值范围	时间粒度	更新频次	地理范围	注释
降水概率	$.result.minutely.probability	降水概率	0.0~1.0	未来两小时	实时更新	数据覆盖范围	本地未来1小时逐分钟短临降水强度预报
一小时降水强度	$.result.minutely.precipitation	雷达降水强度	0.0~1.0	未来一小时	实时更新	数据覆盖范围	本地未来1小时逐分钟短临降水强度预报
两小时降水强度	$.result.minutely.precipitation_2h	雷达降水强度	0.0~1.0	未来两小时	实时更新	数据覆盖范围	本地未来2小时逐分钟短临降水强度预报

变量详细说明

支持的单位制

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 单位制转换
- https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.4750,24.7695/minutely?unit=metric:v2

降水概率

目前我们只提供了四个时段内的降水概率，取值都是从 0.0 到 1.0 之间的数值

第 000 分钟 ~ 第 030 分钟的降水概率，json 路径在 $.result.minutely.probability[0]
第 030 分钟 ~ 第 060 分钟的降水概率，json 路径在 $.result.minutely.probability[1]
第 060 分钟 ~ 第 090 分钟的降水概率，json 路径在 $.result.minutely.probability[2]
第 090 分钟 ~ 第 120 分钟的降水概率，json 路径在 $.result.minutely.probability[3]

常量详细说明

天气现象代码

天气现象	代码	备注
晴（白天）	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:	极易发

预报数据覆盖范围

彩云天气是全球首家且唯一的可以提供全球分钟级预报图和预报数据的天气 API 。彩云天气已接入全球 95% 以上的天气雷达资料，在以下地区提供分钟级预报：

彩云天气2020分钟级预报全球覆盖范围概览

洲	国家
欧洲	意大利、立陶宛、马耳他、法国、斯洛伐克、挪威、白俄罗斯、冰岛、捷克、斯洛文尼亚、德国、西班牙、乌克兰、丹麦、波兰、芬兰、瑞典、克罗地亚、俄罗斯、罗马尼亚、葡萄牙、爱沙尼亚、塞尔维亚、英国、奥地利、希腊、匈牙利
大洋洲	澳大利亚、斐济，关岛，澳大利亚，马绍尔群岛，新喀里多尼亚
亚洲	中国大陆及港澳台，钓鱼岛，南沙群岛，土耳其，巴林，沙特阿拉伯，印度尼西亚，伊朗，新加坡，阿曼，菲律宾，日本，印度，柬埔寨，塞浦路斯，马来西亚，越南，科威特，泰国，韩国，朝鲜
北美	加拿大，巴哈马，开曼群岛，墨西哥，巴拿马，马提尼克，古巴，美国，百慕大，波多黎各，库拉岛，瓜德罗普，尼加拉瓜
南美	巴西，法属圭亚那，哥伦比亚，圭亚那，巴拉圭，阿根廷

@@ Line 1: / Line 1: @@
+{{导览}}
 {{彩云天气 API 版本状态}}
-=='''授权与认证'''==
+== 授权与认证 ==
 请先至彩云开放平台[https://dashboard.caiyunapp.com/user/sign_up/ 注册]，注册后可以获得 token 。
 把您的 token 拼到 API 请求的 URL 中，如
-<code>
+<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json</code>
-<nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json</nowiki>
-</code>
 其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人！
-=='''请求样例'''==
+== API 请求 ==
-=== '''示例1如下''' ===
+=== 示例 ===
-<blockquote><code><nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json</nowiki></code>
-</blockquote><blockquote><nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.jsonp?callback=MYCALLBACK</nowiki></blockquote><blockquote>'''token：'''这里是测试 token ，即 <code>TAkhjf8d1nlSlspN</code></blockquote><blockquote>'''经纬度：'''经度在前，纬度在后，中间用半角逗号隔开，这里是 <code>121.6544,25.1552</code></blockquote><blockquote>'''返回格式：'''json 或者 jsonp，jsonp 需提供回调函数名</blockquote>
+这里是测试 token ，即 <code>TAkhjf8d1nlSlspN</code>
-=== '''示例2如下''' ===
+* <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json</code>
-<blockquote><nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/118.7087,26.9582/minutely?lang=en_US&getplacename=True</nowiki></blockquote><blockquote>'''语言选项 lang：'''默认为简体中文（zh_CN）、繁体中文（zh_TW）、美式英语（en_US）、英式英语（en_GB）</blockquote><blockquote>'''单位制选项 unit：'''默认为公制（metric）、科学单位体系（SI） 、英制（imperial）</blockquote><blockquote>'''时区偏移秒数：tzshift：'''默认为东八区，tzshift=28800；例如：印度东5.5区，tzshift=3600*5.5==19800，v2.3之后版本，返回时区信息，使用秒是为了支持像尼泊尔这样的差 5 小时 45 分钟的地区，它们有非整齐的偏移量；考虑了欧美夏令时。</blockquote><blockquote>
+* <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.jsonp?callback=MYCALLBACK'''</code>
+* <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/118.7087,26.9582/minutely?lang=en_US</code>
-==返回结构和说明==
+=== 请求参数 ===
-<syntaxhighlight lang="javascript">
+* 经纬度：必须，无缺省值，经度在前，纬度在后，中间用半角逗号隔开，如 <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/minutely.json?lang=en_US</code>
+** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/139.7690,35.6804/minutely.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/minutely.json?lang=en_US&unit=imperial</code>
-{   status:ok,
+== API 返回值 ==
-    api_version:v2.2,                                                                                                                                            // 版本号
-    api_status:active,                                                                                                                                           // 版本号状态
-    lang:zh_CN,                                                                                                                                                  // 语言
-    unit:metric,                                                                                                                                                 // 单位制
-    result:{ forecast_keypoint:Cloudy here but it's raining SE 41 km away,                                                                                                       // 逐小时和逐分钟天气预报，综合自然语言描述
-              minutely:{status:ok,                                                                                                                                // 逐日预报模块返回状态
-                        description:Cloudy here but it's raining SE 41 km away,                                                                                              // 逐小时天气预报，自然语言描述
-                        precipitation_2h:[0.0507,0.0348,0.0211,0.0104,0.0033,0.0,0.0,0.0,0.0,0.0,0.001,0.0016,0.0018,0.0016,0.001,0.0,0.0,0.0,0.0,0.0027,0.0096,0.0208,
-.0369,0.0559,0.0755,0.0934,0.1072,0.1146,0.1139,0.1068,0.0958,0.0831,0.0712,0.0625,0.0587,0.0588,0.061,0.0635,0.0646,0.0625,
-.056,0.0461,0.034,0.0214,0.0096,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0052,0.0114,0.0188,0.0279,0.0388,0.0521,0.0676,0.084,0.0996,
-.1128,0.1218,0.125,0.1213,0.1121,0.0995,0.0857,0.0726,0.0625,0.0568,0.0549,0.0557,0.058,0.0606,0.0625,0.0627,0.0615,0.0593,
-.0567,0.0541,0.0521,0.0509,0.0502,0.0494,0.0481,0.0457,0.0417,0.0357,0.0283,0.0202,0.0123,0.0053,0.0,0.0,0.0,0.0,0.0,0.0,
-.0,0.0008,0.0011,0.001,0.0007,0.0003,0.0,0.0,0.0,0.0,0.0001,0.0002,0.0,0.0,0.0,0.0001,0.0018,0.0051,0.0104,0.0181,0.0276],        // 未来2小时，逐分钟，雷达降水强度预报
-                        precipitation:[0.0507,0.0348,0.0211,0.0104,0.0033,0.0,0.0,0.0,0.0,0.0,0.001,0.0016,0.0018,0.0016,0.001,0.0,0.0,0.0,0.0,0.0027,0.0096,0.0208,
-.0369,0.0559,0.0755,0.0934,0.1072,0.1146,0.1139,0.1068,0.0958,0.0831,0.0712,0.0625,0.0587,0.0588,0.061,0.0635,0.0646,0.0625,
-.056,0.0461,0.034,0.0214,0.0096,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0052,0.0114,0.0188,0.0279,0.0388,0.0521,0.0676,0.084]，                // 未来1小时，逐分钟，雷达降水强度预报
-                        probability:[0.658591032,0.7041746378,0.5904211998,0.7576189041],                                                                                    // 未来2小时，逐半小时，雷达降水概率预报
+=== 返回结构说明 ===
-                        probability_4h:[0.7041746378,0.7576189041,0.764185369,0.6725049615],                                                                                 // 未来4小时，逐一小时，雷达降水概率预报
-                        datasource:radar},
+<syntaxhighlight lang="yaml">
-                primary:0},
-     location:[27.8943,
+status: ok                                         # 返回状态
-.1484],                                                                                                                                          // 经纬度
+api_status: active                                 # API 服务状态
-     placename:Unnamed Road, Wanli District, New Taipei City, Taiwan 207,                                                                                         // 经纬度处地址
+api_version: v2.5                                  # API 版本号
-     server_time:1542700934,                                                                                                                                      // 服务器本次返回的utc时间戳
+server_time: 1586247444                            # 响应时刻服务器时间
-     tzshift:28800                                                                                                                                                // 时区的偏移秒数，如东八区就是 28800 秒
+timezone: Asia/Taipei                              # 时区信息
-}
+tzshift: 28800                                     # 时区偏移秒数
+unit: metric                                       # 单位制
+lang: zh_CN                                        # 语言
+location:
+- 25.1552                                          # 纬度
+- 121.6544                                         # 经度
+result:
+  minutely:
+    status: ok
+    datasource: radar                              # 预报依据的数据源
+    description: 附近正在下雨，出门还是带把伞吧~        # 预报的自然语言描述
+    probability:                                   # 降雨概率
+    - 0.0                                          # 0.0~0.5 小时间的降雨概率
+    - 0.0                                          # 0.5~1.0 小时间的降雨概率
+    - 0.0                                          # 1.0~1.5 小时间的降雨概率
+    - 0.0                                          # 1.5~2.0 小时间的降雨概率
+    precipitation:                                 # 预报的分钟级别的降雨强度 00~60 分钟
+    - 0.0                                          # 第 0 分钟的预报值
+     - ...                                          # 共 60 个数据项
+     precipitation_2h:                              # 预报的分钟级别的降雨强度 000~120 分钟
+     - 0.0                                          # 第 0 分钟的预报值
+     - ...                                          # 共 120 个数据项
 </syntaxhighlight>
-=='''变量说明'''==
+=== 返回错误 ===
-<blockquote>逐日预报，没有逐日预报的自然语言描述字段</blockquote>
-{| class="wikitable"
+=== 天气变量 ===
-! 名称
-! 健值路径（jsonpath） !! 量 !! 时间粒度 !! 地理范围 !! 注释
+{{:分钟级降雨预报接口/v2.5/天气变量}}
-|-
-! 短临2h降水强度
+== 变量详细说明 ==
-| $.result.minutely.precipitation_2h[：] || 雷达降水强度 || 逐日预报 || 全球 || 本地未来2小时逐分钟，短临降水强度预报
-|-
-! 短临4h降水强度
-| $.result.minutely.probability_4h[：] || 雷达降水强度 || 逐日预报 || 全球 || 本地未来2小时逐30钟，短临降水强度预报
-|}
-==支持的单位制==
+===支持的单位制===
 {{Template:彩云天气 API/支持的单位制}}
+=== 雷达降水强度 ===
+{{:雷达降水强度}}
+=== 降水概率 ===
+目前我们只提供了四个时段内的降水概率，取值都是从 0.0 到 1.0 之间的数值
+* 第 000 分钟 ~ 第 030 分钟的降水概率，json 路径在 $.result.minutely.probability[0]
+* 第 030 分钟 ~ 第 060 分钟的降水概率，json 路径在 $.result.minutely.probability[1]
+* 第 060 分钟 ~ 第 090 分钟的降水概率，json 路径在 $.result.minutely.probability[2]
+* 第 090 分钟 ~ 第 120 分钟的降水概率，json 路径在 $.result.minutely.probability[3]
+== 常量详细说明 ==
+===天气现象代码===
+{{:天气现象代码表}}
+===生活指数等级===
+{{:生活指数等级}}
+== 预报数据覆盖范围 ==
+{{:分钟级降雨预报数据覆盖}}
 [[Category:API 产品]]

Difference between revisions of "分钟级降雨预报接口/v2.5"

Latest revision as of 05:12, 15 April 2020

Contents

授权与认证

API 请求

示例

请求参数

API 返回值

返回结构说明

返回错误

天气变量

变量详细说明

支持的单位制

雷达降水强度

降水概率

常量详细说明

天气现象代码

生活指数等级

预报数据覆盖范围

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools