logo-square-300
我的信息

我的API密钥:登录后查看

API密钥(key)是用来验证API请求合法性的一个唯一字符串,通过API请求中的key参数传入。

我的用户ID:登录后查看

用户ID是在注册心知会员时得到的一个10位字符串,如U123456789。用户ID会被使用在签名验证方式中。

开始

心知天气支持的全球城市

心知天气支持全国2567个、全球24,373个城市和地点。下面的交互地图中的每一个亮点都代表其中一个城市。心知会持续增加支持的城市数量,尽快点亮地球上的每一个城市和角落。

城市列表下载

查看全屏地图


如何使用签名验证方式

心知天气API不仅支持API密钥key的验证方式,也支持更安全的签名验证方式。

签名指的是通过HMAC-SHA1,对请求参数加密后得到的签名字串进行身份验证,避免了将API密钥明文包含在请求中而造成泄露。

签名的生成方式如下:

  1. 构造验证参数字符串。

    将请求参数按照参数名字典升序排列后,把所有参数param=value用&连接起来,类似URI中Query string的构造方式。目前支持的参数有:UNIX时间戳ts(单位为秒),签名失效时间ttl(可选)和用户IDuid。例:ts=1443079775&ttl=30&uid=U123456789

  2. 使用HMAC-SHA1方式,以API密钥(key)对上一步生成的参数字符串进行加密。

    常见程序语言通常会内置加密函数,或通过扩展库提供支持。例如在NodeJS中,您可以使用crypto模块中的中的createHmac函数,例:crypto.createHmac("sha1", key)。

  3. 将上一步生成的加密结果用base64编码,并做一个urlencode,得到签名sig。

    例:假设key为"secret",步骤(1)中的参数例子加密后得到的结果应为为dTYeoN8WdOfW4PiwgEdLa0gWFzo=,做完urlencode最终得到的签名sig为dTYeoN8WdOfW4PiwgEdLa0gWFzo%3d

  4. 将上一步得到的签名sig附在第一步构造的参数字符串后,作为请求的一个参数发送。

    上述例子里,请求参数即为ts=1443079775&ttl=30&uid=U123456789&sig=dTYeoN8WdOfW4PiwgEdLa0gWFzo%3d

注意:

  • 签名失效时间参数ttl是可选参数。如果忽略这个参数,生成的签名有效期默认为1800秒(30分钟)。较短的有效期可以使签名更难被盗用,提高安全性。

  • 请求中的其它参数,例如location,language,不参与签名。

  • 点此查看API密钥和用户ID


如何使用JSONP方式调用

心知天气API增加了JSONP的支持,可以在网页中直接调用API接口,而不通过服务器中转。JSONP方式调用必须绑定域名,并使用签名验证方式。

方法:在请求中使用callback参数指定回调函数的名字,使用签名验证方式,并在网页中通过script的方式调用。例:

<script type="text/javascript" src="https://api.seniverse.com/v3/weather/now.json?location=beijing&ts=1443079775&ttl=30&uid=[your_uid]&sig=[your_signature]&callback=showWeather"></<script>

返回结果:

showWeather({
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      ......
});

关于天气数据单位的说明

心知天气V3版API对于返回的天气数据的单位做了更加标准化的处理。unit参数有c或f两个值,包含温度、风速、能见度和气压四个指标的单位,具体说明如下:

当unit为c时

返回值单位
温度c(摄氏度)
风速km/h(千米每小时)
能见度km(千米)
气压mb(百帕)

当unit为f时

返回值单位
温度f(华氏度)
风速mph(英里每小时)
能见度mi(英里)
气压in(英寸)

天气现象代码说明

每一种天气现象(例如:晴、小雨、多云等)都对应一个天气现象代码,即API返回结果中的code字段。下表列出了心知天气API所有可能返回的天气现象代码。注:部分天气现象提供白天和夜间两种代码。

天气现象图标下载

每一个天气现象代码也对应了一个PNG图标,心知天气用户可免费下载使用。下载地址:

天气现象代码对照表

