城市信息搜索

天气数据是基于地理位置的数据,因此获取天气之前需要先知道具体的位置信息。和风天气提供一个功能强大的城市信息搜索API服务,可获取到需要查询城市的基本信息,包括城市或地区的Location ID(你需要这个ID去查询天气),多语言名称、经纬度、时区、海拔、Rank值、归属上级行政区域、所在行政区域等。

除此之外,城市信息搜索服务还可以帮助你:

  • 避免重名城市的困扰
  • 在你的应用或网站中根据用户输入的名称返回多个城市结果,便于用户选择准确的城市并返回该城市天气
  • 在你的应用或网站中展示热门城市,用户直接选择即可,减少搜索步骤提高用户体验
  • 不需要维护城市列表,城市信息更新实时获取

城市搜索每天每个账号下所有应用前50000次免费,超出部分参考计费方式

城市信息搜索

请求URL

HTTP GET https://geoapi.qweather.com/v2/city/lookup?{请求参数}

请求参数

请求参数包括必选和可选参数,如不填写可选参数将使用其默认值,参数之间使用 &进行分隔。

location 必选

输入需要查询的城市名称,可使用Location ID多语言文字、以逗号分隔的经度/纬度坐标、ADCode(仅限中国城市)。例如location=beijinglocation=116.4,39.1

模糊搜索,当location传递的为文字时,支持模糊搜索,即用户可以只输入城市名称一部分进行搜索,最少一个汉字或2个字符,排名将按照相关性和Rank值进行排列,便于开发或用户进行选择。例如location=bei,将返回与bei相关性最强的若干结果,包括黎巴嫩的贝鲁特和中国的北京市

重名,当location传递的为文字时,可能会出现重名的城市,例如陕西省西安市、吉林省辽源市下辖的西安区和黑龙江省牡丹江市下辖的西安区,此时会根据Rank值排序返回所有结果。在这种情况下,可以通过adm参数的方式进一步确定需要查询的城市或地区,例如location=西安&adm=黑龙江

key 必选

用户认证key,请参考如何获取你的KEY。支持数字签名方式进行认证,推荐使用。例如 key=123456789ABC

adm 可选

城市所属行政区划,只支持多语言文字,默认不限定行政区划。 可设定只在某个行政区划范围内进行搜索,用于出现重名城市或需要对结果进行过滤的时候使用。例如adm=beijing

如搜索参数为location=chaoyang&adm=beijing时,返回的结果只包括北京市的朝阳区,而不包括辽宁省的朝阳市

如搜索参数仅为location=chaoyang时,返回的结果包括北京市的朝阳区、辽宁省的朝阳市以及长春市的朝阳区

range 可选

搜索范围,默认搜索全球城市。 可设定只在某个国家范围内进行搜索,国家名称需使用ISO 3166 所定义的国家代码

  • world 全球城市范围,默认
  • cn 中国城市范围,可替换为其他国家的ISO 3166 国家代码,例如range=us

number 可选

返回城市的数量,取值范围1-20,默认返回10个结果

gzip 可选

对API接口进行压缩,可以极大的减少API接口访问延迟,减少缓存空间,提高接口连接成功率。默认开启gzip

  • y 使用gzip方式压缩,默认
  • n 不使用压缩

lang 可选

多语言,默认中文,例如lang=en。具体的语言参数值请参考多语言参数。当一些城市不存在对应的语言时,将返回英文或其本地语言结果。

返回数据

参数 描述 示例
code API状态码,具体含义请参考状态码 200
location.name 地区/城市名称 南山区
location.id 地区/城市ID 101280604
location.lat 地区/城市纬度 22.53122
location.lon 地区/城市经度 113.92942
location.adm2 该地区/城市的上级行政区划名称 深圳市
location.adm1 该地区/城市所属一级行政区域 广东省
location.country 该地区/城市所属国家名称 中国
location.tz 该地区/城市所在时区 Asia/Shanghai
location.utcOffset 该地区/城市目前与UTC时间偏移的小时数,参考详细说明 +08:00
location.isDst 该地区/城市是否当前处于夏令时
1 表示当前处于夏令时
0 表示当前不是夏令时
0
location.type 该地区/城市的属性 city
location.rank 地区评分 10
location.fxLink 该地区的天气预报网页链接,便于嵌入你的网站或应用 http://hfx.link/34T5

热门城市查询

请求URL

