# 天气服务接口2020版

**强调**：2020版接口的维护将于2021.7.1日截止。自2021.7.1日始，所有首次访问天气服务2020版接口的ip请求将被拒绝。

## 统一说明

#### POST接口请求方式说明

凡是Method为POST方式的接口，支持两种参数请求方式。
这两种请求方式的Header参数（Content-Type）值不同。

##### 方式一

该类接口以接口以http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/**unifier**开头 

HTTP请求的Header需设置参数如下：

```
Content-Type=application/x-www-form-urlencoded
```

body体传参为字符串，格式为jsonString={"key":"value"}，其中jsonString为固定字符，后面为Json格式字符串参数。

##### 方式二

该类接口以接口以http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/**unifierJson**开头 

HTTP请求的Header需设置参数如下：

```
Content-Type=application/json
```

body体传参为Json格式字符串，例如：{"key":"value"}。

#### 统一参数说明

**所有查询指定城市天气数据的接口，都需要在参数中指明是哪一个城市。**
目前天气服务支持传入cityCode、projectId、cityName三个参数(之一)来定位城市（说明见下表）。


| 参数key    | 说明                         |  优先级      | 举例     |
| --------- | ---------------------------- | ---------- | -------- |
| cityCode  | 合法数据字典城市编码，6位数字字符串 | 最高       | 110101    |
| projectId | 合法数据字典项目ID，12位字符串    | 高         | Pj1101010001 |
| cityName  | 城市中文名，字符串              | 低         | 北京        |


## 接口说明
**注意：** 

1. 凡是入参涉及到传城市信息的，以下接口说明中均已cityName作为参数，实际接口调用时，可根据*统一参数说明*，使用cityCode或者projectId代替cityName参数作为入参。
2. 凡未特别注释，示例中的接口示入参均为必需项。

### 实时数据查询

简介：接口返回指定城市的最新天气数据信息，数据分为两大类A和B。
A包括以下信息：天气现象文字(晴、多云...)、天气现象编码、温度、体感温度、气压、相对湿度、能见度、风速、风向文字、风向角度、风力等级、云量（范围0~100，天空被云覆盖的百分比）。
B包括以下信息：空气质量文字(优、良...)、首要污染物、PM2.5、PM10、so2、no2、co、o3。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/NowWeatherQuery 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海",
    "dataType":"枚举值字符串：weather,只返回A类数据; air,只返回B类数据; all, 返回A和B类数据"
}
```

返回结果：

正确结果JSON示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "code": "天气现象编码，示例：8", 
            "o3": "43",
            "visibility": "能见度示例：9.3",
            "pm10": "50",
            "wind_direction": "风向文字，示例：北",
            "pressure": "气压值，示例：1017", 
            "clouds": "云量，示例：90", 
            "co": "0.532",
            "feels_like": "体感温度，示例：17",
            "quality": "空气质量文字，示例：优",
            "no2": "45",
            "pm25": "30",
            "so2": "7",
            "last_update": "2021-01-21 15:50:00",
            "wind_scale": "风力等级，示例：0",
            "aqi": "50",
            "primary_pollutant": "首要污染物，示例：pm25，若无则为空串", 
            "temperature": "17",
            "humidity": "相对湿度，示例：82", 
            "wind_direction_degree": "风向角，示例：0", 
            "wind_speed": "风速，示例：0.72",
            "text": "天气现象文字，示例：阴"
        }
    ]
}
```

错误结果JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 24小时预报数据查询

简介：获取未来24小时的小时天气信息。此“未来24小时”包含当前小时整点，以及未来的23个小时的23个整点，共24条天气数据。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/Hour24Forecast 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海"
}
```

返回结果：

正确结果JSON示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "location": {
                "id": "WX4FBXXFKE4F",
                "name": "北京",
                "country": "CN",
                "path": "北京,北京,中国",
                "timezone": "Asia/Shanghai",
                "timezone_offset": "+08:00"
            },
            "hourly": [
                {
                    "time": "时间，str，示例：2021-01-21 17:00:00",
                    "text": "天气现象文字，str，示例：晴",
                    "code": "天气现象编码，str，示例：0",
                    "temperature": "温度，str，示例4", 
                    "humidity": "相对湿度，str，示例：41",
                    "wind_direction": "风向文字，str，南",
                    "wind_speed": "风速，str，示例：10"
                },
                {
                    "time": "2021-01-21 18:00:00",
                    "text": "晴",
                    "code": "1",
                    "temperature": "1",
                    "humidity": "42",
                    "wind_direction": "西南",
                    "wind_speed": "15"
                },
                {
                    "time": "2021-01-22 16:00:00",
                    "text": "晴",
                    "code": "0",
                    "temperature": "4",
                    "humidity": "62",
                    "wind_direction": "南",
                    "wind_speed": "10"
                }
            ]
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 14天日预报

简介：获取今天及未来共14天的天气预报信息。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/DayForecast 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海",
    "startDay":"非必需参数，未来14天中，某一段时间的开始日（包含），示例：2021-01-21",
    "endDay":"非必需参数，未来14天中，某一段时间的结束日（不包含）2021-01-29，示例：2021-01-21"
}
```

结果示例

正确结果JSON示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "date": "2021-01-21",
            "maxTemperature": "日最高温，Str，示例：6",
            "rainfall": "降雨量，str， 示例：0.0",
            "codeDay": "白日气象编码，示例：0",
            "windDirectionDegree": "风向角，str，示例：225", 
            "textDay": "白日气象文字，str，示例：晴",
            "codeNight": "白日气象编码，str，示例：1",
            "minTemperature": "日最低温，str，示例：-5",
            "textNight": "夜晚气象文字，str，示例：晴",
            "humidity": "相对湿度，str，示例：49",
            "windDirection": "风向文字，str，示例：西南",
            "windSpeed": "风速,str，示例：8.4",
            "windScale": "风力等级,str，示例：2"
        },
        {
            "date": "2021-01-28",
            "maxTemperature": "4",
            "rainfall": "0.0",
            "codeDay": "0",
            "windDirectionDegree": "225",
            "textDay": "晴",
            "codeNight": "1",
            "minTemperature": "-5",
            "textNight": "晴",
            "humidity": "44",
            "windDirection": "西南",
            "windSpeed": "8.4",
            "windScale": "2"
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 小时级历史数据
简介：根据城市信息及开始时间、结束时间，获取城市小时天气历史数据。

注意：
1. 该接口能够查询到的最新的小时数据会至少比当前时间滞后半小时，例如结束时间为当天10:10，则接口只能查到最新小时数据为9:00的小时数据；若结束时间为当天10:35则能查到的最新小时数据为10:00的数据；
2. 目前只支持全国约1200个城市区域；
3. 改历史历史数据最远可追溯至17年，有些城市最远开始于2020年7月；
4. 接口最大支持查询7天的数据。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/HourHistoryData 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海",
    "minResponse":"是否只返回部分指标数据，boolean类型",
    "startTime":"开始时间（包含），str，示例：2021-01-01 00:00:00",
    "endTime":"结束时间（不包含），str，示例：2021-01-03 00:00:00"
}
```

注：参数minResponse，默认值true,表示返回所有气象指标数据；false，只返回温度、相对湿度、风速、空气质量文字、天气现象文字六项数据

返回结果：

正确JSON，小时历史数据示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "code": "天气现象编码，str，示例：1",
            "visibility": "能见度，str，示例：15.3",
            "o3": "7",
            "pm10": "60",
            "pressure": "气压值，str，示例：1023",
            "clouds": "云量，str，示例：0",
            "co": "0.608",
            "quality": "空气质量文字，str，示例：良", 
            "feelsLike": "体感温度，str，示例：-6",
            "windDirectionDegree": "风向角，str，示例：0",
            "no2": "52",
            "hourTime": "2021-01-01 00:00:00",
            "pm25": "22",
            "so2": "3",
            "temperature": "温度，str，示例：-7",
            "aqi": "气象指标指数，str，示例：55",
            "humidity": "相对湿度，str，示例：37",
            "primaryPollutant": "首要污染物，str，示例：PM10",
            "text": "天气现象文字，str，示例：晴",
            "windDirection": "风向，str，示例：北",
            "windSpeed": "风速，str，示例：2.16",
            "windScale": "风力等级，str，示例：1"
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 日级历史数据

简介：根据城市信息及开始时间、结束时间，获取城市日历史数据。该接口最大支持一年的数据查询。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/dataHistory 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海",
    "startTime":"开始时间（包含），str，示例：2021-01-01 00:00:00",
    "endTime":"结束时间（不包含），str，示例：2021-01-03 00:00:00"
}
```

返回结果：

正确JSON

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "rainfall": "降雨量，str，示例：0.0",
            "codeDay": "白日气象编码，str，示例：0",
            "dayTime": "2021-01-01 00:00:00",
            "windDirectionDegree": "风向角，str，示例：225",
            "high": "日最高温，str，示例：1",
            "textDay": "白日天气现象文字，str，示例：晴",
            "codeNight": "夜晚气象编码，str，示例：1",
            "low": "日最低温，str，示例：-11",
            "textNight": "晚间天气现象文字，str，示例：晴",
            "humidity": "相对湿度，str，示例：24",
            "windDirection": "降雨量，str，示例：西南",
            "windSpeed": "风速，str，示例：8.4",
            "windScale": "风力等级，str，示例：2"
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 日统计数据

简介：获取以下气象指标【温度、相对湿度、风速、气压、能见度】的日最大/小值和日均值数据。

注意：有小时天气历史数据的城市才有日统计数据记录，该记录数据在每日凌晨将昨日小时气象数据统计得出；该接口最大支持一年的数据查询。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/DayStaticData 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海",
    "startTime":"开始时间（包含），str，示例：2021-01-01 00:00:00",
    "endTime":"结束时间（不包含），str，示例：2021-01-03 00:00:00",
    "dataType":"返回数据类型，字符串枚举值，示例：All"
}
```

注：参数dataType三个可选枚举值，默认为Max，表示获取最大最小值；Avg，表示获取平均值；All，表示获取最大最小值和平均值

返回结果：

正确JSON

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "maxVisibility": 27.0,
            "avgPressure": 1021.5,
            "maxTemp": 1.0, 
            "avgHumidity": 37.0,
            "avgTemp": -5.4, 
            "minHumidity": 17.0,
            "dayTime": "2021-01-01 00:00:00",
            "minTemp": -11.0,
            "maxWindSpeed": 8.0,
            "avgWindSpeed": 4.0,
            "minVisibility": 11.0,
            "avgVisibility": 17.0,
            "minPressure": 1020.0,
            "maxPressure": 1024.0,
            "minWindSpeed": 1.0,
            "maxHumidity": 59.0
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 灾害预警

简介：取指定城市的指定时间区间的灾害预警信息。

注：

1.同一种灾害预警如果级别不同，则结果可能返回多条结果数据；
2.灾害数据更新频率为15分钟/次；
3.所查询的时间跨度最大支持一年。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/DisasterWarningQuery 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海",
    "startTime":"开始时间（包含），str，示例：2021-01-01 00:00:00",
    "endTime":"结束时间（不包含），str，示例：2021-01-03 00:00:00",
    "type":"非必需，灾害类型枚举，str,示例：道路结冰",
    "level":"非必需，预警级别枚举值，str，示例：黄色"
}
```

正确JSON，日灾害预警示例

注：
1. 同一种灾害预警如果级别不同，则结果可能返回多条结果数据；
2. 灾害数据更新频率为15分钟/次；
3. 所查询的时间跨度最大支持一年。

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "insertTime": "2021-01-19 06:16:06",
            "path": "北京,北京,中国",
            "level": "黄色",
            "pubTime": "2021-01-19 06:08:39",
            "name": "北京",
            "description": "市气象台2021年1月19日06时00分发布道路结冰黄色预警信号：预计当前至20日中午将出现道路结冰现象，请注意防范。",
            "cityId": "WX4FBXXFKE4F",
            "title": "北京市气象台2021年1月19日06时00分发布道路结冰黄色预警信号",
            "type": "道路结冰"
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```


### 日出日落时间计算

简介：根据坐标或者数据字典城市编码或者包含数据字典城市编码的项目数据字典ID计算日出日落时间。

提示：入参支持数据字典城市名称，数据字典城市编码，符合数据字典命名规范的项目ID，经纬度值，四项参数不能全部为空，使用优先级：经纬度值> 数据字典城市编码 > 项目ID > 城市名称。该接口支持最长一年的数据计算。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/SunRiseAndSet 

请求参数： 

```json
{
    "cityName":"城市名称，比如：上海",
    "longitude":116.4,
    "latitude":39.9,
    "startDay":"开始日（含），str，示例：2021-02-14",
    "endDay":"结束日（不含），str，示例：2021-02-15"
}
```

返回结果：

正确JSON示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "sunSet": "日落时间，示例：2021-02-14 17:50:00",
            "sunRise": "日出时间，示例：2021-02-14 07:06:00"
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 字典数据-天气现象编码与文字

简介：取天气现象编码及文字描述信息。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/DicWeatherCodeName 

请求参数： 

```json
{}
```

返回结果：

正确JSON示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        {
            "0": "晴",
            "1": "晴",
            "2": "晴",
            "3": "晴",
            "4": "多云",
            "5": "晴间多云",
            "6": "晴间多云",
            "7": "大部多云",
            "8": "大部多云"
        }
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 字典数据-灾害预警类型

简介：取天气现象编码及文字描述信息。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/DicDisasterType 

请求参数： 

```json
{}
```

返回结果：

正确JSON示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        "台风",
        "暴雨",
        "暴雪",
        "寒潮",
        "大风",
        "沙尘暴",
        "高温",
        "干旱",
        "雷电",
        "冰雹",
        "霜冻",
        "大雾",
        "道路结冰",
        "雷雨大风"
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 字典数据-灾害预警级别

简介：取天气现象编码及文字描述信息。

Method：POST 

Header参数：Content-Type=application/json 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/unifierJson/DicDisasterLevel 

请求参数： 

```json
{}
```

返回结果：

正确JSON示例

```json
{
    "version": "1.0",
    "result": "success",
    "reason": null,
    "content": [
        "白色",
        "蓝色",
        "黄色",
        "橙色",
        "红色"
    ]
}
```

错误JSON示例

```json
{
    "version": "1.0",
    "result": "failure",
    "reason": "错误信息",
    "content": []
}
```

### 天气现象图标下载

简介：获取天气现象编码对应的图标图片数据。

Method：GET 

URL：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/download/icon/weatherCode-theme-size 

URL说明：
1. 以HTTP-GET访问接口，接口参数在URL最后面；
2. 参数格式为weatherCode-theme-size。其中weatherCode为天气现象编码，必需；theme为图片主题，非必需，支持dark、light、classic三种；size为图标大小，非必需，支持big、small两种。
3. 接口请求示例：http://127.0.0.1:8888/EMS_Weather/Spring/MVC/entrance/download/icon/5-classic-big

返回结果：数据流