HTTP接口说明

目前天气服务只向外提供了HTTP接口形式的服务。接口以2020年为时间线分为两个大版本：2020年及之前版本，2021年之后版本。这两个版本在接口功能及提供的数据上相同，只是接口风格及返回的数据结构略有差异。凡首次使用天气服务的产品，应使用2020年之后版本的接口，2020年及之前版本的接口将在2021年7月1日始，拒绝所有新的ip请求，且停止接口服务升级和维护。以下是对两个版本的接口说明。

2021版

2020版

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

POST接口请求方式说明

说明：该版HTTP接口，凡是Method为POST的，支持两种参数请求方式。这两种请求方式对应Header参数Content-Type的两种值。

方式一

该类接口以接口以/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"}。

接口统一参数说明

所有查询指定城市天气数据的接口，都需要在参数中指明是哪一个城市。目前天气服务支持传入以下三个参数（至少有一个），来定位城市。三个参数的key及说明如下：

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

接口说明

注：以下对于接口说明，均已*POST接口请求方式说明*所述的*方式二*进行举例。凡是涉及到到传指定城市信息参数的地方，示例请求参数均已cityName作为参数，实际接口调用时，可根据*接口统一参数说明*中说明使用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"
        }
    ]
}

小时级历史数据

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

• 接口最大支持查询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

• 请求结果：会返回数据流