代码中文英文图标
0Sunny晴
1Clear晴
2Fair晴
3Fair晴
4多云Cloudy多云
5晴间多云Partly Cloudy晴间多云
6晴间多云Partly Cloudy晴间多云
7大部多云Mostly Cloudy大部多云
8大部多云Mostly Cloudy大部多云
9Overcast阴
10阵雨Shower阵雨
11雷阵雨Thundershower雷阵雨
12雷阵雨伴有冰雹Thundershower with Hail雷阵雨伴有冰雹
13小雨Light Rain小雨
14中雨Moderate Rain中雨
15大雨Heavy Rain大雨
16暴雨Storm暴雨
17大暴雨Heavy Storm大暴雨
18特大暴雨Severe Storm特大暴雨
19冻雨Ice Rain冻雨
20雨夹雪Sleet雨夹雪
21阵雪Snow Flurry阵雪
22小雪Light Snow小雪
23中雪Moderate Snow中雪
24大雪Heavy Snow大雪
25暴雪Snowstorm暴雪
26浮尘Dust浮尘
27扬沙Sand扬沙
28沙尘暴Duststorm沙尘暴
29强沙尘暴Sandstorm强沙尘暴
30Foggy雾
31Haze霾
32Windy风
33大风Blustery大风
34飓风Hurricane飓风
35热带风暴Tropical Storm热带风暴
36龙卷风Tornado龙卷风
37Cold冷
38Hot热
99未知Unknown未知

API返回错误代码说明

当API请求由于权限不足、服务过期等原因导致错误时,API会返回如下结构的错误信息。你的程序可以根据status_code来进行相应的处理。

{
  "status": "The location can not be found.",
  "status_code": "AP010010"
}

可能出现的status_code说明如下:

status_code说明
AP010001API请求参数错误。
AP010002没有权限访问这个API接口。在此查看你有权访问的API接口
AP010003API密钥key错误。
AP010004签名错误。
AP010005你请求的API不存在。
AP010006没有权限访问这个地点。
AP010007JSONP请求需要使用签名验证方式。
AP010008没有绑定域名。在此绑定域名
AP010009API请求的user-agent与你设置的不一致。
AP010010没有这个地点。
AP010011无法查找到制定IP地址对应的城市。
AP010012你的服务已经过期。在此续费
AP010013访问量余额不足。联系客服购买更多访问量。
AP010014免费用户超过了每小时访问量额度。一小时后自动恢复。
AP010015暂不支持该城市的车辆限行信息。
AP100001系统内部错误:数据缺失。
AP100002系统内部错误:数据错误。
AP100003系统内部错误:服务内部错误。

多语言支持说明

心知天气API支持13种语言,分别为:中文(简体、繁体),英语,日语,德语,法语,俄语,西班牙语,葡萄牙语,泰语,阿拉伯语,印尼语,印地语。多语言支持向心知的所有注册用户开放,无论免费用户还是付费用户,都可以通过接口的language参数改变返回数据的语言。

参数
language
语言 (可选)

参数值范围:

  • zh-Hans 简体中文
  • zh-Hant 繁体中文
  • en 英文
  • ja 日语
  • de 德语
  • fr 法语
  • es 西班牙语
  • pt 葡萄牙语
  • hi 印地语(印度官方语言之一)
  • id 印度尼西亚语
  • ru 俄语
  • th 泰语
  • ar 阿拉伯语

默认值:zh-Hans

注意:

  • language为可选参数。如果忽略,返回数据的默认语言为简体中文(默认值zh-Hans)。

  • 气象灾害预警、农历、节气、生肖接口无多语言支持。生活指数的details无多语言支持。


示例代码

为了帮助你快速学习如何使用心知天气API,我们提供了多种编程语言下调用心知天气API的示例代码,包括Node.js、Python、PHP、Android、JSONP等。

点此查看:https://github.com/seniverse/seniverse-api-demos

欢迎成为心知共创社区的一员,将你的示例代码提交给我们,请在Github上Pull Request,或发送到邮箱hack@seniverse.com

天气

天气实况

GET/weather/now.json

获取指定城市的天气实况。付费用户可获取全部数据,免费用户只返回天气现象文字、代码和气温3项数据。注:中国城市暂不支持云量和露点温度。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

unit
单位 (可选)

参数值范围:

  • c 当参数为c时,温度c、风速km/h、能见度km、气压mb
  • f 当参数为f时,温度f、风速mph、能见度mile、气压inch

默认值:c