HTTP GET https://geoapi.qweather.com/v2/city/top?{请求参数}

请求参数

请求参数包括必选和可选参数,如不填写可选参数将使用其默认值,参数之间使用 &进行分隔。

key 必选

用户认证密钥,参考如何获取你的KEY。支持数字签名方式认证。例如:key=12334567890ABC

range 可选

热门城市范围,默认全球范围。 可选择某个国家范围内的热门城市,国家名称需使用ISO 3166 所定义的国家代码

  • world 全球城市范围,默认
  • cn 中国城市范围,可替换为其他国家的ISO 3166 国家代码,例如range=cn

number 可选

返回城市的数量,取值范围1-20,默认返回10个结果

gzip 可选

对API接口进行压缩,可以极大的减少API接口访问延迟,减少缓存空间,提高接口连接成功率。默认开启gzip

  • y 使用gzip方式压缩,默认
  • n 不使用压缩

lang 可选

多语言,默认中文,例如lang=en。具体的语言参数值请参考多语言参数。当一些城市不存在对应的语言时,将返回英文或其本地语言结果。

返回数据

参数 描述 示例值
code API状态码,具体含义请参考状态码 200
topCityList.name 地区/城市名称 南山区
topCityList.id 地区/城市ID 101280604
topCityList.lat 地区/城市纬度 22.53122
topCityList.lon 地区/城市经度 113.92942
topCityList.adm2 该地区/城市的上级行政区划名称 深圳市
topCityList.adm1 该地区/城市所属一级行政区域 广东省
topCityList.country 该地区/城市所属国家名称 中国
topCityList.tz 该地区/城市所在时区 Asia/Shanghai
topCityList.utcOffset 该地区/城市目前与UTC时间偏移的小时数,参考详细说明 +08:00
topCityList.isDst 该地区/城市是否当前处于夏令时
1 表示当前处于夏令时
0 表示当前不是夏令时
0
topCityList.type 该地区/城市的属性 city
topCityList.rank 地区评分 10
topCityList.fxLink 该地区的天气预报网页链接,便于嵌入你的网站或应用 http://hfx.link/34T5

POI信息搜索

请求URL

HTTP GET https://geoapi.qweather.com/v2/poi/lookup?{请求参数}

请求参数

请求参数包括必选和可选参数,如不填写可选参数将使用其默认值,参数之间使用&进行分隔。

location 必选

输入需要查询的POI名称,可使用中文、英文。最少一个汉字或2个英文字母,返回结果将按照相关性和Rank值进行排列。例如location=故宫

key 必选

用户认证key,请参考如何获取你的KEY。支持数字签名方式进行认证,推荐使用。例如 key=123456789ABC

type 必选

POI类型,可选择搜索某一类型的POI,目前仅限景点。例如type=scenic

city 可选

选择POI所在城市,可设定只搜索在特定城市内的POI信息。城市名称可以是文字或城市的LocationID。默认不限制特定城市

城市名称为精准匹配,建议使用LocaitonID,如文字无法匹配,则数据返回为空。

number 可选

返回POI的数量,取值范围1-20,默认返回10个结果

gzip 可选

对API接口进行压缩,可以极大的减少API接口访问延迟,减少缓存空间,提高接口连接成功率。默认开启gzip

  • y 使用gzip方式压缩,默认
  • n 不使用压缩

lang 可选

多语言,默认中文,例如lang=en。具体的语言参数值请参考多语言参数。当一些城市不存在对应的语言时,将返回英文或其本地语言结果。

返回数据

参数 描述 示例
code API状态码,具体含义请参考状态码 200
poi.name POI名称 南山区
poi.id POI的LocationID 101280604
poi.lat POI纬度 22.53122
poi.lon POI经度 113.92942
poi.adm2 该POI所属的上级行政区划名称 深圳市
poi.adm1 该POI所属的一级行政区域 广东省
poi.country 该POI所属的国家名称 中国
poi.tz 该POI所在时区 Asia/Shanghai
poi.utcOffset 该POI目前与UTC时间偏移的小时数,参考详细说明 +08:00
poi.isDst 该POI是否当前处于夏令时
1 表示当前处于夏令时
0 表示当前不是夏令时
0
poi.type 该POI的属性 city
poi.rank 地区评分 10

POI范围搜索

请求URL

HTTP GET https://geoapi.qweather.com/v2/poi/range?{请求参数}

请求参数

