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

From Caiyun Wiki
Jump to: navigation, search
(返回结构和说明)
(请求参数)
 
(6 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/daily.json</code>
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.json
 
</code>
 
  
 
其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人!
 
其中 TAkhjf8d1nlSlspN 就是一个共用测试 token 。不要把私有token 告诉任何人!
  
=='''请求样例'''==
+
== API 请求 ==
 +
 
 +
=== 示例 ===
 +
 
 +
这里是测试 token ,即 <code>TAkhjf8d1nlSlspN</code>
  
=== '''示例1如下''' ===
+
* <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.json</code>
<blockquote><code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.json</code>
+
* <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.jsonp?callback=MYCALLBACK</code>
  
</blockquote><blockquote>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.jsonp?callback=MYCALLBACK</blockquote><blockquote>'''token:'''这里是测试 token ,即 <code>TAkhjf8d1nlSlspN</code></blockquote><blockquote>'''经纬度:'''经度在前,纬度在后,中间用半角逗号隔开,这里是 <code>121.6544,25.1552</code></blockquote><blockquote>'''返回格式:'''json 或者 jsonp,jsonp 需提供回调函数名</blockquote>
+
=== 请求参数 ===
 +
 
 +
* 经纬度:必须,无缺省值,经度在前,纬度在后,中间用半角逗号隔开,如 <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/daily.json?lang=en_US</code>
 +
** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/139.7690,35.6804/daily.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/daily.json?lang=en_US&unit=imperial</code>
 +
* 天步长选项 dailysteps: 可选,缺省值是 <code>5</code>,  选择范围 <code> 1 ~ 15 </code>
 +
** <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/-74.0060,40.7128/daily.json?dailysteps=3</code>
 +
 
 +
== API 返回值 ==
 +
 
 +
=== 返回结构说明 ===
  
=== '''示例2如下''' ===
 
<blockquote><code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.json?lang=en_US&dailysteps=360</code></blockquote><blockquote>'''语言选项 lang:'''默认为简体中文(zh_CN)、繁体中文(zh_TW)、美式英语(en_US)、英式英语(en_GB)</blockquote><blockquote>'''单位制选项 unit:'''默认为公制(metric)、科学单位体系(SI) 、英制(imperial)</blockquote><blockquote>'''定制返回逐日预报总日数 dailysteps''':默认为5日</blockquote><blockquote>'''时区偏移秒数 tzshift:'''默认为东八区,tzshift=28800;例如:印度东5.5区,tzshift=3600*5.5==19800,v2.3之后版本,返回时区信息,使用秒是为了支持像尼泊尔这样的差 5 小时 45 分钟的地区,它们有非整齐的偏移量;考虑了欧美夏令时。</blockquote>
 
==返回结构和说明==
 
 
<syntaxhighlight lang="yaml">
 
<syntaxhighlight lang="yaml">
 
status: ok                                        #返回状态
 
status: ok                                        #返回状态
Line 131: Line 146:
 
         index: '1'
 
         index: '1'
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
=== 返回错误 ===
  
=='''变量说明'''==
+
=== 天气变量 ===
<blockquote>逐日预报,没有逐日预报的自然语言描述字段</blockquote>
 
{| class="wikitable"
 
! 名称
 
! 健值路径(jsonpath) !! 量 !! 时间粒度 !! 地理范围 !! 注释
 
|-
 
! 温度
 
| $.result.daily.temperature[max,min,avg] || 温度 || 逐日预报 || 全球 || 地表2米气温
 
|-
 
! 气压
 
| $.result.daily.pres[max,min,avg] || 气压(Pa) || 逐日预报 || 全球 || 地面气压
 
|-
 
! 相对湿度
 
| $.result.daily.humidity[max,min,avg] || 相对湿度(%) || 逐日预报 || 全球 || 地表2米湿度
 
|-
 
! 风速
 
| $.result.daily.wind.speed[max,min,avg] || 风速 || 逐日预报 || 全球 || 地表10米风速
 
|-
 
! 本地降水强度
 
| $.result.daily.precipitation[max,min,avg] || 降水量(mm/h) || 逐日预报 || 全球 || 本地降水量
 
|-
 
! 云量
 
| $.result.daily.cloudrate[max,min,avg] || 云量(0.0-1.0) || 逐日预报 || 全球 || 全天总云量
 
|-
 
! 短波辐射
 
| $.result.daily.dswrf[max,min,avg]|| 向下短波辐射通量(W/M2) || 逐日预报 || 全球 || 地表向下短波辐射通量
 
|-
 
! 能见度
 
| $.result.daily.visibility[max,min,avg] || 能见度 || 逐日预报 || 全球 || 地表水平能见度
 
|-
 
!
 
!
 
!
 
!
 
!
 
!
 
|-
 
! 全天主要天气现象
 
| $.result.daily.skycon.value || 天气状况 || 逐日预报 || 全球 || 全天主要天气现象
 
|-
 
! 白天主要天气现象
 
| $.result.daily.skycon_08h_20h.value|| 天气状况 || 逐日预报 || 全球 || 白天主要天气现象
 
|-
 
! 夜晚主要天气现象
 
| $.result.daily.skycon_20h_32h.value|| 天气状况 || 逐日预报 || 全球 || 夜晚主要天气现象
 
|-
 
! 紫外线指数
 
| $.result.daily.ultraviolet.desc|| 紫外线指数自然语言 || 逐日预报 || 全球 || 紫外线指数及其描述
 
|-
 
! 舒适度指数
 
| $.result.daily.comfort.desc|| 舒适度指数自然语言 || 逐日预报 || 全球 || 舒适度指数及其描述
 
|-
 
! 洗车指数
 
| $.result.daily.carWashing.desc|| 洗车指数自然语言 || 逐日预报 || 全球 || 洗车指数及其描述
 
|-
 
! 感冒指数
 
| $.result.daily.coldRisk.desc|| 感冒指数自然语言 || 逐日预报 || 全球 || 感冒指数及其描述
 
|-
 
! 穿衣指数
 
| $.result.daily.dressing.desc|| 冷热指数自然语言 || 逐日预报 || 全球 || 穿衣指数(dressing),不建议继续使用,请使用舒适度
 
|-
 
!
 
!
 
!
 
!
 
!
 
!
 
|-
 
! PM25浓度
 
| $.result.daily.pm25[max,min,avg] || PM25浓度(μg/m3) || 逐日预报 || 大陆、港澳台、暂无印度 || PM25浓度
 
|-
 
! AQI
 
| $.result.daily.aqi[max,min,avg] || 国标AQI || 逐日预报 || 大陆、港澳台、暂无印度 || 国标AQI
 
|-
 
!
 
!
 
!
 
!
 
!
 
!
 
|-
 
! 日出日落
 
| $.result.astro.aqi[sunrise,sunset] || 国标AQI || 逐日预报 || 大陆、港澳台、暂无印度 || 日出日落(当地时区的时刻,tzshift不作用在这个变量)
 
|}
 
{{天气现象}}
 
  
=='''生活指数'''==
+
{{:天级预报接口/v2.5/天气变量}}
{{生活指数}}
+
 
 +
== 变量详细说明 ==
 +
 
 +
===支持的单位制===
  
==支持的单位制==
 
 
{{Template:彩云天气 API/支持的单位制}}
 
{{Template:彩云天气 API/支持的单位制}}
 +
 +
== 常量详细说明 ==
 +
 +
===天气现象代码===
 +
 +
{{:天气现象代码表}}
 +
 +
===生活指数等级===
 +
 +
{{:生活指数等级}}
  
 
[[Category:API 产品]]
 
[[Category:API 产品]]

Latest revision as of 06:47, 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/daily.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:
  daily:
    status: ok
    astro:                                          #日出与日落时刻
    - date: 2020-04-07T00:00+08:00
      sunrise:
        time: 05:38
      sunset:
        time: 18:12
    skycon:                                         #天气状态
    - date: 2020-04-07T00:00+08:00
      value: CLOUDY
    temperature:                                    #温度,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg: 17.46
      max: 20.0
      min: 17.0
    precipitation:                                  #降雨量,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg: 0.0058
      max: 2.4895
      min: 0.0
    pressure:                                       #气压,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg: 100033.73
      max: 100137.49
      min: 99817.49
    wind:                                           #风力与风向,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg:
        direction: 27.97
        speed: 20.44
      max:
        direction: 19.12
        speed: 23.11
      min:
        direction: 38.45
        speed: 15.84
    cloudrate:                                      #云量,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg: 1.0
      max: 1.0
      min: 0.99
    humidity:                                       #相对湿度,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg: 0.8
      max: 0.95
      min: 0.79
    dswrf:                                          #短波辐射下向通量,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg: 48.6
      max: 121.5
      min: 0.0
    visibility:                                     #能见度,最大值,平均值,最小值
    - date: 2020-04-07T00:00+08:00
      avg: 24.3
      max: 26.37
      min: 3.02
    air_quality:
      aqi:                                          #AQI,最大值,平均值,最小值
      - date: 2020-04-07T00:00+08:00
        avg:
          chn: 10.88
          usa: 10.88
        max:
          chn: 17
          usa: 17
        min:
          chn: 10
          usa: 10
      pm25:                                         #PM25,最大值,平均值,最小值
      - date: 2020-04-07T00:00+08:00
        avg: 7.5
        max: 12
        min: 7
    life_index:
      carWashing:                                   #洗车指数
      - date: 2020-04-07T00:00+08:00
        desc: 较不适宜
        index: '3'
      coldRisk:                                     #感冒指数
      - date: 2020-04-07T00:00+08:00
        desc: 易发
        index: '3'
      comfort:                                      #舒适度指数
      - date: 2020-04-07T00:00+08:00
        desc: 凉爽
        index: '6'
      dressing:                                     #穿衣指数
      - date: 2020-04-07T00:00+08:00
        desc: 凉爽
        index: '5'
      ultraviolet:                                  #紫外线指数
      - date: 2020-04-07T00:00+08:00
        desc: 最弱
        index: '1'

返回错误

天气变量

逐日预报,没有逐日预报的自然语言描述字段

名称 健值路径(jsonpath) 时间粒度 地理范围 注释
温度 $.result.daily.temperature[max,min,avg] 温度 逐日预报 全球 地表2米气温
气压 $.result.daily.pressure[max,min,avg] 气压(Pa) 逐日预报 全球 地面气压
相对湿度 $.result.daily.humidity[max,min,avg] 相对湿度(%) 逐日预报 全球 地表2米湿度
风速 $.result.daily.wind.speed[max,min,avg] 风速 逐日预报 全球 地表10米风速
本地降水强度 $.result.daily.precipitation[max,min,avg] 降水量(mm/h) 逐日预报 全球 本地降水量
云量 $.result.daily.cloudrate[max,min,avg] 云量(0.0-1.0) 逐日预报 全球 全天总云量
短波辐射 $.result.daily.dswrf[max,min,avg] 向下短波辐射通量(W/M2) 逐日预报 全球 地表向下短波辐射通量
能见度 $.result.daily.visibility[max,min,avg] 能见度 逐日预报 全球 地表水平能见度
全天主要天气现象 $.result.daily.skycon.value 天气状况 逐日预报 全球 全天主要天气现象,参见#天气现象代码
白天主要天气现象 $.result.daily.skycon_08h_20h.value 天气状况 逐日预报 全球 白天主要天气现象,参见#天气现象代码
夜晚主要天气现象 $.result.daily.skycon_20h_32h.value 天气状况 逐日预报 全球 夜晚主要天气现象,参见#天气现象代码
紫外线指数 $.result.daily.ultraviolet.desc 紫外线指数自然语言 逐日预报 全球 紫外线指数及其描述
舒适度指数 $.result.daily.comfort.desc 舒适度指数自然语言 逐日预报 全球 舒适度指数及其描述
洗车指数 $.result.daily.carWashing.desc 洗车指数自然语言 逐日预报 全球 洗车指数及其描述
感冒指数 $.result.daily.coldRisk.desc 感冒指数自然语言 逐日预报 全球 感冒指数及其描述
穿衣指数 $.result.daily.dressing.desc 冷热指数自然语言 逐日预报 全球 穿衣指数(dressing),不建议继续使用,请使用舒适度
PM25浓度 $.result.daily.pm25[max,min,avg] PM25浓度(μg/m3) 逐日预报 大陆、港澳台、暂无印度 PM25浓度
AQI $.result.daily.aqi[max,min,avg] 国标AQI 逐日预报 大陆、港澳台、暂无印度 国标AQI
日出日落 $.result.daily.astro[sunrise,sunset] 时间 逐日预报 大陆、港澳台、暂无印度 日出日落(当地时区的时刻,tzshift不作用在这个变量)

变量详细说明

支持的单位制

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 极强
紫外线(天级别) ultraviolet1 最弱
ultraviolet2
ultraviolet3 中等
ultraviolet4
ultraviolet5 很强
穿衣 dressing0 极热
dressing1 极热
dressing2 很热
dressing3
dressing4 温暖
dressing5 凉爽
dressing6
dressing7 寒冷
dressing8 极冷
感冒 coldRisk1 少发
coldRisk2 较易发
coldRisk3 易发
coldRisk4: 极易发