返回结果  200
{
  "results": [{
  "location": {
      "id": "C23NB62W20TF",
      "name": "西雅图",
      "country": "US",
      "timezone": "America/Los_Angeles",
      "timezone_offset": "-07:00"
  },
  "now": {
      "text": "多云", //天气现象文字
      "code": "4", //天气现象代码
      "temperature": "14", //温度,单位为c摄氏度或f华氏度
      "feels_like": "14", //体感温度,单位为c摄氏度或f华氏度
      "pressure": "1018", //气压,单位为mb百帕或in英寸
      "humidity": "76", //相对湿度,0~100,单位为百分比
      "visibility": "16.09", //能见度,单位为km公里或mi英里
      "wind_direction": "西北", //风向文字
      "wind_direction_degree": "340", //风向角度,范围0~360,0为正北,90为正东,180为正南,270为正西
      "wind_speed": "8.05", //风速,单位为km/h公里每小时或mph英里每小时
      "wind_scale": "2", //风力等级,请参考:http://baike.baidu.com/view/465076.htm
      "clouds": "90", //云量,范围0~100,天空被云覆盖的百分比 #目前不支持中国城市#
      "dew_point": "-12" //露点温度,请参考:http://baike.baidu.com/view/118348.htm #目前不支持中国城市#
  },
  "last_update": "2015-09-25T22:45:00-07:00" //数据更新时间(该城市的本地时间)
  }]
}

逐日天气预报和昨日天气

GET/weather/daily.json

获取指定城市未来最多15天每天的白天和夜间预报,以及昨日的历史天气。付费用户可获取全部数据,免费用户只返回3天天气预报。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

unit
单位 (可选)

参数值范围:

  • c 当参数为c时,温度c、风速km/h、能见度km、气压mb
  • f 当参数为f时,温度f、风速mph、能见度mile、气压inch

默认值:c

start
起始时间 (可选)

参数值范围:

  • 日期 例如:start=2015/10/1
  • 整数 例如:start=-2 代表前天、start=-1 代表昨天、start=0 代表今天、start=1 代表明天

默认值:0

days
天数 (可选) 返回从start算起days天的结果。默认为你的权限允许的最多天数。

参数值范围:

  • 整数 例如:days=3 代表3天、days=7 代表7天

返回结果  200
{
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      "country": "CN",
      "path": "北京,北京,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "daily": [{                         //返回指定days天数的结果
      "date": "2015-09-20",             //日期
      "text_day": "多云",               //白天天气现象文字
      "code_day": "4",                  //白天天气现象代码
      "text_night": "晴",               //晚间天气现象文字
      "code_night": "0",                //晚间天气现象代码
      "high": "26",                     //当天最高温度
      "low": "17",                      //当天最低温度
      "precip": "0",                    //降水概率,范围0~100,单位百分比
      "wind_direction": "",             //风向文字
      "wind_direction_degree": "255",   //风向角度,范围0~360
      "wind_speed": "9.66",             //风速,单位km/h(当unit=c时)、mph(当unit=f时)
      "wind_scale": ""                  //风力等级
    }, {
      "date": "2015-09-21",
      "text_day": "晴",
      "code_day": "0",
      "text_night": "晴",
      "code_night": "0",
      "high": "27",
      "low": "17",
      "precip": "0",
      "wind_direction": "",
      "wind_direction_degree": "157",
      "wind_speed": "17.7",
      "wind_scale": "3"
    }, {
      ...                               //更多返回结果
    }],
    "last_update": "2015-09-20T18:00:00+08:00" //数据更新时间(该城市的本地时间)
  }]
}

24小时逐小时天气预报(付费接口)

GET/weather/hourly.json

获取指定城市未来最多24小时的逐小时天气预报,支持全球城市。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

unit
单位 (可选)

参数值范围:

  • c 当参数为c时,温度c、风速km/h、能见度km、气压mb
  • f 当参数为f时,温度f、风速mph、能见度mile、气压inch

默认值:c

start
起始时间 (可选)

参数值范围:

  • 整数 例如:start=0 代表这个小时、start=1 代表下个小时

默认值:0

hours
小时数 (可选) 返回从start算起hours个小时的结果。默认为你的权限允许的最多预报小时数。

参数值范围:

  • 整数 例如:hours=3 代表3小时、hours=24 代表24小时

返回结果  200
{
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      "country": "CN",
      "path": "北京,北京,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "hourly": [{           //逐小时天气预报数组,数量可由start和hours参数控制,最多24个对象。
      "time": "2016-02-19T14:00:00+08:00",  //时间
      "text": "多云",      //天气现象文字
      "code": "4",        //天气现象代码
      "temperature": "7",     //温度,单位为c摄氏度或f华氏度
      "humidity": "35",       //相对湿度,0~100,单位为百分比
      "wind_direction": "北", //风向
      "wind_speed": "18.0"    //风速,单位为km/h公里每小时或mph英里每小时
    }, {                  //下一个小时预报
      "time": "2016-02-19T15:00:00+08:00",
      "text": "多云",
      "code": "4",
      "temperature": "6",
      "humidity": "37",
      "wind_direction": "西北",
      "wind_speed": "12.0"
    }, {
      ...                 //后面的就省略了
    }]
  }]
}

