Difference between revisions of "彩云天气 API/v2.5"

From Caiyun Wiki
Jump to: navigation, search
(→‎是否支持返回历史数据)
(→‎特性增强)
 
(21 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{彩云天气 API 版本状态}}
 
{{彩云天气 API 版本状态}}
  
−
== 数据覆盖范围 ==
+
{{彩云天气速查表}}
  
−
=== 天气数据覆盖区域 ===
 
−
* 小时级和天级天气数据覆盖全球任意经纬度;
 
−
* 分钟级降水数据覆盖范围如下:
 
−
[[File:2020.2 彩云天气全球数据覆盖范围概览.png|thumb|
 
−
彩云天气2020分钟级预报全球覆盖范围概览
 
−
]]
 
−
{| class="wikitable"
 
−
!洲
 
−
!国家
 
−
|-
 
−
|欧洲
 
−
|意大利、立陶宛、马耳他、法国、斯洛伐克、挪威、白俄罗斯、冰岛、 捷克、斯洛文尼亚、德国、西班牙、乌克兰、丹麦、波兰、芬兰、瑞典、克罗地亚、俄罗斯、罗马尼亚、葡萄牙、爱沙尼亚、塞尔维亚、英国、奥地利、希腊、匈牙利
 
−
|-
 
−
|澳大利亚
 
−
|斐济,关岛,澳大利亚,马绍尔群岛,新喀里多尼亚
 
−
|-
 
−
|亚洲
 
−
|中国大陆及港澳台,钓鱼岛,南沙群岛,土耳其,巴林,沙特阿拉伯,印度尼西亚,伊朗,新加坡,阿曼,菲律宾,日本,印度,柬埔寨,塞浦路斯,马来西亚,越南,科威特,泰国,韩国,朝鲜
 
−
|-
 
−
|澳洲
 
−
|澳大利亚
 
−
|-
 
−
|北美
 
−
|加拿大,巴哈马,开曼群岛,墨西哥,巴拿马,马提尼克,古巴,美国,百慕大,波多黎各,库拉岛,瓜德罗普,尼加拉瓜
 
−
|-
 
−
|南美
 
−
|巴西,法属圭亚那,哥伦比亚,圭亚那,巴拉圭,阿根廷
 
−
|}
 
  
−
=== 空气质量数据覆盖区域 ===
+
== 接口格式说明 ==
  
−
中国全境。即将开通全球。
+
<code>TAkhjf8d1nlSlspN</code> 是个例子,请使用你的 token
  
−
==状态==
+
* '''[[通用预报接口/v2.5|通用预报接口]]''':<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/weather.json</code>
−
状态:继承v2.4,本版本已经是稳定版本。
+
* '''[[实况天气接口/v2.5|实况天气接口]]''':<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/realtime.json</code>
 +
* '''[[分钟级降雨预报接口/v2.5|分钟级降雨预报接口]]''':<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json</code>
 +
* '''[[小时级预报接口/v2.5|小时级预报接口]]''':<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.json</code>
 +
* '''[[天级预报接口/v2.5|天级预报接口]]''':<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.json</code>
  
−
* [[实况天气接口/v2.5|实况天气接口]]:<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/forecast.json</code>
+
=== 格式变更 ===
−
* [[分钟级降雨预报接口]]:<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json</code>
 
−
* [[小时级预报接口/v2.5|小时级预报接口]]:[https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.json <code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.json</code>]
 
−
* [[天级预报接口/v2.5|天级预报接口]]:<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.json</code>
 
−
* [[通用预报接口/v2.5|通用点数据接口]]:<code>https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/weather.json</code>
 
  
−
== 数据类型及预报时长 ==
 
−
 
−
=== 数据类型 ===
 
