接口
cuixubin edited this page 3 years ago

天气服务接口文档

统一说明

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

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

业务接口

注意: 凡是入参涉及到传城市信息的,以下接口说明中均已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/dataNow

请求参数:

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

返回结果:

正确JSON示例

{
    "result": "success",
    "message": null,
    "data": {
        "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示例

{
    "result": "fail",
    "message": "错误信息,如果接口发生错误会返回该字段"
}

预报数据查询

简介:获取未来24小时预报数据,或14天日预报数据。此“未来24小时”包含当前小时整点,以及未来的23个小时的23个整点,共24条天气数据。

Method:POST

Header参数:Content-Type=application/json

URL:/EMS_Weather/Spring/MVC/entrance/unifierJson/dataPredict

请求参数:

{
    "cityName":"城市名称,比如:上海",
    "dataType":"枚举值字符串:hour,小时预报; day,日预报; disaster,灾害预报",
    "startTime":"开始时间(包含),dataType为disaster时需要该参数,示例:2021-01-18 00:00:00",
    "endTime":"结束时间(不包含),dataType为disaster时需要该参数,示例:2021-01-21 00:00:00"
}

返回结果:

正确JSON,小时预报数据示例

{
    "result": "success",
    "message": null,
    "data": [
        {
            "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,日预报数据示例

{
    "result": "success",
    "message": null,
    "data": [
        {
            "date": "2021-01-21",
            "high": "日最高温,Str,示例:6",
            "rainfall": "降雨量,str, 示例:0.0",
            "codeDay": "白日气象编码,示例:0",
            "windDirectionDegree": "风向角,str,示例:225", 
            "textDay": "白日气象文字,str,示例:晴",
            "codeNight": "白日气象编码,str,示例:1",
            "low": "日最低温,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,日灾害预警示例

注:

  1. 同一种灾害预警如果级别不同,则结果可能返回多条结果数据;
  2. 灾害数据更新频率为15分钟/次;
  3. 所查询的时间跨度最大支持一年。
{
    "result": "success",
    "message": null,
    "data": [
        {
            "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示例

{
    "result": "fail",
    "message": "错误信息,如果接口发生错误会返回该字段"
}

历史数据查询

简介:获取小时历史数据或日历史数据。

小时历史数据查询提示:

  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/dataHistory

请求参数:

{
    "cityName":"城市名称,比如:上海",
    "dataType":"枚举值字符串:hour,小时数据; day,日数据",
    "startTime":"开始时间(包含),str,示例:2021-01-01 00:00:00",
    "endTime":"结束时间(不包含),str,示例:2021-01-03 00:00:00"
}

返回结果:

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

{
    "result": "success",
    "message": null,
    "data": [
        {
            "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,日历史数据示例

{
    "result": "success",
    "message": null,
    "data": [
        {
            "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示例

{
    "result": "fail",
    "message": "错误信息,如果接口发生错误会返回该字段"
}

统计数据查询

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

提示:

  1. 有小时天气历史数据的城市才有日统计数据记录;
  2. 数据在每日0-1时更新;
  3. 接口最大支持一年的数据查询;

Method:POST

Header参数:Content-Type=application/json

URL:/EMS_Weather/Spring/MVC/entrance/unifierJson/dataStatistic

请求参数:

{
    "cityName":"城市名称,比如:上海",
    "dataSize":"枚举值字符串:max,返回最大最小值; avg,返回均值,all,返回最值和均值",
    "startTime":"开始时间(包含),str,示例:2021-01-01 00:00:00",
    "endTime":"结束时间(不包含),str,示例:2021-01-03 00:00:00"
}

返回结果:

正确JSON示例

{
    "result": "success",
    "message": null,
    "data": [
        {
            "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示例

{
    "result": "fail",
    "message": "错误信息,如果接口发生错误会返回该字段"
}

日出日落时间计算

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

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

Method:POST

Header参数:Content-Type=application/json

URL:/EMS_Weather/Spring/MVC/entrance/unifierJson/sunRiseAndSetCompute

请求参数:

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

返回结果:

正确JSON示例

{
    "result": "success",
    "message": null,
    "data": [
        {
            "day": "日时间yyyy-MM-dd,str,示例:2021-02-14",
            "sunSet": "日落时间HH:mm:ss,str,示例:17:50:00",
            "sunRise": "日出时间HH:mm:ss,str,示例:07:06:00"
        }
    ]
}

错误JSON示例

{
    "result": "fail",
    "message": "错误信息,如果接口发生错误会返回该字段"
}

天气现象图标下载

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

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

返回结果:数据流