过去24小时历史天气(付费接口)

GET/weather/hourly_history.json

获取指定城市过去24小时逐小时的历史天气。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

unit
单位 (可选)

参数值范围:

  • c 当参数为c时,温度c、风速km/h、能见度km、气压mb
  • f 当参数为f时,温度f、风速mph、能见度mile、气压inch

默认值:c

返回结果  200
{
  "results": [{
    "location": {
      "id": "C23NB62W20TF",
      "name": "西雅图",
      "country": "US",
      "path": "西雅图,华盛顿州,美国",
      "timezone": "America/Los_Angeles",
      "timezone_offset": "-08:00"
    },
    "hourly_history": [{            //最近24小时天气历史记录数组
      "text": "多云",
      "code": "4",
      "temperature": "6",
      "feels_like": "4",
      "pressure": "1018",
      "humidity": "86",
      "visibility": "16.09",
      "wind_direction": "南",
      "wind_direction_degree": "170",
      "wind_speed": "8.05",
      "wind_scale": "2",
      "clouds": "90",
      "dew_point": "-16",
      "last_update": "2015-12-02T22:45:00+08:00"
    }, {
      "text": "多云",
      "code": "4",
      "temperature": "6",
      "feels_like": "4",
      "pressure": "1018",
      "humidity": "87",
      "visibility": "16.09",
      "wind_direction": "东南",
      "wind_direction_degree": "170",
      "wind_speed": "9.66",
      "wind_scale": "2",
      "clouds": "90",
      "dew_point": "-16",
      "last_update": "2015-12-02T21:45:00+08:00"
    }, {
      ...
    }]
  }]
}

气象灾害预警(付费接口)

GET/weather/alarm.json

获取当前所有城市或指定城市的气象灾害预警信息。当前城市无预警信息时返回值为空,请做好空值处理。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

返回结果  200
{
  "results": [{ //当前全国或指定城市的气象灾害预警数组
    "location": { //第一个灾害预警的城市信息
      "id": "WM3B1R518R80",
      "name": "乐山",
      "country": "CN",
      "path": "乐山,乐山,四川,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "alarms": [{ //该城市所有的灾害预警数组
      "title": "四川省乐山市气象台发布大雾黄色预警", //灾害预警
      "type": "大雾",
      "level": "黄色",
      "status": "预警中",
      "description": "我县出现能见度小于500米、大于等于200米的浓雾并将持续至10时左右,请注意交通安全,减少户外活动,预防浓雾带来的不利影响。",
      "pub_date": "2015-09-23T07:02:00+08:00"
    }]
  }, {
    ...
  }]
}
空气质量

空气质量实况(付费接口)

GET/air/now.json

获取指定城市的AQI、PM2.5、PM10、一氧化碳、二氧化氮、臭氧等空气质量信息。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

scope
范围 (可选) 设定返回城市平均值或各监测站监测值

参数值范围:

  • city 只返回城市平均值
  • all 返回城市平均值和各监测站监测值

默认值:city

返回结果  200
{
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      "country": "CN",
      "path": "北京,北京,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "air": {
      "city": { //城市综合空气质量数据
        "aqi": "40", //空气质量指数(AQI)是描述空气质量状况的定量指数
        "pm25": "28", //PM2.5颗粒物(粒径小于等于2.5μm)1小时平均值。单位:μg/m³
        "pm10": "33", //PM10颗粒物(粒径小于等于10μm)1小时平均值。单位:μg/m³
        "so2": "2", //二氧化硫1小时平均值。单位:μg/m³
        "no2": "32", //二氧化氮1小时平均值。单位:μg/m³
        "co": "0.642", //一氧化碳1小时平均值。单位:mg/m³
        "o3": "78", //臭氧1小时平均值。单位:μg/m³
        "quality": "优", //空气质量类别,有“优、良、轻度污染、中度污染、重度污染、严重污染”6类
        "last_update": "2015-09-23T13:00:00+08:00" //数据发布时间
      },
      "stations": [{ //该城市所有监测站数组
        "aqi": "50",
        "pm25": "35",
        "pm10": "0",
        "so2": "2",
        "no2": "39",
        "co": "0.8",
        "o3": "83",
        "station": "万寿西宫", //监测站名称
        "latitude": "39.865927",  //监测站纬度
        "longitude": "116.359805",  //监测站经度
        "last_update": "2015-09-23T13:00:00+08:00" //监测站名称
      }, {
        ... //更多监测站
      }]
    },
    "last_update": "2015-09-23T22:45:48+08:00"
  }]
}

