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

From Caiyun Wiki
Jump to: navigation, search
(示例2如下)
 
(31 intermediate revisions by 4 users 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/minutely.json</code>
<nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json</nowiki>
 
</code>
 
  
 
其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人!
 
其中 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,
 
                                          0.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,
 
                                          0.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,
 
                                          0.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,
 
                                          0.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,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,
 
                                      0.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,
 
                                      0.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                                        # 返回状态
            118.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>
 
</syntaxhighlight>
  
=='''变量说明'''==
+
=== 返回错误 ===
<blockquote>逐日预报,没有逐日预报的自然语言描述字段</blockquote>
+
 
{| class="wikitable"
+
=== 天气变量 ===
! 名称
+
 
! 健值路径(jsonpath) !! 量 !! 时间粒度 !! 地理范围 !! 注释
+
{{:分钟级降雨预报接口/v2.5/天气变量}}
|-
+
 
! 短临2h降水强度
+
== 变量详细说明 ==
| $.result.minutely.precipitation_2h[:] || 雷达降水强度 || 逐日预报 || 全球 || 本地未来2小时逐分钟,短临降水强度预报
 
|-
 
! 短临4h降水强度
 
| $.result.minutely.probability_4h[:] || 雷达降水强度 || 逐日预报 || 全球 || 本地未来2小时逐30钟,短临降水强度预报
 
|}
 
  
==支持的单位制==
+
===支持的单位制===
  
 
{{Template:彩云天气 API/支持的单位制}}
 
{{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 产品]]
 
[[Category:API 产品]]

Latest revision as of 05:12, 15 April 2020

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

本文版本:分钟级降雨预报接口/v2.5,当前稳定版本版本:v2.5,历史版本:v2.2v2.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

请求参数

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 暴雨/雪

降水概率

目前我们只提供了四个时段内的降水概率,取值都是从 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分钟级预报全球覆盖范围概览
国家
欧洲 意大利、立陶宛、马耳他、法国、斯洛伐克、挪威、白俄罗斯、冰岛、 捷克、斯洛文尼亚、德国、西班牙、乌克兰、丹麦、波兰、芬兰、瑞典、克罗地亚、俄罗斯、罗马尼亚、葡萄牙、爱沙尼亚、塞尔维亚、英国、奥地利、希腊、匈牙利
大洋洲 澳大利亚、斐济,关岛,澳大利亚,马绍尔群岛,新喀里多尼亚
亚洲 中国大陆及港澳台,钓鱼岛,南沙群岛,土耳其,巴林,沙特阿拉伯,印度尼西亚,伊朗,新加坡,阿曼,菲律宾,日本,印度,柬埔寨,塞浦路斯,马来西亚,越南,科威特,泰国,韩国,朝鲜
北美 加拿大,巴哈马,开曼群岛,墨西哥,巴拿马,马提尼克,古巴,美国,百慕大,波多黎各,库拉岛,瓜德罗普,尼加拉瓜
南美 巴西,法属圭亚那,哥伦比亚,圭亚那,巴拉圭,阿根廷