−
{| class="wikitable"
 
−
|'''数据类型'''
 
−
|'''描述'''
 
−
|-
 
−
|'''实时数据'''
 
−
|温度、湿度、风向、风速、气压、云量、降水量(mm/h)/降水强度、PM 2.5、AQI、天气类型
 
−
|-
 
−
|'''分钟级降水数据'''
 
−
|未来两小时每分钟降水强度及每半小时降水概率、未来两小时降水情况的自然语言描述
 
−
|-
 
−
|'''逐小时数据'''
 
−
|温度、湿度、风向、风速、气压、云量、降水量(mm/h)/降水强度、PM 2.5、AQI、天气类型及未来 24 小时自然语言描述
 
−
|-
 
−
|'''逐日数据'''
 
−
|温度、湿度、风向、风速、气压、云量、降水量(mm/h)/降水强度、PM 2.5、AQI、天气类型、日出日落时间、生活指数
 
−
|-
 
−
|'''生活指数'''
 
−
|穿衣、洗车、感冒、紫外线
 
−
|-
 
−
|'''预警信息'''
 
−
 
−
'''(同步于中央气象台)'''
 
−
|台风、暴雨、暴雪、寒潮、大风、沙尘暴、高温、干旱、雷电、冰雹、霜冻、大雾、霾、道路结冰
 
−
|}
 
−
 
−
=== 预报时长 ===
 
−
{| class="wikitable"
 
−
|'''数据类型'''
 
−
|'''描述'''
 
−
|-
 
−
|'''分钟级降水数据'''
 
−
|未来两小时逐分钟
 
−
|-
 
−
|'''逐小时数据'''
 
−
|未来十五天逐小时
 
−
|-
 
−
|'''逐日数据'''
 
−
|未来十五天逐日
 
−
|-
 
−
|'''空气质量(AQI 和 PM2.5) '''
 
−
|未来十五天逐小时
 
−
|-
 
−
|'''生活指数'''
 
−
|未来十五天逐日
 
−
|}
 
−
 
−
注:并不表示我们会向所有类型的 API 用户提供所列全部数据。彩云API预报接口默认返回5天数据,如果需15天数据需要增加参数,可在URL后增加参数 <code>dailysteps=15&hourlysteps=360</code> 来控制返回预报时长。
 
−
 
−
== API 降水强度对照 ==
 
−
 
−
=== 降水强度对照表 ===
 