请求参数包括必选和可选参数,如不填写可选参数将使用其默认值,参数之间使用&进行分隔。

location 必选

输入需要查询的POI坐标,坐标以逗号分隔的经度/纬度坐标。例如location=116.4,39.1

key 必选

用户认证key,请参考如何获取你的KEY。支持数字签名方式进行认证,推荐使用。例如 key=123456789ABC

type 必选

POI类型,可选择搜索某一类型的POI,目前仅限景点。例如type=scenic

radius 可选

搜索范围,可设置搜索半径,取值范围1-50,单位:公里。默认5公里

number 可选

返回城市的数量,取值范围1-20,默认返回10个结果

gzip 可选

对API接口进行压缩,可以极大的减少API接口访问延迟,减少缓存空间,提高接口连接成功率。默认开启gzip

  • y 使用gzip方式压缩,默认
  • n 不使用压缩

lang 可选

多语言,默认中文,例如lang=en。具体的语言参数值请参考多语言参数。当一些城市不存在对应的语言时,将返回英文或其本地语言结果。

返回数据

参数 描述 示例
code API状态码,具体含义请参考状态码 200
poi.name POI名称 南山区
poi.id POI的LocationID 101280604
poi.lat POI纬度 22.53122
poi.lon POI经度 113.92942
poi.adm2 该POI所属的上级行政区划名称 深圳市
poi.adm1 该POI所属的一级行政区域 广东省
poi.country 该POI所属的国家名称 中国
poi.tz 该POI所在时区 Asia/Shanghai
poi.utcOffset 该POI目前与UTC时间偏移的小时数,参考详细说明 +08:00
poi.isDst 该POI是否当前处于夏令时
1 表示当前处于夏令时
0 表示当前不是夏令时
0
poi.type 该POI的属性 city
poi.rank 地区评分 10

请求和返回示例

城市信息搜索

// 搜索关键字beij 
// https://geoapi.qweather.com/v2/city/lookup?location=beij&key=xxx
// 请将示例请求URL中的KEY更换成你自己的KEY

{
  "status": "200",
  "location": [
    {
      "name": "北京",
      "id": "101010100",
      "lat": "39.90498",
      "lon": "116.40528",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "10",
      "fxLink": "https://www.qweather.com/weather/beijing-101010100.html"
    },
    {
      "name": "旧拜耶兰",
      "id": "BD495",
      "lat": "51.82416",
      "lon": "4.41249",
      "adm2": "旧拜耶兰",
      "adm1": "南荷兰省",
      "country": "荷兰",
      "tz": "Europe/Amsterdam",
      "utcOffset": "+02:00",
      "isDst": "1",
      "type": "city",
      "rank": "62",
      "fxLink": "https://www.qweather.com/weather/oud-beijerland-BD495.html"
    },
    {
      "name": "朝阳",
      "id": "101010300",
      "lat": "39.92148",
      "lon": "116.48641",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "15",
      "fxLink": "https://www.qweather.com/weather/chaoyang-101010300.html"
    },
    {
      "name": "海淀",
      "id": "101010200",
      "lat": "39.95607",
      "lon": "116.31031",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "15",
      "fxLink": "https://www.qweather.com/weather/haidian-101010200.html"
    },
    {
      "name": "丰台",
      "id": "101010900",
      "lat": "39.86364",
      "lon": "116.28696",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "25",
      "fxLink": "https://www.qweather.com/weather/fengtai-101010900.html"
    },
    {
      "name": "大兴",
      "id": "101011100",
      "lat": "39.72890",
      "lon": "116.33803",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "25",
      "fxLink": "https://www.qweather.com/weather/daxing-101011100.html"
    },
    {
      "name": "房山",
      "id": "101011200",
      "lat": "39.73553",
      "lon": "116.13916",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "https://www.qweather.com/weather/fangshan-101011200.html"
    },
    {
      "name": "通州",
      "id": "101010600",
      "lat": "39.90248",
      "lon": "116.65859",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "https://www.qweather.com/weather/tongzhou-101010600.html"
    },
    {
      "name": "石景山",
      "id": "101011000",
      "lat": "39.91460",
      "lon": "116.19544",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "35",
      "fxLink": "https://www.qweather.com/weather/shijingshan-101011000.html"
    },
    {
      "name": "昌平",
      "id": "101010700",
      "lat": "40.21808",
      "lon": "116.23590",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "https://www.qweather.com/weather/changping-101010700.html"
    }
  ]
}