空气质量实况城市排行(付费接口)

GET/air/ranking.json

获取全国城市空气质量AQI排行榜。

请求地址示例
参数
key
你的API密钥
language
语言 (可选)

参数值范围:点此查看

默认值:zh-Hans

返回结果  200
{
  "results": [{ //城市排名数组,从好到差排序
    "location": { //排名第一城市
      "id": "TV9JG0M1S9QU", //城市ID
      "name": "阿里", //城市名称
      "country": "CN", //国家代码
      "path": "阿里,阿里,西藏,中国", //隶属层级,从小到大
      "timezone": "Asia/Shanghai", //IANA标准时区名称(该名称不受夏令时影响)
      "timezone_offset": "+08:00" //相对于UTC时区的偏移量(采用夏令时的城市会因夏令时而变化)
    },
    "aqi": "18" //空气质量指数
  }, {
    "location": { //排名第二城市
      "id": "WKN2DZXM71F0",
      "name": "玉林",
      "country": "CN",
      "path": "玉林,玉林,广西,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "aqi": "18"
  }, {
    ... //后续排名城市
  }]
}

逐日空气质量预报(付费接口)

GET/air/daily.json

获取指定城市未来最多7天的逐日AQI预报。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

days
天数 (可选) 返回days天的结果。默认为你的权限允许的最多天数。

参数值范围:

  • 整数 例如:days=3 代表3天、days=7 代表7天

language
语言 (可选)

参数值范围:点此查看

返回结果  200
{
  "results": [
    {
      "location": {
        "id": "WX4FBXXFKE4F", 
        "name": "北京", 
        "country": "CN", 
        "path": "北京,北京,中国", 
        "timezone": "Asia/Shanghai", 
        "timezone_offset": "+08:00"
      }, 
      "daily": [                //返回指定days天数的结果
        {
          "aqi": "73",          //空气质量指数(AQI)是描述空气质量状况的定量指数
          "pm25": "46.742",     //PM2.5颗粒物(粒径小于等于2.5μm)预报值。单位:μg/m³
          "pm10": "96",         //PM10颗粒物(粒径小于等于10μm)预报值。单位:μg/m³ 
          "so2": "23",          //二氧化硫预报值。单位:μg/m³
          "no2": "49",          //二氧化氮预报值。单位:μg/m³
          "co": "1",            //一氧化碳预报值。单位:mg/m³
          "o3": "44",           //臭氧预报值。单位:μg/m³
          "quality": "良",      //空气质量类别,有“优、良、轻度污染、中度污染、重度污染、严重污染”6类
          "date": "2016-04-10"  //预报日期
        }, 
        ... //下一天预报
      ], 
      "last_update": "2016-04-10T02:23:22+08:00"  //预报发布时间
    }
  ]
}

逐小时空气质量预报(付费接口)

GET/air/hourly.json

获取指定城市未来最多7天的逐小时AQI预报。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

days
天数 (可选) 返回days天的结果。默认为你的权限允许的最多天数。

参数值范围:

  • 整数 例如:days=3 代表3天、days=7 代表7天

language
语言 (可选)

参数值范围:点此查看

返回结果  200
{
  "results": [
    {
      "location": {
        "id": "WX4FBXXFKE4F", 
        "name": "北京", 
        "country": "CN", 
        "path": "北京,北京,中国", 
        "timezone": "Asia/Shanghai", 
        "timezone_offset": "+08:00"
      }, 
      "hourly": [               //返回指定days天每个小时的预报结果
        {
          "aqi": "73",          //空气质量指数(AQI)是描述空气质量状况的定量指数
          "pm25": "46.742",     //PM2.5颗粒物(粒径小于等于2.5μm)预报值。单位:μg/m³
          "pm10": "96",         //PM10颗粒物(粒径小于等于10μm)预报值。单位:μg/m³ 
          "so2": "23",          //二氧化硫预报值。单位:μg/m³
          "no2": "49",          //二氧化氮预报值。单位:μg/m³
          "co": "1",            //一氧化碳预报值。单位:mg/m³
          "o3": "44",           //臭氧预报值。单位:μg/m³
          "quality": "良",      //空气质量类别,有“优、良、轻度污染、中度污染、重度污染、严重污染”6类
          "time": "2016-04-10T21:00:00+08:00"   //预报小时
        }, 
        ... //下一小时预报
      ], 
      "last_update": "2016-04-10T02:24:49+08:00" //预报发布时间
    }
  ]
} 

过去24小时历史空气质量(付费接口)

GET/air/hourly_history.json

获取指定城市过去24小时逐小时的AQI、PM2.5、PM10、一氧化碳、二氧化氮、臭氧等空气质量信息。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

scope
范围 (可选) 设定返回城市平均值或各监测站监测值

参数值范围:

  • city 只返回城市平均值
  • all 返回城市平均值和各监测站监测值

默认值:city

返回结果  200
{
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      "country": "CN",
      "path": "北京,北京,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "hourly_history": [{    //最近24小时空气质量历史记录数组
      "city": {
        "aqi": "26",
        "pm25": "7",
        "pm10": "25",
        "so2": "2",
        "no2": "13",
        "co": "0.292",
        "o3": "42",
        "last_update": "2015-12-02T22:00:00+08:00",
        "quality": "优"
      },
      "stations": null
    }, {
      "city": {
        "aqi": "22",
        "pm25": "6",
        "pm10": "16",
        "so2": "2",
        "no2": "14",
        "co": "0.292",
        "o3": "42",
        "last_update": "2015-12-02T21:00:00+08:00",
        "quality": "优"
      },
      "stations": null
    }, {
      ...                 //更多历史记录
    }]
  }]
}
生活

