Difference between revisions of "彩云天气 API/v2.5"
Chaosconst (talk | contribs) (Tag: Visual edit) |
Chaosconst (talk | contribs) (→是否支持返回历史数据) (Tag: Visual edit) |
||
| Line 561: | Line 561: | ||
== 是否支持返回历史数据 == | == 是否支持返回历史数据 == | ||
| − | API接口仅支持返回过去一天的历史数据，接口默认返回当前时刻到未来的数据。需要调用过去一天的数据，可以在 URL 后加参数 <code> | + | API接口仅支持返回过去一天的历史数据，接口默认返回当前时刻到未来的数据。需要调用过去一天的数据，可以在 URL 后加参数 <code>begin=时间戳</code> 即可。 |
== 按区域代码adcode返回对应城市的数据 == | == 按区域代码adcode返回对应城市的数据 == | ||
Revision as of 04:16, 26 February 2020
本文版本：彩云天气 API/v2.5，当前稳定版本版本：v2.5，历史版本：v2.2，v2.3，和 v2.4。
Contents
数据覆盖范围
天气数据覆盖区域
- 小时级和天级天气数据覆盖全球任意经纬度；
- 分钟级降水数据覆盖范围如下：
| 洲 | 国家 |
|---|---|
| 欧洲 | 意大利、立陶宛、马耳他、法国、斯洛伐克、挪威、白俄罗斯、冰岛、 捷克、斯洛文尼亚、德国、西班牙、乌克兰、丹麦、波兰、芬兰、瑞典、克罗地亚、俄罗斯、罗马尼亚、葡萄牙、爱沙尼亚、塞尔维亚、英国、奥地利、希腊、匈牙利 |
| 澳大利亚 | 斐济，关岛，澳大利亚，马绍尔群岛，新喀里多尼亚 |
| 亚洲 | 中国大陆及港澳台，钓鱼岛，南沙群岛，土耳其，巴林，沙特阿拉伯，印度尼西亚，伊朗，新加坡，阿曼，菲律宾，日本，印度，柬埔寨，塞浦路斯，马来西亚，越南，科威特，泰国，韩国，朝鲜 |
| 澳洲 | 澳大利亚 |
| 北美 | 加拿大，巴哈马，开曼群岛，墨西哥，巴拿马，马提尼克，古巴，美国，百慕大，波多黎各，库拉岛，瓜德罗普，尼加拉瓜 |
| 南美 | 巴西，法属圭亚那，哥伦比亚，圭亚那，巴拉圭，阿根廷 |
空气质量数据覆盖区域
中国全境。即将开通全球。
状态
状态：继承v2.4，本版本已经是稳定版本。
- 分钟级+小时级+天级预报接口
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/forecast.json - 分钟级降雨预报接口：
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/minutely.json - 小时级预报接口：
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/hourly.json - 天级预报接口：
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/daily.json - 通用点数据接口：
https://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/121.6544,25.1552/weather.json
数据类型及预报时长
数据类型
| 数据类型 | 描述 |
| 实时数据 | 温度、湿度、风向、风速、气压、云量、降水量（mm／h）／降水强度、PM 2.5、AQI、天气类型 |
| 分钟级降水数据 | 未来两小时每分钟降水强度及每半小时降水概率、未来两小时降水情况的自然语言描述 |
| 逐小时数据 | 温度、湿度、风向、风速、气压、云量、降水量（mm／h）／降水强度、PM 2.5、AQI、天气类型及未来 24 小时自然语言描述 |
| 逐日数据 | 温度、湿度、风向、风速、气压、云量、降水量（mm／h）／降水强度、PM 2.5、AQI、天气类型、日出日落时间、生活指数 |
| 生活指数 | 穿衣、洗车、感冒、紫外线 |
| 预警信息
（同步于中央气象台） |
台风、暴雨、暴雪、寒潮、大风、沙尘暴、高温、干旱、雷电、冰雹、霜冻、大雾、霾、道路结冰 |
预报时长
| 数据类型 | 描述 |
| 分钟级降水数据 | 未来两小时逐分钟 |
| 逐小时数据 | 未来十五天逐小时 |
| 逐日数据 | 未来十五天逐日 |
| 空气质量(AQI 和 PM2.5) | 未来十五天逐小时 |
| 生活指数 | 未来十五天逐日 |
注：并不表示我们会向所有类型的 API 用户提供所列全部数据。彩云API预报接口默认返回5天数据，如果需15天数据需要增加参数，可在URL后增加参数 dailysteps=15&hourlysteps=360 来控制返回预报时长。
API 降水强度对照
降水强度对照表
| 降水强度值 | 降水量数值 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
如：https://api.caiyunapp.com/v2.5/your_token/121.4750,24.7695/forecast?unit=metric:v2
AQI数据基本对照表
| AQI数值 | 空气质量等级 |
| 0 ~50 | 优 |
| 50~100 | 良 |
| 100~150 | 轻度污染 |
| 150~200 | 中度污染 |
| >200 | 重度污染 |
预报数据更新频率
| 数据类型 | 频率 |
| 实况天气数据 | 1 分钟 |
| 分钟级天气预报数据 | 1 分钟 |
| 小时级天气预报数据 | 15 分钟 |
| 天级天气预报数据 | 2 小时 |
| PM 2.5 / AQI 数据 | 1 小时 |
注：采用多数据源校正数据，每个数据源的更新频率不同，小时级和天级预报更新频率为综合测算估值。
预报数据地域精度
| 数据类型 | 精度 |
| 分钟级预报 | |
| 小时级预报 | |
| 天级预报 | |
| PM 2.5 / AQI 数据 | 5 km*5 km |
注：采用多数据源校正数据，每个数据源的地域精度不同，小时级和天级预报地域精度为综合测算估值。
风力风速风向等级对照表
风力等级对照表
| 风力等级 | 风速范围 （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 | 超强台风 |
风向对照表
| 风向 | 符号 | 中心角度 | 角度 |
| 北 | 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 字段前两位
预警类型编码对照表：
| 预警级别 | 级别编码 |
| 台风 | 01 |
| 暴雨 | 02 |
| 暴雪 | 03 |
| 寒潮 | 04 |
| 大风 | 05 |
| 沙尘暴 | 06 |
| 高温 | 07 |
| 干旱 | 08 |
| 雷电 | 09 |
| 冰雹 | 10 |
| 霜冻 | 11 |
| 大雾 | 12 |
| 霾 | 13 |
| 道路结冰 | 14 |
| 森林火灾 | 15 |
| 雷雨大风 | 16 |
预警级别取 code 字段后两位
预警级别编码对照表：
| 预警级别 | 级别编码 |
| 蓝色 | 01 |
| 黄色 | 02 |
| 橙色 | 03 |
| 红色 | 04 |
举例："code": "0901”, // 预警类型编码＋预警级别编码 “雷电蓝色预警”
生活指数等级
| 生活指数名称 | 等级 | 等级描述 |
| 紫外线 | ultraviolet1 | 最弱 |
| ultraviolet2 | 弱 | |
| ultraviolet3 | 中等 | |
| ultraviolet4 | 强 | |
| ultraviolet5 | 很强 | |
| 洗车 | carWashing1 | 适宜 |
| carWashing2 | 较适宜 | |
| carWashing3 | 较不适宜 | |
| carWashing4 | 不适宜 | |
| 穿衣 | dressing0 | 极热 |
| dressing1 | 极热 | |
| dressing2 | 很热 | |
| dressing3 | 热 | |
| dressing4 | 温暖 | |
| dressing5 | 凉爽 | |
| dressing6 | 冷 | |
| dressing7 | 寒冷 | |
| dressing8 | 极冷 | |
| 感冒 | coldRisk1 | 少发 |
| coldRisk2 | 较易发 | |
| coldRisk3 | 易发 | |
| coldRisk4: | 极易发 |
数据来源
| 数据类型 | 数据源 |
| 天气数据 | 中国气象科学数据共享服务网 |
| 台湾地区交通部中央气象局 | |
| 美国大气与海洋管理局 | |
| 日本气象厅 | |
| Open Weather Map | |
| 空气质量数据 | PM 25.in、环保部、WMO |
数据 API 语言种类
英语、中文简体、中文繁体
调用次数如何计算
用户发出一次 URL 请求并得到返回数据为一次调用
数据坐标
数据所用坐标系 GCJ－02 坐标系统
是否支持返回历史数据
API接口仅支持返回过去一天的历史数据，接口默认返回当前时刻到未来的数据。需要调用过去一天的数据，可以在 URL 后加参数 begin=时间戳 即可。
按区域代码adcode返回对应城市的数据
通用接口： http://api.caiyunapp.com/v2.5/TAkhjf8d1nlSlspN/weather.json?adcode=110100
adcode 列表见 行政区域经纬度对照表
格式变更
- 实况接口（/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六个等级，可能出现的字符串有七种:'缺数据'，'优'，'良'，'轻度污染'，'中度污染'，'重度污染'，'严重污染'
- 使用了新的数据融合算法，提高了十五日内逐小时降水预报准确度；
- 新增了雨夹雪（SLEET），雷阵雨(THUNDER_SHOWER)，雷阵雨并伴有冰雹（HAIL）3个天气现象；
天气现象 skycon v2.5
主要天气现象的优先级：降雪 > 降雨 > 雾 > 沙尘 > 浮尘 > 雾霾 > 大风 > 阴 > 多云 > 晴
| 天气现象 | 代码 | 备注 |
|---|---|---|
| 晴（白天） | 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 |
雾霾类(HAZE）天气现象（skycon）分三个等级：
| 轻度雾霾 | 中度雾霾 | 重度雾霾 |
| AQI > 100 | AQI > 150 | AQI > 200 |
空气污染的自然语言描述air_quality: description字段，根据AQI有六个等级划分：
| 缺数据 missing | 优 good | 良 satisfactory | 轻度污染 moderate | 中度污染 unhealthy | 重度污染 very poor | 严重污染 hazardous |
| 无测站国家和位置 | 0~50 | 51~100 | 101~150 | 151~200 | 201~300 | >300 |