热门城市查询

// 中国热门城市前5位 
// https://geoapi.qweather.com/v2/city/top?number=5&range=cn&key=xxx
// 请将示例请求URL中的KEY更换成你自己的KEY

{
  "status": "200",
  "topCityList": [
    {
      "name": "余杭",
      "id": "101210106",
      "lat": "30.42118",
      "lon": "120.30173",
      "adm2": "杭州",
      "adm1": "浙江",
      "cnty": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "25",
      "fxLink": "https://www.qweather.com/weather/yuhang-101210106.html"
    },
    {
      "name": "嘉定",
      "id": "101020500",
      "lat": "31.38352",
      "lon": "121.25033",
      "adm2": "上海",
      "adm1": "上海",
      "cnty": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "https://www.qweather.com/weather/jiading-101020500.html"
    },
    {
      "name": "杭州",
      "id": "101210101",
      "lat": "30.28745",
      "lon": "120.15357",
      "adm2": "杭州",
      "adm1": "浙江",
      "cnty": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "11",
      "fxLink": "https://www.qweather.com/weather/hangzhou-101210101.html"
    },
    {
      "name": "上海",
      "id": "101020100",
      "lat": "31.23170",
      "lon": "121.47264",
      "adm2": "上海",
      "adm1": "上海",
      "cnty": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "11",
      "fxLink": "https://www.qweather.com/weather/shanghai-101020100.html"
    },
    {
      "name": "萧山",
      "id": "101210102",
      "lat": "30.16293",
      "lon": "120.27069",
      "adm2": "杭州",
      "adm1": "浙江",
      "cnty": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "https://www.qweather.com/weather/xiaoshan-101210102.html"
    }
  ]
}

POI信息搜索

// 搜索关键字jings 
// https://geoapi.qweather.com/v2/poi/lookup?type=scenic&location=jings&key=xxx
// 请将示例请求URL中的KEY更换成你自己的KEY

{
  "status": "200",
  "poi": [
    {
      "name": "景山公园",
      "id": "10101010012A",
      "lat": "39.91999",
      "lon": "116.38999",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "67",
      "fxLink": "-999"
    },
    {
      "name": "静思园",
      "id": "10119040702A",
      "lat": "31.15999",
      "lon": "120.68000",
      "adm2": "苏州",
      "adm1": "苏州",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "86",
      "fxLink": "-999"
    }
  ]
}

POI范围搜索

// 北京市中心附近5公里景点 
// https://geoapi.qweather.com/v2/poi/range?location=116.40528,39.90498&type=scenic&radius=10&key=xxx
// 请将示例请求URL中的KEY更换成你自己的KEY

{
  "status": "200",
  "poi": [
    {
      "name": "中山公园",
      "id": "10101010016A",
      "lat": "39.90999985",
      "lon": "116.38999939",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "86",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "故宫博物院",
      "id": "10101010018A",
      "lat": "39.90999985",
      "lon": "116.38999939",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "67",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "北京市规划展览馆",
      "id": "10101010002A",
      "lat": "39.88999939",
      "lon": "116.40000153",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "68",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "老舍茶馆",
      "id": "10101010021A",
      "lat": "39.88999939",
      "lon": "116.38999939",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "86",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "景山公园",
      "id": "10101010012A",
      "lat": "39.91999817",
      "lon": "116.38999939",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "67",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "北京明城墙遗址公园",
      "id": "10101010001A",
      "lat": "39.90000153",
      "lon": "116.43000031",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "70",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "明城墙遗址公园",
      "id": "10101010003A",
      "lat": "39.90000153",
      "lon": "116.43000031",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "85",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "北海公园",
      "id": "10101010010A",
      "lat": "39.91999817",
      "lon": "116.37999725",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "68",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "天坛公园",
      "id": "10101010004A",
      "lat": "39.88000107",
      "lon": "116.41000366",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "68",
      "fxLink": "http://hfx.link/1"
    },
    {
      "name": "南锣鼓巷",
      "id": "10101010005A",
      "lat": "39.93000031",
      "lon": "116.40000153",
      "adm2": "北京",
      "adm1": "北京",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "scenic",
      "rank": "86",
      "fxLink": "http://hfx.link/1"
    }
  ],
  "refer": {
    "sources": [
      "qweather.com"
    ],
    "license": [
      "commercial license"
    ]
  }
}