Difference between revisions of "小时级预报接口/v2.5"

From CaiyunWiki
Jump to: navigation, search
(Created page with "{{彩云天气 API 版本状态}} =='''授权与认证'''== 请先至彩云开放平台[https://dashboard.caiyunapp.com/user/sign_up/ 注册],注册后可以获得 token...")
 
m (请求参数)
 
(10 intermediate revisions by 2 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/hourly.json</code>
<nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.json</nowiki>
 
</code>
 
  
 
其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人!
 
其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人!
  
=='''请求样例'''==
+
== API 请求 ==
  
=== '''示例1如下''' ===
+
=== 示例 ===
<blockquote><code><nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.json</nowiki></code>
 
  
</blockquote><blockquote><nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.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/hourly.json</code>
<blockquote><code><nowiki>https://api.caiyunapp.com/v2/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly?lang=en_US&hourlysteps=2</nowiki></code></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=19800(=3600*5.5),然后daily的计算都会做相应处理。</blockquote><blockquote>'''定制返回的起始时间戳 begin''':默认为当前utc时间戳,可以用来返回两日内的历史数据</blockquote><blockquote>'''定制返回逐小时预报总小时数 hourlysteps''':默认为48小时(包括当前时刻)</blockquote><blockquote>'''定制返回逐日预报总天数 dailysteps''':默认为5天(包括今天)</blockquote>
+
* <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.jsonp?callback=MYCALLBACK</code>
==返回结构和说明==
 
<syntaxhighlight lang="javascript">
 
  
{  status:ok,
+
=== 请求参数 ===
    api_version:v2.2,                                                                                                          // 版本号
 
    api_status:active,                                                                                                        // 版本号状态
 
    lang:en_US,                                                                                                                // 语言
 
    unit:metric,                                                                                                              // 单位制
 
    result:{
 
        hourly:{
 
            status:ok,                                                                                                          // 逐小时预报模块返回状态
 
            temperature:[{value:23.0,datetime:2018-11-20 10:00},{value:22.0,datetime:2018-11-20 11:00}]},                          // 温度
 
            pres:[{value:100279.8643200001,datetime:2018-11-20 10:00},{value:100249.1918336001,datetime:2018-11-20 11:00}],        // 气压
 
            humidity:[{value:0.77,datetime:2018-11-20 10:00},{value:0.77,datetime:2018-11-20 11:00}],                              // 相对湿度
 
            wind:[ {  direction:95.62,                                                                                            // 风向,单位是度。正北方向为0度,顺时针增加到360度。
 
                      speed:22.85,datetime:2018-11-20 10:00},                                                                      // 风速,米制下是公里每小时
 
                  {  direction:97.97,
 
                      speed:23.27,datetime:2018-11-20 11:00}],
 
            precipitation:[{value:0.0,datetime:2018-11-20 10:00},{value:0.0,datetime:2018-11-20 11:00}],                            // 本地降水强度(单位见表格)
 
            cloudrate:[{value:0.77,datetime:2018-11-20 10:00},{value:0.46,datetime:2018-11-20 11:00}],                              // 云量
 
            dswrf:[{value:344.09456384,datetime:2018-11-20 10:00},{value:325.9617024,datetime:2018-11-20 11:00}],                  // 短波辐射
 
            visibility:[{value:23.24,datetime:2018-11-20 10:00},{value:23.0,datetime:2018-11-20 11:00}],                            // 能见度
 
  
            skycon:[{value:PARTLY_CLOUDY_DAY,datetime:2018-11-20 10:00},{value:PARTLY_CLOUDY_DAY,datetime:2018-11-20 11:00}],       // 主要天气现象
+
* 经纬度:必须,无缺省值,经度在前,纬度在后,中间用半角逗号隔开,如 <code>121.6544,25.1552</code>
            description:cloudy, clear weather after 7 tomorrow morning, increasing cloudiness,                                      // 逐小时天气预报,自然语言描述
+
* 返回格式:必须,无缺省值,可选项目包括json 或者 jsonp,jsonp 需提供回调函数名
            forecast_keypoint:cloudy, clear weather after 7 tomorrow morning, increasing cloudiness,primary:0,                    // 逐小时和逐分钟天气预报,综合自然语言描述
+
* 语言选项 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/hourly.json?lang=en_US</code>
 +
** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/139.7690,35.6804/hourly.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/hourly.json?lang=en_US&unit=imperial</code>
 +
* 小时步长选项  hourlysteps: 可选,缺省值是 <code>48</code>,  选择范围 <code> 1 ~ 360 </code>
 +
** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/-74.0060,40.7128/hourly.json?hourlysteps=12</code>
  
            pm25:[{value:8,datetime:2018-11-20 10:00},{value:9,datetime:2018-11-20 11:00}],                                        // PM2.5
+
== API 返回值 ==
            aqi:[{value:33,datetime:2018-11-20 10:00},{value:13,datetime:2018-11-20 11:00}]                                        // AQI(国标)
 
            },
 
    location:[25.1552,
 
              121.6544]                                                                                                            // 经纬度
 
    server_time:1542695724,                                                                                                    // 服务器本次返回的utc时间戳
 
    tzshift:14400,                                                                                                              // 时区的偏移秒数,如东八区就是 28800 秒
 
}
 
  
 +
=== 返回结构说明 ===
 +
 +
<syntaxhighlight lang="yaml">
 +
status: ok
 +
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:
 +
  hourly:
 +
    status: ok
 +
    description: 未来24小时阴                      #预报自然语言表述
 +
    skycon:                                      #天气状态
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: CLOUDY
 +
    temperature:                                  #温度
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: 17.2
 +
    precipitation:                                #降雨
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: 0.0
 +
    cloudrate:                                    #云量
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: 1.0
 +
    humidity:                                    #相对湿度
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: 0.81
 +
    pressure:                                    #气压
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: 99897.4914560001
 +
    wind:                                        #风力、风向
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      direction: 26.03
 +
      speed: 20.93
 +
    visibility:                                  #能见度
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: 23.77
 +
    dswrf:                                        #短波辐射下向通量
 +
    - datetime: 2020-04-07T16:00+08:00
 +
      value: 113.6283648
 +
    air_quality:
 +
      aqi:                                        # AQI
 +
      - datetime: 2020-04-07T16:00+08:00
 +
        value:
 +
          chn: 14                                #国标
 +
          usa: 14                                #美标
 +
      pm25:                                      #PM25
 +
      - datetime: 2020-04-07T16:00+08:00
 +
        value: 8
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=='''变量说明'''==
+
=== 返回错误 ===
<blockquote>逐小时预报,没有生活指数变量</blockquote>
+
 
{| class="wikitable"
+
=== 天气变量 ===
! 名称
+
 
! 健值路径(jsonpath) !! 量 !! 时间粒度 !! 地理范围 !! 注释
+
{{:小时级预报接口/v2.5/天气变量}}
|-
 
! 温度
 
| $.result.hourly.temperature.value || 温度 || 逐小时预报 || 全球 || 地表2米气温
 
|-
 
! 气压
 
| $.result.hourly.pres.value || 气压(Pa) || 逐小时预报 || 全球 || 地面气压
 
|-
 
! 相对湿度
 
| $.result.hourly.humidity.value || 相对湿度(%) || 逐小时预报 || 全球 || 地表2米湿度
 
|-
 
! 风向
 
| $.result.hourly.wind.direction.value || 风向 || 逐小时预报 || 全球 || 地表10米风向
 
|-
 
! 风速
 
| $.result.hourly.wind.speed.value || 风速 || 逐小时预报 || 全球 || 地表10米风速
 
|-
 
! 本地降水强度
 
| $.result.hourly.precipitation.value || 降水量(mm/h) || 逐小时预报 || 全球 || 本地降水量
 
|-
 
! 云量
 
| $.result.hourly.cloudrate.value || 云量(0.0-1.0) || 逐小时预报 || 全球 || 全天总云量
 
|-
 
! 短波辐射
 
| $.result.hourly.dswrf.value|| 向下短波辐射通量(W/M2) || 逐小时预报 || 全球 || 地表向下短波辐射通量
 
|-
 
! 能见度
 
| $.result.hourly.visibility.value || 能见度 || 逐小时预报 || 全球 || 地表水平能见度
 
|-
 
!
 
!
 
!
 
!
 
!
 
!
 
|-
 
! 主要天气现象
 
| $.result.hourly.skycon.value || 天气状况 || 逐小时预报 || 全球 || 天气状况
 
|-
 
! 逐小时预报自然语言描述
 
| $.result.hourly.description || 舒适度指数自然语言 || 逐小时预报 || 全球 || 舒适度指数及其描述
 
|-
 
! 综合预报自然语言描述
 
| $.result.hourly.forecast_keypoint || 紫外线指数自然语言 || 逐小时预报 || 全球 || 逐小时和逐分钟天气预报,综合自然语言描述
 
|-
 
!
 
!
 
!
 
!
 
!
 
!
 
|-
 
! PM25浓度
 
| $.result.hourly.pm25.value || PM25浓度(μg/m3) || 逐小时预报 || 大陆、港澳台、暂无印度 || PM25浓度
 
|-
 
! AQI
 
| $.result.hourly.aqi.value || 国标AQI || 逐小时预报 || 大陆、港澳台、暂无印度 || 国标AQI
 
|}
 
{{天气现象}}
 
  
==支持的单位制==
+
== 变量详细说明 ==
 +
 
 +
===支持的单位制===
  
 
{{Template:彩云天气 API/支持的单位制}}
 
{{Template:彩云天气 API/支持的单位制}}
 +
 +
== 常量详细说明 ==
 +
 +
===天气现象代码===
 +
 +
{{:天气现象代码表}}
 +
 +
===生活指数等级===
 +
 +
{{:生活指数等级}}
 +
  
 
[[Category:API 产品]]
 
[[Category:API 产品]]

Latest revision as of 06:48, 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/hourly.json

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

API 请求

示例

这里是测试 token ,即 TAkhjf8d1nlSlspN

请求参数

API 返回值

返回结构说明

status: ok
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:
  hourly:
    status: ok
    description: 未来24小时阴                       #预报自然语言表述
    skycon:                                       #天气状态
    - datetime: 2020-04-07T16:00+08:00
      value: CLOUDY
    temperature:                                  #温度
    - datetime: 2020-04-07T16:00+08:00
      value: 17.2
    precipitation:                                #降雨
    - datetime: 2020-04-07T16:00+08:00
      value: 0.0
    cloudrate:                                    #云量
    - datetime: 2020-04-07T16:00+08:00
      value: 1.0
    humidity:                                     #相对湿度
    - datetime: 2020-04-07T16:00+08:00
      value: 0.81
    pressure:                                     #气压
    - datetime: 2020-04-07T16:00+08:00
      value: 99897.4914560001
    wind:                                         #风力、风向
    - datetime: 2020-04-07T16:00+08:00
      direction: 26.03
      speed: 20.93
    visibility:                                   #能见度
    - datetime: 2020-04-07T16:00+08:00
      value: 23.77
    dswrf:                                        #短波辐射下向通量
    - datetime: 2020-04-07T16:00+08:00
      value: 113.6283648
    air_quality:
      aqi:                                        # AQI
      - datetime: 2020-04-07T16:00+08:00
        value:
          chn: 14                                 #国标
          usa: 14                                 #美标
      pm25:                                       #PM25
      - datetime: 2020-04-07T16:00+08:00
        value: 8

返回错误

天气变量

逐小时预报,没有生活指数变量

名称 健值路径(jsonpath) 时间粒度 地理范围 注释
温度 $.result.hourly.temperature.value 温度 逐小时预报 全球 地表2米气温
气压 $.result.hourly.pressure.value 气压(Pa) 逐小时预报 全球 地面气压
相对湿度 $.result.hourly.humidity.value 相对湿度(%) 逐小时预报 全球 地表2米湿度
风向 $.result.hourly.wind.direction.value 风向 逐小时预报 全球 地表10米风向
风速 $.result.hourly.wind.speed.value 风速 逐小时预报 全球 地表10米风速
本地降水强度 $.result.hourly.precipitation.value 降水量(mm/h) 逐小时预报 全球 本地降水量
云量 $.result.hourly.cloudrate.value 云量(0.0-1.0) 逐小时预报 全球 全天总云量
短波辐射 $.result.hourly.dswrf.value 向下短波辐射通量(W/M2) 逐小时预报 全球 地表向下短波辐射通量
能见度 $.result.hourly.visibility.value 能见度 逐小时预报 全球 地表水平能见度
主要天气现象 $.result.hourly.skycon.value 天气状况 逐小时预报 全球 参见#天气现象代码
逐小时预报自然语言描述 $.result.hourly.description 自然语言描述 逐小时预报 全球 逐小时预报自然语言描述
综合预报自然语言描述 $.result.hourly.forecast_keypoint 自然语言描述 逐小时预报 全球 逐小时或逐分钟天气预报,综合自然语言描述
PM25浓度 $.result.hourly.pm25.value PM25浓度(μg/m3) 逐小时预报 大陆、港澳台、暂无印度 PM25浓度
AQI $.result.hourly.aqi.value 国标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)来判断,研发中...

常量详细说明

天气现象代码

天气现象 代码 备注
晴(白天) 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 极强
洗车 carWashing1 适宜
carWashing2 较适宜
carWashing3 较不适宜
carWashing4 不适宜
穿衣 dressing0 极热
dressing1 极热
dressing2 很热
dressing3
dressing4 温暖
dressing5 凉爽
dressing6
dressing7 寒冷
dressing8 极冷
感冒 coldRisk1 少发
coldRisk2 较易发
coldRisk3 易发
coldRisk4: 极易发