# 天气服务介绍

## 简介

本天气服务通过定时访问第三方天气服务商的服务,将得到的指定城市的天气数据存入本地,并向外提供了可获取天气数据的HTTP接口,供各产品线业务系统查询使用。

## 支持数据

本服务支持以下气象指标和服务数据的查询

#### 气象指标全集

| 指标名        | 英文标识       | 单位及其他说明              |
| ------------ | ------------ | ------------------------- |
| 气温实时值     | temperature  | c,摄氏度                  |
| 体感温度       | feelsLike   | c,摄氏度                   | 
| 日最高温度     | temperatureHigh   | c,摄氏度              | 
| 日最低温度     | temperatureLow   | c,摄氏度              | 
| 统计温度最大值     | temperatureMax   | c,摄氏度              | 
| 统计温度最小值     | temperatureMin   | c,摄氏度              | 
| 统计温度均值     | temperatureAvg   | c,摄氏度              | 
| 相对湿度       | humidity     | 数值范围0~100,是百分比值 |
| 统计相对湿度最大值     | humidityMax     | 数值范围0~100,是百分比值 |
| 统计相对湿度最小值     | humidityMin     | 数值范围0~100,是百分比值 | 
| 统计相对湿度均值       | humidityAvg     | 数值范围0~100,是百分比值 |
| 气压          | pressure     | 单位mbar,百帕              |
| 统计气压最大值   | pressureMax     | 单位mbar,百帕              |
| 统计气压最小值   | pressureMin     | 单位mbar,百帕              |
| 统计气压均值     | pressureAvg     | 单位mbar,百帕              |
| 能见度        | visibility   | km,千米                    |
| 统计能见度最大值     | visibilityMax   | km,千米                    |
| 统计能见度最小值     | visibilityMin   | km,千米                    |
| 统计能见度均值       | visibilityAvg   | km,千米                    |
| 风速          | windSpeed   | km/h,千米每小时             |
| 统计风速最大值       | windSpeedMax   | km/h,千米每小时             |
| 统计风速最小值       | windSpeedMin   | km/h,千米每小时             |
| 统计风速均值         | windSpeedAvg   | km/h,千米每小时             |
| 风力等级       | windScale   | 数值,>=0,无单位            |
| 风向文字       | windDirection   | 无单位,描述信息,如:西南          | 
| 风向角度       | windDirectionDegree   | 角度数值,0~360,0为正北,90为正东,180为正南 |
| 降水量         | rainfall    | mm,毫米                     | 
| 首要污染物      | primaryPollutant   | 无单位,字符描述            | 
| 气象文字描述    | text      | 阴、晴、雨、雪...,无单位        | 
| 白日气象文字描述    | textDay      | 阴、晴、雨、雪...,无单位        | 
| 夜晚气象文字描述    | textNight      | 阴、晴、雨、雪...,无单位        | 
| 气象编码       | code      | 无单位                        | 
| 白日气象编码    | codeDay      | 无单位                  | 
| 夜晚气象编码    | codeNight      | 无单位                  | 
| 空气质量文字    | quality      | 优、良、轻度污染...,无单位     | 
| 云量           | clouds      | 数值,0~100,无单位          | 
| pm25          | pm25       | 1小时平均值。单位:μg/m³        |
| pm10          | pm10       | 1小时平均值。单位:μg/m³        |
| so2           | so2        | 1小时平均值。单位:μg/m³        |
| no2           | no2        | 1小时平均值。单位:μg/m³        |
| co           | co          | 1小时平均值。单位:μg/m³        |
| o3           | o3          | 1小时平均值。单位:μg/m³        |
| aqi          | aqi         | 数值,无单位                   |


#### 日出日落信息

| 指标名        | 英文标识       | 单位及其他说明              |
| ------------ | ------------ | ------------------------- |
| 日出时间          | sunRise        | 时间戳                   |
| 日落时间          | sunSet         | 时间戳                   | 


#### 灾害预警信息

| 指标名        | 英文标识       | 单位及其他说明              |
| ------------ | ------------ | ------------------------- |
| 灾害预警级别    | level  |                   |
| 预警发布时间    | pubTime   |  时间戳           | 
| 预警描述信息    | description   |              | 
| 灾害预警标题   | title   |             | 
| 灾害预警类型   | type   |             | 


## 枚举值

#### 空气质量类别

```json
["优", "良", "轻度污染", "中度污染", "重度污染", "严重污染"]
```

#### 气象编码与气象文字描述

```json
{
    "0": "晴",
    "1": "晴",
    "2": "晴",
    "3": "晴",
    "4": "多云",
    "5": "晴间多云",
    "6": "晴间多云",
    "7": "大部多云",
    "8": "大部多云",
    "9": "阴",
    "10": "阵雨",
    "11": "雷阵雨",
    "12": "雷阵雨伴有冰雹",
    "13": "小雨",
    "14": "中雨",
    "15": "大雨",
    "16": "暴雨",
    "17": "大暴雨",
    "18": "特大暴雨",
    "19": "冻雨",
    "20": "雨夹雪",
    "21": "阵雪",
    "22": "小雪",
    "23": "中雪",
    "24": "大雪",
    "25": "暴雪",
    "26": "浮尘",
    "27": "扬沙",
    "28": "沙尘暴",
    "29": "强沙尘暴",
    "30": "雾",
    "31": "霾",
    "32": "风",
    "33": "大风",
    "34": "飓风",
    "35": "热带风暴",
    "36": "龙卷风",
    "37": "冷",
    "38": "热",
    "99": "未知"
}
```