生活指数

GET/life/suggestion.json

获取指定城市的基本、交通、生活、运动、健康5大类共27项生活指数,仅支持中国城市。付费用户可获取全部数据; 免费用户只返回6项基本类生活指数,且只有brief,没有details。

  • 基本类:穿衣、紫外线强度、洗车、旅游、感冒、运动

  • 交通类:交通、路况

  • 生活类:晾晒、雨伞、空调开启、啤酒、逛街、夜生活、约会

  • 运动类:晨练、钓鱼、划船、放风筝

  • 健康类:过敏、美发、化妆、风寒、防晒、空气污染扩散条件、舒适度、心情

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

返回结果  200
{
  "results": [{
    "location": {
      "id": "WTW3SJ5ZBJUY",
      "name": "上海",
      "country": "CN",
      "path": "上海,上海,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "suggestion": {
      "ac": { //空调开启
        "brief": "较少开启",  //简要建议
        "details": "您将感到很舒适,一般不需要开启空调。" //详细建议
      },
      "air_pollution": { //空气污染扩散条件
        "brief": "较差",
        "details": "气象条件较不利于空气污染物稀释、扩散和清除,请适当减少室外活动时间。"
      },
      "airing": { //晾晒
        "brief": "不太适宜",
        "details": "天气阴沉,不利于水分的迅速蒸发,不太适宜晾晒。若需要晾晒,请尽量选择通风的地点。"
      },
      "allergy": { //过敏
        "brief": "极不易发",
        "details": "天气条件极不易诱发过敏,可放心外出,享受生活。"
      },
      "beer": { //啤酒
        "brief": "较不适宜",
        "details": "您将会感到有些凉意,建议饮用常温啤酒,并少量饮用为好。"
      },
      "boating": { //划船
        "brief": "较适宜",
        "details": "白天较适宜划船,但天气阴沉,气温稍低,请注意加衣,小心着凉。"
      },
      "car_washing": { //洗车
        "brief": "不宜",
        "details": "不宜洗车,未来24小时内有雨,如果在此期间洗车,雨水和路上的泥水可能会再次弄脏您的爱车。"
      },
      "chill": { //风寒
        "brief": "凉",
        "details": "感觉有点凉,室外活动注意适当增减衣物。"
      },
      "comfort": { //舒适度
        "brief": "较舒适",
        "details": "白天天气阴沉,会感到有点儿凉,但大部分人完全可以接受。"
      },
      "dating": { //约会
        "brief": "较适宜",
        "details": "虽然天空有些阴沉,但情侣们可以放心外出,不用担心天气来调皮捣乱而影响了兴致。"
      },
      "dressing": { //穿衣
        "brief": "较冷",
        "details": "建议着厚外套加毛衣等服装。年老体弱者宜着大衣、呢外套加羊毛衫。"
      },
      "fishing": { //钓鱼
        "brief": "较适宜",
        "details": "较适合垂钓,但天气稍凉,会对垂钓产生一定的影响。"
      },
      "flu": { //感冒
        "brief": "较易发",
        "details": "天气较凉,较易发生感冒,请适当增加衣服。体质较弱的朋友尤其应该注意防护。"
      },
      "hair_dressing": { //美发
        "brief": "一般",
        "details": "注意防晒,洗发不宜太勤,建议选用保湿防晒型洗发护发品。出门请戴上遮阳帽或打遮阳伞。"
      },
      "kiteflying": { //放风筝
        "brief": "不宜",
        "details": "天气不好,不适宜放风筝。"
      },
      "makeup": { //化妆
        "brief": "保湿",
        "details": "皮肤易缺水,用润唇膏后再抹口红,用保湿型霜类化妆品。"
      },
      "mood": { //心情
        "brief": "较差",
        "details": "天气阴沉,会感觉莫名的压抑,情绪低落,此时将所有的悲喜都静静地沉到心底,在喧嚣的尘世里,感受片刻恬淡的宁静。"
      },
      "morning_sport": { //晨练
        "brief": "不宜",
        "details": "阴天,早晨天气寒冷,请尽量避免户外晨练,若坚持室外晨练请注意保暖防冻,建议年老体弱人群适当减少晨练时间。"
      },
      "night_life": { //夜生活
        "brief": "较不适宜",
        "details": "有降水,会给您的出行带来很大的不便,建议就近或最好在室内进行夜生活。"
      },
      "road_condition": { //路况
        "brief": "干燥",
        "details": "阴天,路面比较干燥,路况较好。"
      },
      "shopping": { //购物
        "brief": "适宜",
        "details": "阴天,在这种天气里去逛街,省去了涂防晒霜,打遮阳伞的麻烦,既可放松身心,又会有很多意外收获。"
      },
      "sport": { //运动
        "brief": "较适宜",
        "details": "阴天,较适宜进行各种户内外运动。"
      },
      "sunscreen": { //防晒
        "brief": "弱",
        "details": "属弱紫外辐射天气,长期在户外,建议涂擦SPF在8-12之间的防晒护肤品。"
      },
      "traffic": { //交通
        "brief": "良好",
        "details": "阴天,路面干燥,交通气象条件良好,车辆可以正常行驶。"
      },
      "travel": { //旅游
        "brief": "适宜",
        "details": "天气较好,温度适宜,总体来说还是好天气哦,这样的天气适宜旅游,您可以尽情地享受大自然的风光。"
      },
      "umbrella": { //雨伞
        "brief": "不带伞",
        "details": "阴天,但降水概率很低,因此您在出门的时候无须带雨伞。"
      },
      "uv": { //紫外线
        "brief": "最弱",
        "details": "属弱紫外线辐射天气,无需特别防护。若长期在户外,建议涂擦SPF在8-12之间的防晒护肤品。"
      }
    },
    "last_update": "2015-11-28T14:10:48+08:00"
  }]
}