−
{| class="wikitable"
 
−
|'''降水强度值'''
 
−
|'''降水量数值 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 表示,<code>RAIN</code> 表示雨,<code>SNOW</code> 表示雪。
 
−
# API 默认返回降水强度,如果需要 API 返回降水量需要在 API URL 增加参数 <code>unit=metric:v2</code>
 
−
             如:https://api.caiyunapp.com/v2.5/your_token/121.4750,24.7695/forecast?unit=metric:v2
 
−
 
−
== AQI数据基本对照表 ==
 
−
{| class="wikitable"
 
−
|'''AQI数值'''
 
−
|'''空气质量等级'''
 
−
|-
 
−
|'''0 ~50'''
 
−
|优
 
−
|-
 
−
|'''50~100'''
 
−
|良
 
−
|-
 
−
|'''100~150'''
 
−
|轻度污染
 
−
|-
 
−
|'''150~200'''
 
−
|中度污染
 
−
|-
 
−
|'''>200'''
 
−
|重度污染
 
−
|}
 
−
 
−
== 预报数据更新频率 ==
 
−
 
−
{| class="wikitable"
 
−
|'''数据类型'''
 
−
|'''频率'''
 
−
|-
 
−
|'''实况天气数据'''
 
−
|1 分钟
 
−
|-
 
−
|'''分钟级天气预报数据'''
 
−
|1 分钟
 
−
|-
 
−
|'''小时级天气预报数据'''
 
−
|15 分钟
 
−
|-
 
−
|'''天级天气预报数据'''
 
−
|2 小时
 
−
|-
 
−
|'''PM 2.5 / AQI 数据'''
 
−
|1 小时
 
−
|}
 
−
注:采用多数据源校正数据,每个数据源的更新频率不同,小时级和天级预报更新频率为综合测算估值。
 
−
 
−
== 预报数据地域精度 ==
 
−
{| class="wikitable"
 
−
|'''数据类型'''
 
−
|'''精度'''
 
−
|-
 
−
|'''分钟级预报'''
 
−
|
 
−
|-
 
−
|'''小时级预报'''
 
−
|
 
−
|-
 
−
|'''天级预报'''
 
−
|
 
−
|-
 
−
|'''PM 2.5 / AQI 数据'''
 
−
|5 km*5 km
 
−
|}
 
−
注:采用多数据源校正数据,每个数据源的地域精度不同,小时级和天级预报地域精度为综合测算估值。
 
−
 
−
== 风力风速风向等级对照表 ==
 
−
 
−
'''风力等级对照表'''
 
−
 
−
{| class="wikitable"
 
−
|'''风力等级'''
 
−
|'''风速范围 (km/h)'''
 
−
|'''自然语言描述'''
 
−
|-
 
−
|'''0级'''
 
−
|<1
 
−
|无风
 
−
|-
 
−
|'''1级'''
 
−
|1-5
 
−
|微风徐徐
 
−
|-
 
−
|'''2级'''
 
−
|6-11
 
−
|清风
 
−
|-
 
−
|'''3级'''
 
−
|12-19
 
−
|树叶摇摆
 
−
|-
 
−
|'''4级'''
 
−
|20-28
 
−
|树枝摇动
 
−
|-
 
−
|'''5级'''
 
−
|29-38
 
−
|风力强劲
 
−
|-
 
−
|'''6级'''
 
−
|39-49
 
−
|风力强劲
 
−
|-
 
−
|'''7级'''
 
−
|50-61
 
−
|风力超强
 
−
|-
 
−
|'''8级'''
 
−
|62-74
 
−
|狂风大作
 
−
|-
 
−
|'''9级'''
 
−
|75-88
 
−
|狂风呼啸
 
−
|-
 
−
|'''10级'''
 
−
|89-102
 
−
|暴风毁树
 
−
|-
 
−
|'''11级'''
 
−
|103-117
 
−
|暴风毁树
 
−
|-
 
−
|'''12级'''
 
−
|118-133
 
−
|飓风
 
−
|-
 
−
|'''13级'''
 
−
|134-149
 
−
|台风
 
−
|-
 
−
|'''14级'''
 
−
|150-166
 
−
|强台风
 
−
|-
 
−
|'''15级'''
 
−
|167-183
 
−
|强台风
 
−
|-
 
−
|'''16级'''
 
−
|184-201
 
−
|超强台风
 
−
|-
 
−
|'''17级'''
 
−
|202-220
 
−
|超强台风
 
−
|}
 
−
 
−
'''风向对照表'''
 
−
 
−
{| class="wikitable"
 
−
|'''风向'''
 
−
|'''符号'''
 
−
|'''中心角度'''
 
−
|'''角度'''
 
−
|-
 
−
|'''北'''
 
−
|N
 
−
|0
 
−
|348.76-11.25
 
−
|-
 
−
|'''北东北'''
 
−
|NNE
 
−
|22.5
 
−
|11.26-33.75
 
−
|-
 
−
|'''东北'''
 
−
|NE
 
−
|45
 
−
|33.76-56.25
 
−
|-
 
−
|'''东东北'''
 
−
|ENE
 
−
|67.5
 
−
|56.26-78.75
 
−
|-
 
−
|'''东'''
 
−
|E
 
−
|90
 
−
|78.76-101.25
 
−
|-
 
−
|'''东东南'''
 
−
|ESE
 
−
|112.5
 
−
|101.26-123.75
 
−
|-
 
−
|'''东南'''
 
−
|SE
 
−
|135
 
−
|123.76-146.25
 
−
|-
 
−
|'''南东南'''
 
−
|SSE
 
−
|157.5
 
−
|146.26-168.75
 
−
|-
 
−
|'''南'''
 
−
|S
 
−
|180
 
−
|168.76-191.25
 
−
|-
 
−
|'''南西南'''
 
−
| SSW
 
−
|202.5
 
−
|191.26-213.75
 
−
|-
 
−
|'''西南'''
 
−
|SW
 
−
|225
 
−
|213.76-236.25 
 
−
|-
 
−
|'''西西南'''
 
−
|WSW
 
−
|247.5
 
−
|236.26-258.75
 
−
|-
 
−
|'''西'''
 
−
|W
 
−
|270
 
−
|258.76-281.25
 
−
|-
 
−
|'''西西北'''
 
−
|WNW
 
−
|295.5
 
−
|281.26-303.75
 
−
|-
 
−
|'''西北'''
 
−
|NW
 
−
|315
 
−
|303.76-326.25
 
−
|-
 
−
|'''北西北'''
 
−
|NNW
 
−
|337.5
 
−
|326.26-348.75
 
−
|}
 
−
 
−
== 天气预警 ==
 
−
 
−
获取天气预警信息,需要在API接口后增加参数:alert=true 
 
−
 
−
增加参数以后,返回的数据里会增加:alert:{} 字段 
 
−
 
−
预警信息类型取 code 字段'''前两位'''
 
−
 
−
预警类型编码对照表:
 
−
 
−
{| class="wikitable"
 
−
|'''预警级别'''
 
−
|'''级别编码'''
 
−
|-
 
−
|台风
 
−
|01
 
−
|-
 
−
|暴雨
 
−
|02
 
−
|-
 
−
|暴雪
 
−
|03
 
−
|-
 
−
|寒潮
 
−
|04
 
−
|-
 
−
|大风
 
−
|05
 
−
|-
 
−
|沙尘暴
 
−
|06
 
−
|-
 
−
|高温
 
−
|07
 
−
|-
 
−
|干旱
 
−
|08
 
−
|-
 
−
|雷电
 
−
|09
 
−
|-
 
−
|冰雹
 
−
|10
 
−
|-
 
−
|霜冻
 
−
|11
 
−
|-
 
−
|大雾
 
−
|12
 
−
|-
 
−
|霾
 
−
|13
 
−
|-
 
−
|道路结冰
 
−
|14
 
−
|-
 
−
|森林火灾
 
−
|15
 
−
|-
 
−
|雷雨大风
 
−
|16
 
−
|}
 
−
 
−
预警级别取 code 字段'''后两位'''
 
−
 
−
预警级别编码对照表:
 
−
{| class="wikitable"
 
−
|'''预警级别'''
 
−
|'''级别编码'''
 
−
|-
 
−
|'''蓝色'''
 
−
|01
 
−
|-
 
−
|'''黄色'''
 
−
|02
 
−
|-
 
−
|'''橙色'''
 
−
|03
 
−
|-
 
−
|'''红色'''
 
−
|04
 
−
|}
 
−
举例:"code": "0901”,  // 预警类型编码+预警级别编码 '''“雷电蓝色预警”'''
 
−
 
−
== 生活指数等级 ==
 
−
 
−
{| class="wikitable"
 
−
|'''生活指数名称'''
 
−
|'''等级'''
 
−
|'''等级描述'''
 
−
|-
 
−
| rowspan="5" |紫外线
 
−
|ultraviolet1
 
−
|最弱
 
−
|-
 
−
|ultraviolet2
 
−
|弱
 
−
|-
 
−
|ultraviolet3
 
−
|中等
 
−
|-
 
−
|ultraviolet4
 
−
|强
 
−
|-
 
−
|ultraviolet5
 
−
|很强
 
−
|-
 
−
| rowspan="4" |洗车
 
−
|carWashing1
 
−
|适宜
 
−
|-
 
−
|carWashing2
 
−
|较适宜
 
−
|-
 
−
|carWashing3
 
−
|较不适宜
 
−
|-
 
−
|carWashing4
 
−
|不适宜
 
−
|-
 
−
| rowspan="9" |穿衣
 
−
|dressing0
 
−
|极热
 
−
|-
 
−
|dressing1
 
−
|极热
 
−
|-
 
−
|dressing2
 
−
|很热
 
−
|-
 
−
|dressing3
 
−
|热
 
−
|-
 
−
|dressing4
 
−
|温暖
 
−
|-
 
−
|dressing5
 
−
|凉爽
 
−
|-
 
−
|dressing6
 
−
|冷
 
−
|-
 
−
|dressing7
 
−
|寒冷
 
−
|-
 
−
|dressing8
 
−
|极冷
 
−
|-
 
−
| rowspan="4" |感冒
 
−
|coldRisk1
 
−
|少发
 
−
|-
 
−
|coldRisk2
 
−
|较易发
 
−
|-
 
−
|coldRisk3
 
−
|易发
 
−
|-
 
−
|coldRisk4:
 
−
|极易发
 
−
|}
 
−
 
−
== 数据来源 ==
 
−
{| class="wikitable"
 
−
|'''数据类型'''
 
−
|'''数据源'''
 
−
|-
 
−
| rowspan="5" |天气数据
 
−
|中国气象科学数据共享服务网
 
−
|-
 
−
|台湾地区交通部中央气象局
 
−
|-
 
−
|美国大气与海洋管理局
 
−
|-
 
−
|日本气象厅
 
−
|-
 
−
|Open Weather Map
 
−
|-
 
−
|空气质量数据
 
−
|PM 25.in、环保部、WMO
 
−
|}
 
−
 
−
== 数据 API 语言种类 ==
 
−
 
−
英语、中文简体、中文繁体
 
−
 
−
== 调用次数如何计算 ==
 
−
 
−
用户发出一次 URL 请求并得到返回数据为一次调用
 
−
 
−
== 数据坐标 ==
 
−
 
−
数据所用坐标系 GCJ-02 坐标系统
 
−
 
−
== 是否支持返回历史数据 ==
 
−
 
−
API接口仅支持返回过去一天的历史数据,接口默认返回当前时刻到未来的数据。需要调用过去一天的数据,可以在 URL 后加参数 <code>begin=时间戳</code> 即可。
 
−
 
−
== 按区域代码adcode返回对应城市的数据 ==
 
−
 
−
通用接口: http://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/weather.json?adcode=110100
 
−
 
−
adcode 列表见 [[行政区域经纬度对照表]]
 
−
 
−
==格式变更==
 
 
*实况接口(/realtime.json)中各变量,在json中的位置,从result.xxxx变为result.realtime.xxxx
 
*实况接口(/realtime.json)中各变量,在json中的位置,从result.xxxx变为result.realtime.xxxx
  
Line 577: Line 25:
 
*v2.2及以下版本,逐日预报时间信息是北京时间;v2.3及以上版本,逐日预报时间信息,都带了时区,和当地时区一致
 
*v2.2及以下版本,逐日预报时间信息是北京时间;v2.3及以上版本,逐日预报时间信息,都带了时区,和当地时区一致
 
*v2.4及以上版本pres字段改为了pressure
 
*v2.4及以上版本pres字段改为了pressure
−
==特性增强==
+
 
 +
===特性增强===
 +
 
 
*air_quality(预报和实况)中, 增加美标和国标的AQI
 
*air_quality(预报和实况)中, 增加美标和国标的AQI
−
 
 
*air_quality(预报和实况)中,增加空气质量自然语言描述descripition六个等级,可能出现的字符串有七种:'缺数据','优','良','轻度污染','中度污染','重度污染','严重污染'
 
*air_quality(预报和实况)中,增加空气质量自然语言描述descripition六个等级,可能出现的字符串有七种:'缺数据','优','良','轻度污染','中度污染','重度污染','严重污染'
 
*使用了新的数据融合算法,提高了十五日内逐小时降水预报准确度;
 
*使用了新的数据融合算法,提高了十五日内逐小时降水预报准确度;
−
*新增了雨夹雪(SLEET),雷阵雨(THUNDER_SHOWER),雷阵雨并伴有冰雹(HAIL)3个天气现象;
+
 
−
{{天气现象v2.5}}
+
== 参考文档 ==
 +
 
 +
* [[彩云天气 API 的版本策略|全球点数据接口的版本策略]]
 +
* 历史版本:[[彩云天气 API/v2.3|v2.3]]
 +
* 历史版本:[[彩云天气 API/v2.4|v2.4]]
  
 
[[Category:API 产品]]
 
[[Category:API 产品]]

Latest revision as of 07:50, 26 January 2022

本文版本:彩云天气 API/v2.5,当前稳定版本版本:v2.5,历史版本:v2.2,v2.3,和 v2.4。

如果您需要

快速了解覆盖区域、涵盖变量、更新频次等信息,请参看彩云天气业务速查表

快速了解彩云天气的 API 格式信息,请参看彩云天气数据格式速查表

有问题,请参看彩云天气常见问题


接口格式说明

TAkhjf8d1nlSlspN 是个例子,请使用你的 token

变更说明

格式变更

  • 实况接口(/realtime.json)中各变量,在json中的位置,从result.xxxx变为result.realtime.xxxx
  • v2.4及以上版本, 生活指数相关的字段重组到 life_index 字段下
  • v2.4及以上版本, 空气质量相关的字段重组到 air_quality 字段下(位于realtime,hourly和daily中)
  • v2.2及以下版本,逐日预报时间信息是北京时间;v2.3及以上版本,逐日预报时间信息,都带了时区,和当地时区一致
  • v2.4及以上版本pres字段改为了pressure

特性增强

  • air_quality(预报和实况)中, 增加美标和国标的AQI
  • air_quality(预报和实况)中,增加空气质量自然语言描述descripition六个等级,可能出现的字符串有七种:'缺数据','优','良','轻度污染','中度污染','重度污染','严重污染'
  • 使用了新的数据融合算法,提高了十五日内逐小时降水预报准确度;

参考文档