#### 灾害预警类型

```json
["台风", "暴雨", "暴雪", "寒潮", "大风", "沙尘暴", "高温", "干旱", "雷电", "冰雹", "霜冻", "大雾", "道路结冰", "雷雨大风"]
```

#### 灾害级别

```json
["白色", "蓝色", "黄色", "橙色", "红色"]
```


## 气象数据类型
按时间和功能划分,支持以下类型数据查询: 

| 类型名        | 类型码       | 
| ------------ | ------------ | 
| 实时数据     | present  | 
| 小时预报数据   | predictHour | 
| 日预报数据    | predictDay  | 
| 小时历史数据   | historyHour | 
| 日历史数据    | historyDay  |
| 日统计数据    | statisticDay  |
| 灾害预警数据    | disaster  |
| 日出日落数据    | sunRiseSet  |

* **实时数据** 

获取某城市当前气象数据信息。支持的气象指标有:气温实时值, 体感温度, 相对湿度, 气压, 能见度, 风速, 风力等级, 风向文字, 风向角度, 首要污染物, 气象文字描述, 气象编码, 空气质量文字, 云量, pm25, pm10, so2, no2, co, o3, aqi。


* **小时预报数据** 

可获取包含当前小时及未来23小时的预报数据。支持气象指标:气温实时值, 相对湿度, 风速, 风向文字, 气象文字描述, 气象编码。


* **日预报数据** 

可获取包含当天及未来14日的预报数据。支持气象指标:日最高温度, 日最低温度, 相对湿度, 风速, 风力等级, 风向文字, 风向角度, 降水量, 白日气象文字描述, 夜晚气象文字描述, 白日气象编码, 夜晚气象编码。


* **小时历史数据** 

最早可获取到2017年1月1日数据。支持气象指标: 气温实时值, 相对湿度, 气象文字, 气压, 能见度, 风速, 风力等级, 风向文字, 风向角度,(2020.7.1之前不支持以下类型)体感温度, 首要污染物, 气象文字描述, 气象编码, 空气质量文字, 云量, pm25, pm10, so2, no2, co, o3, aqi;


* **日历史数据** 

最早可获取到2017年1月1日数据。支持气象指标: 日最高温度, 日最低温度, 相对湿度, 白日气象文字描述, 夜晚气象文字描述, 风速, 风向角, (2020.7.1之前不支持以下类型)风力等级, 风向文字, 白日气象编码, 夜晚气象编码, 降雨量。


* **日统计数据** 

凡具有小时历史数据的城市,均有日统计数据。最早可获取到2017年1月1日数据。 支持气象指标: [温度, 相对湿度, 风速, 气压, 能见度] 的日最大值、最小值、均值。


* **灾害预警数据** 

支持以下灾害类型的预警信息查询: ["台风", "暴雨", "暴雪", "寒潮", "大风", "沙尘暴", "高温", "干旱", "雷电", "冰雹", "霜冻", "大雾", "道路结冰", "雷雨大风"]


* **日出日落数据** 

支持根据经纬度坐标,或者数据字典城市编码,或者包含数据字典城市编码的项目数据字典ID,来计算日出时间和日落时间。


* **天气现象图标** 

支持天气现象(即阴晴雨雪...)对应图标下载。


## 数据来源

本天气服务中所有天气相关数据来源于服务提供商——心知天气(https://www.seniverse.com/)。

## 支持城市
* 天气实况数据,日历史天气数据,预报数据和灾害预警数据支持3000+个城市地区(几乎涵盖全国所有地区)
* 小时历史数据和统计数据支持约1200个城市地区(几乎涵盖全国所有一、二、三、四、五线城市的市级,部分涵盖区级)

## 产品更新记录

* 2020年8月15日,对整个底层代码逻辑行了重构,重新设计了表结构及存储方式,优化了定时任务,升级了数据字典城市编码与第三方城市码的匹配算法。新增若干接口,支持约1200个城市的小时天气数据查询和日天气数据统计查询,支持3000多个城市区域的日天气数据查询,支持日出日落数据数据查询,支持天气气象图标下载;
* 2019年6月,新增若干接口,支持约300个城市小时天气数据查询和日数据统计查询,约1000个城市地区的日天气数据查询,并增加了灾害预警数据查询、月级别统计数据的计算;
* 2018年10月,健全了项目的说明文档,接口文档,并对项目的定时任务逻辑进行了简单重构;
* 2017年4月,作为一个定制项目被创建,提供了4个HTTP服务接口,支持约100个城市的日天气数据查询;