农历、节气、生肖(付费接口)

GET/life/chinese_calendar.json

查询任何一个公历日期对应的农历日期、农历传统节假日、二十四节气、天干地支纪年纪月纪日、及生肖属相。

请求地址示例
参数
key
你的API密钥
start
起始时间 (可选)

参数值范围:

  • 日期 例如:start=2015/10/1
  • 整数 例如:start=-2 代表前天、start=-1 代表昨天、start=0 代表今天、start=1 代表明天

默认值:0

days
天数 (可选) 返回从start算起days天的结果。默认为你的权限允许的最多天数。

参数值范围:

  • 整数 例如:days=3 代表3天、days=7 代表7天

返回结果  200
{
  "results": {
    "chinese_calendar": [{ //返回数组元素个数由start和days参数控制
      "date": "2014-01-31", //公历日期
      "zodiac": "蛇", //生肖属相
      "ganzhi_year": "癸巳", //干支纪年
      "ganzhi_month": "乙丑", //干支纪月
      "ganzhi_day": "壬寅", //干支纪日
      "lunar_year": "2014", //农历年
      "lunar_month": "1", //农历月(1-13,当有闰月时,比如2014年闰9月,则10表示闰9月,11表示10月)
      "lunar_day": "1", //农历日
      "lunar_month_name": "正月", //农历月中文名
      "lunar_day_name": "初一", //农历日中文名
      "lunar_leap_month": "9", //农历闰月所在月份,0表示无闰月
      "lunar_festival": "春节", //农历节假日,如:春节、端午、中秋等
      "solar_term": "" //二十四节气名,如:冬至、小寒、大寒、立春等
    }, {
      ... //下一天
    }]
  }
}

机动车尾号限行(付费接口)

GET/life/driving_restriction.json

查询北京、天津、哈尔滨、成都、杭州、贵阳、长春、兰州8个城市的今天、明天和后天的机动车尾号限行数据。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

