# 产品介绍 本天气服务系统通过定时访问第三方天气服务商的服务，将得到的指定城市的天气数据存入本地，并向外提供了可获取天气数据的HTTP接口，供各产品线业务系统调用。 ## 1 产品功能与服务 ### 1.1 数据来源 本天气服务中所有天气相关数据来源于服务提供商——心知天气（https://www.seniverse.com/）。 ### 1.2 产品更新简史 1. 2017年初，作为一个定制项目被创建，只提供了4个HTTP服务接口，支持不到100个城市的日天气数据查询； 2. 2018年下旬，健全了项目的说明文档，接口文档，并对项目的定时任务逻辑进行了简单重构； 3. 2019年初至2020年初，HTTP服务接口数量增加至18个，支持约300个城市小时天气数据查询和日数据统计查询，约1000个城市地区的日天气数据查询，并增加了灾害预警数据查询、月级别统计数据的计算； 4. 2020年5月-8月，对整个系统进行了代码重构，重新设计了表结构及存储方式，对天气源数据获取的定时任务进行了优化，升级了第三方城市编码与数据字典城市编码的匹配算法，HTTP服务接口数量增加至25个，支持约1200个城市的小时天气数据查询和日天气数据统计查询，支持3000多个城市区域的日天气数据查询，支持日出日落数据数据查询，支持天气气象图标下载； ## 2 服务及数据支持说明 ### 2.1 数据类型说明 按时间划分，支持以下类型数据 #### 24小时预报 温度、相对湿度、能见度、气象文字、气象代码、风向、风速 #### 14日天气预报 日最高/低温、相对湿度、白天气象文字/代码、夜晚气象文字/代码、风向文字、风向角、风速、风力等级、降水量 #### 小时级别历史数据 注：最早支持到2017年1月1日。 支持数据类型如下： 温度、相对湿度、气象文字、气压、能见度、风向文字、风速、风向角风速、风力等级、（2020.7.1之前不支持以下类型）体感温度、空气质量、云量、pm25、pm10、so2、no2、co、o3 #### 日历史数据 注：最早支持到2017年1月1日。 支持数据类型如下： 日最高温、日最低温、相对湿度、白日气象文字、夜晚气象文字、风向文字、风速、风向角风速、风力等级、（2020.7.1之前不支持以下类型）白天夜晚\气象代码、降雨量 按其他维度划分 #### 统计数据 支持以下数据类型[温度, 相对湿度, 风速, 气压, 能见度]的日最大/小值，日均值查询 #### 其他功能服务数据 * 支持以下预警类型的预警信息查询，预警类型：[台风, 暴雨, 暴雪, 寒潮, 大风, 沙尘暴, 高温, 干旱, 雷电, 冰雹, 霜冻, 大雾, 道路结冰, 雷雨大风]； * 支持基于经纬度坐标（或数据字典城市编码）的日出日落数据查询； * 支持天气现象（即阴晴雨雪...）图标下载。 ### 2.2 数据单位说明 本天气服务HTTP接口返回数据指标的默认单位说明如下： * 温度（体感温度），c，摄氏度 * 相对湿度，数值在0~100之间，是百分比数值 * 气压，mbar，百帕 * 能见度，km，千米 * 风向角度，数值在0~360，0为正北，90为正东，180为正南 * 风速，km/h，千米每小时 * 风力等级，数值>=0，无单位，数值越大风力越大 * 降水量，mm，毫米 * aqi，数值，无单位 * pm25，1小时平均值。单位：μg/m³ * pm10，1小时平均值。单位：μg/m³ * so2，1小时平均值。单位：μg/m³ * no2，1小时平均值。单位：μg/m³ * co，1小时平均值。单位：mg/m³ * o3，1小时平均值。单位：mg/m³ ### 2.3 枚举字典值说明 #### 空气质量类别 ["优"、"良"、"轻度污染"、"中度污染"、"重度污染"、"严重污染"] #### 天气现象编码与文字描述 { "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": "未知" } #### 灾害预警类型 ["台风", "暴雨", "暴雪", "寒潮", "大风", "沙尘暴", "高温", "干旱", "雷电", "冰雹", "霜冻", "大雾", "道路结冰", "雷雨大风"] #### 灾害级别 ["白色", "蓝色", "黄色", "橙色", "红色"] ### 2.4 支持城市 * 天气实况数据，日历史天气数据，预报数据和灾害预警数据支持3000+个城市地区（几乎涵盖全国所有地区） * 小时历史数据和统计数据支持约1200个城市地区（涵盖全国所有一、二、三、四、五线城市的市级，部分涵盖区级） ## 3 HTTP接口说明 目前天气服务只向外提供了HTTP接口形式的服务，其中POST方法的接口支持两种参数请求方式。 ### 3.1 POST接口请求方式说明 根据Header参数Content-Type的值不同，提供HTTP参数请求两种方式。 #### 方式一 该类接口以接口以/EMS_Weather/Spring/MVC/entrance/**unifier**开头 HTTP请求的Header需设置参数如下： Content-Type=application/x-www-form-urlencoded body体传参为字符串，格式为jsonString={"key":"value"}，其中jsonString为固定字符，后面为Json格式字符串参数。 #### 方式二 该类接口以接口以/EMS_Weather/Spring/MVC/entrance/**unifierJson**开头 HTTP请求的Header需设置参数如下： Content-Type=application/json body体内容为Json格式字符串，例如：{"key":"value"}。 ### 3.2 接口统一参数说明 所有查询指定城市天气数据的接口，都需要在参数中指明是哪一个城市。目前天气服务支持传入以下三个参数（至少有一个），来定位城市。三个参数的key及说明如下： * cityCode，合法数据字典城市编码，6位数字字符串，优先级最高，举例： 110101 * projectId，合法数据字典项目ID，12位字符串，优先级高，举例：Pj1101010001 * cityName，城市中文名，字符串，优先级低，举例：北京 ### 3.3 通用接口 注：以下对于接口说明，均已3.1所述的方式二进行举例。凡是涉及到到传指定城市信息参数的地方，示例请求参数均已cityName作为参数，实际接口调用时，可根据3.2中说明使用cityCode或者projectId代替cityName参数作为入参。 #### 天气实况数据 * 简介：接口返回指定城市的最新天气数据信息，数据分为两大类A和B。A包括以下信息：天气现象文字(晴、多云...)、天气现象编码、温度、体感温度、气压、相对湿度、能见度、风速、风向文字、风向角度、风力等级、云量（范围0~100，天空被云覆盖的百分比）。 B包括以下信息：空气质量文字(优、良...)、首要污染物、PM2.5、PM10、so2、no2、co、o3。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/NowWeatherQuery ##### body体参数： { "cityName":"上海", "dataType":"all" } 参数说明：dataType的值是以下三个枚举值字符串中的一个，weather，只获取A类数据；air，只获B类数据；all，获取A类和B类数据。 ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "code": "9", // 天气现象编码，str "o3": "43", "visibility": "9.3", // 能见度，str "pm10": "50", "wind_direction": "北", // 风向文字，str "pressure": "1017", // 气压值，str "clouds": "90", // 云量，str "co": "0.532", "feels_like": "17", // 体感温度，str "quality": "优", // 空气质量文字，str "no2": "45", "pm25": "30", "so2": "7", "last_update": "2021-01-21 15:50:00", "wind_scale": "0", // 风力等级，str "aqi": "50", "primary_pollutant": "", // 首要污染物，str，若无则为空串 "temperature": "17", // 温度，str "humidity": "82", // 相对湿度，str "wind_direction_degree": "0", // 风向角，str "wind_speed": "0.72", // 风速，str "text": "阴" // 天气现象文字，str } ] } #### 24小时预报 * 简介：获取未来24小时的小时天气信息。此“未来24小时”包含当前小时整点，以及未来的23个小时的23个整点，共24条天气数据。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/Hour24Forecast ##### body体参数： { "cityName":"北京" } ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "location": {// 匹配到的城市信息 "id": "WX4FBXXFKE4F", // 城市编码 "name": "北京", "country": "CN", "path": "北京,北京,中国", // 隶属区域 "timezone": "Asia/Shanghai", "timezone_offset": "+08:00" }, "hourly": [ // 24条小时预报数据 { "time": "2021-01-21 17:00:00", "text": "晴", // 天气现象文字，str "code": "0", // 天气现象编码，str "temperature": "4", // 温度，str "humidity": "41", // 相对湿度，str "wind_direction": "西南", // 风向文字，str "wind_speed": "10" // 风速，str }, { "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" } ] } ] } #### 14天日预报 * 简介：获取今天及未来共14天的天气预报信息。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/DayForecast ##### body体参数： { "cityName":"北京", "startDay":"2021-01-21", // 非必需参数，未来14天中，某一段时间的开始日（包含） "endDay":"2021-01-29" // 非必需参数，未来14天中，某一段时间的结束日（不包含） } ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "date": "2021-01-21", "maxTemperature": "6", // 日最高温 "rainfall": "0.0", // 降雨量 "codeDay": "0", // 白日气象编码 "windDirectionDegree": "225", // 风向角 "textDay": "晴", // 白日气象文字 "codeNight": "1", // 夜晚气象编码 "minTemperature": "-5", // 日最低温 "textNight": "晴", // 夜晚气象文字 "humidity": "49", // 相对湿度 "windDirection": "西南", // 风向文字 "windSpeed": "8.4", // 风速 "windScale": "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" } ] } #### 小时级历史数据 * 简介：根据城市信息及开始时间、结束时间，获取城市小时天气历史数据。 注意： 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：/EMS_Weather/Spring/MVC/entrance/unifierJson/HourHistoryData ##### body体参数： { "startTime":"2021-01-01 00:00:00", // 开始时间（包含） "endTime":"2021-01-02 00:00:00", // 结束时间（不包含） "cityName":"北京市", "minResponse":false // 是否只返回部分指标数据，boolean } 注：参数minResponse，默认值true,表示返回所有气象指标数据；false，只返回温度、相对湿度、风速、空气质量文字、天气现象文字六项数据 ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "code": "1", // 天气现象编码 "visibility": "15.3", // 能见度 "o3": "7", "pm10": "60", "pressure": "1023", // 气压值 "clouds": "0", // 云量 "co": "0.608", "quality": "良", // 空气质量文字 "feelsLike": "-6", // 体感温度 "windDirectionDegree": "0", // 风向角 "no2": "52", "hourTime": "2021-01-01 00:00:00", "pm25": "22", "so2": "3", "temperature": "-7", // 温度 "aqi": "55", // 气象指标指数 "humidity": "37", // 相对湿度 "primaryPollutant": "PM10", // 首要污染物 "text": "晴", // 天气现象文字 "windDirection": "北", // 风向 "windSpeed": "2.16", // 风速 "windScale": "1" // 风力等级 },... ] } #### 日级历史数据 * 简介：根据城市信息及开始时间、结束时间，获取城市日历史数据。该接口最大支持一年的数据查询。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/DayHistoryData ##### body体参数： { "startTime":"2021-01-01 00:00:00", // 开始时间（包含） "endTime":"2021-01-02 00:00:00", // 结束时间（不包含） "cityName":"北京市" } ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "rainfall": "0.0", // 降雨量 "codeDay": "0", // 白日气象编码 "dayTime": "2021-01-01 00:00:00", "windDirectionDegree": "225", // 风向角 "high": "1", // 日最高温 "textDay": "晴", // 白日天气现象文字 "codeNight": "1", // 夜晚气象编码 "low": "-11", // 日最低温 "textNight": "晴", // 晚间天气现象文字 "humidity": "24", // 相对湿度 "windDirection": "西南", // 风向描述 "windSpeed": "8.4", // 风速 "windScale": "2" // 风力等级 } ] } #### 日统计数据 * 简介：获取以下气象指标【温度、相对湿度、风速、气压、能见度】的日最大/小值和日均值数据。 注意：有小时天气历史数据的城市才有日统计数据记录，该记录数据在每日凌晨将昨日小时气象数据统计得出；该接口最大支持一年的数据查询。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/DayStaticData ##### body体参数： { "startTime":"2021-01-01 00:00:00", // 开始时间（包含） "endTime":"2021-01-02 00:00:00", // 结束时间（不包含） "cityName":"北京市", "dataType":"All" // 返回数据类型，字符串枚举值 } 注：参数dataType三个可选枚举值，默认为Max，表示获取最大最小值；Avg，表示获取平均值；All，表示获取最大最小值和平均值 ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "maxVisibility": 27.0, // 能见度最大值，number "avgPressure": 1021.5, // 气压均值，number "maxTemp": 1.0, // 温度度最大值，number "avgHumidity": 37.0, // 相对湿度均值，number "avgTemp": -5.4, // 温度均值，number "minHumidity": 17.0, // 相对湿度最小值，number "dayTime": "2021-01-01 00:00:00", "minTemp": -11.0, // 温度最小值，number "maxWindSpeed": 8.0, // 风速最大值，number "avgWindSpeed": 4.0, // 风速均值，number "minVisibility": 11.0, // 能见度最小值，number "avgVisibility": 17.0, // 能见度均值，number "minPressure": 1020.0, // 气压最小值，number "maxPressure": 1024.0, // 气压最大值，number "minWindSpeed": 1.0, // 风速最小值，number "maxHumidity": 59.0 // 相对湿度最大值，number } ] } #### 灾害预警 * 简介：获取指定城市的指定时间区间的灾害预警信息。 注： 1.同一种灾害预警如果级别不同，则结果可能返回多条结果数据； 2.灾害数据更新频率为15分钟/次； 3.所查询的时间跨度最大支持一年。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/DisasterWarningQuery ##### body体参数： { "startTime":"2021-01-18 00:00:00", // 开始时间（包含） "endTime":"2021-01-21 00:00:00", // 结束时间（不包含） "cityName":"北京市", "type":"道路结冰", // 非必需，灾害类型枚举值 "level":"黄色" // 非必需，预警级别枚举值 } ##### 请求结果： { "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": "道路结冰" } ] } #### 日出日落数据 * 简介：根据坐标或者数据字典城市编码或者包含数据字典城市编码的项目数据字典ID计算日出日落时间。 注：入参支持数据字典城市名称，数据字典城市编码，符合数据字典命名规范的项目ID，经纬度值，四项参数不能全部为空，使用优先级：经纬度值> 数据字典城市编码 > 项目ID > 城市名称。该接口支持最长一年的数据计算。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/SunRiseAndSet ##### body体参数： { "cityName":"北京市", "longitude":116.4, // 经度坐标，Double "latitude":39.9, // 纬度坐标，Double "startDay":"2021-02-14", // 开始日（含），yyyy-MM-dd "endDay":"2021-02-15" // 结束日（不含），yyyy-MM-dd } ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "sunSet": "2021-02-14 17:50:00", // 日落时间 "sunRise": "2021-02-14 07:06:00" // 日出时间 } ] } #### 字典数据-天气现象编码与文字 * 简介：获取天气现象编码及文字描述信息。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/DicWeatherCodeName ##### body体参数： {} ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ { "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": "未知" } ] } #### 字典数据-灾害预警类型 * 简介：获取灾害预警类型信息。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/DicDisasterType ##### body体参数： {} ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ "台风", "暴雨", "暴雪", "寒潮", "大风", "沙尘暴", "高温", "干旱", "雷电", "冰雹", "霜冻", "大雾", "道路结冰", "雷雨大风" ] } #### 字典数据-灾害预警级别 * 简介：获取灾害预警类型信息。 * Method：POST * Header参数：Content-Type=application/json * URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/DicDisasterLevel ##### body体参数： {} ##### 请求结果： { "version": "1.0", "result": "success", "reason": null, "content": [ "白色", "蓝色", "黄色", "橙色", "红色" ] } #### 天气现象图标下载 * 简介：获取天气现象图标图片数据。 * Method：GET * URL：/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. 接口请求示例：/EMS_Weather/Spring/MVC/entrance/download/icon/5-classic-big ##### 请求结果：会返回数据流