返回结果  200
{
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      "country": "CN",
      "path": "北京,北京,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "restriction": {
      "penalty": "京牌罚100块,不扣分。非京牌罚100块,扣3分。",  //处罚规定
      "region": "五环路以内道路(不包括五环路主路)",  //限行区域
      "remarks": "临时号牌按号牌尾号数字限行。机动车车尾号为英文字母的按0号管理。本市核发号牌的纯电动小客车不受工作日高峰时段区域限行措施限制。警车、消防车、救护车、出租车、环卫车等非民用车辆不受上述限制, 外埠车辆工作日7时至9时、17时至20时禁止进五环(含),没有进京证禁止进六环(不含)",  //详细说明
      "limits": [{  //今天、明天、后天限行尾号数组
        "date": "2016-01-25",  //今天日期
        "plates": ["3", "8"],  //限行尾号
        "memo": "尾号限行"  //限行类型,其他城市可能是“日期尾号限行”、“单双号限行”等
      }, {
        "date": "2016-01-26",  //明天日期
        "plates": ["4", "9"],
        "memo": "尾号限行"
      }, {
        "date": "2016-01-27",  //后天日期
        "plates": ["5", "0"],
        "memo": "尾号限行"
      }]
    }
  }]
}
地理

日出日落(付费接口)

GET/geo/sun.json

查询全球各地最多15天的日出日落时间。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

start
起始时间 (可选)

参数值范围:

  • 日期 例如:start=2015/10/1
  • 整数 例如:start=-2 代表前天、start=-1 代表昨天、start=0 代表今天、start=1 代表明天

默认值:0

days
天数 (可选) 返回从start算起days天的结果。最多查询前后15天的结果。

参数值范围:

  • 整数 例如:days=3 代表3天、days=7 代表7天

返回结果  200
{
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      "country": "CN",
      "path": "北京,北京,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "sun": [{               //返回指定days天数的结果
      "date": "2016-10-01", //日期
      "sunrise": "06:10",   //日出时间
      "sunset": "18:00"     //日落时间
    }, {
      "date": "2016-10-02",
      "sunrise": "06:11",
      "sunset": "17:58"
    }, {
      "date": "2016-10-03",
      "sunrise": "06:12",
      "sunset": "17:57"
    }]
  }]
}

月出月落和月相(付费接口)

GET/geo/moon.json

查询全球各地最多15天的月出月落时间和月相。

请求地址示例
参数
key
你的API密钥
location
所查询的位置

参数值范围:

  • 城市ID 例如:location=WX4FBXXFKE4F
  • 城市中文名 例如:location=北京
  • 省市名称组合 例如:location=辽宁朝阳、location=北京朝阳
  • 城市拼音/英文名 例如:location=beijing(如拼音相同城市,可在之前加省份和空格,例:shanxi yulin)
  • 经纬度 例如:location=39.93:116.40(纬度前经度在后,冒号分隔)
  • IP地址 例如:location=220.181.111.86(某些IP地址可能无法定位到城市)
  • “ip”两个字母 自动识别请求IP地址,例如:location=ip

language
语言 (可选)

参数值范围:点此查看

start
起始时间 (可选)

参数值范围:

  • 日期 例如:start=2015/10/1
  • 整数 例如:start=-2 代表前天、start=-1 代表昨天、start=0 代表今天、start=1 代表明天

默认值:0

days
天数 (可选) 返回从start算起days天的结果。最多查询前后15天的结果。

参数值范围:

  • 整数 例如:days=3 代表3天、days=7 代表7天

返回结果  200
{
  "results": [{
    "location": {
      "id": "WX4FBXXFKE4F",
      "name": "北京",
      "country": "CN",
      "path": "北京,北京,中国",
      "timezone": "Asia/Shanghai",
      "timezone_offset": "+08:00"
    },
    "moon": [{                  //返回指定days天数的结果
      "date": "2015-09-20",     //日期
      "rise": "12:14",          //月出时间
      "set": "22:30",           //月落时间
      "fraction": "0.38",       //月球被照明部分比例,范围0~1
      "phase": "0.21",          //月相,范围0~1
      "phase_name": "蛾眉月"     //月相名称
    }, {
      "date": "2015-09-21",
      "rise": "13:10",
      "set": "23:22",
      "fraction": "0.49",
      "phase": "0.25",
      "phase_name": "上弦月"
    }, {
      "date": "2015-09-22",
      "rise": "14:03",
      "set": "10:31",
      "fraction": "0.59",
      "phase": "0.28",
      "phase_name": "盈凸月"
    }]
  }]
}
位置