城市信息查询

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

另外,城市搜索也可以帮助你在你的APP中实现模糊搜索,用户只需要输入1-2个字即可获得结果。

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

请求URL #

https://geoapi.qweather.com/v2/city/lookup?[请求参数]

请求参数 #

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

location

需要查询地区的名称,支持文字、以英文逗号分隔的经度,纬度坐标(十进制)、LocationIDAdcode(仅限中国城市)。例如 location=北京location=116.41,39.92

模糊搜索,当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
  • us 美国
  • fr 法国
  • uk 英国
  • ru 俄罗斯
  • 更多国家代码
number

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

lang

多语言设置,默认中文,当数据不匹配你设置的语言时,将返回英文或其本地语言结果。

返回数据 #

# 搜索关键字beij 
// https://geoapi.qweather.com/v2/city/lookup?location=beij&key=你的KEY

{
  "code": "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": "http://hfx.link/2ax1"
    },
    {
      "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": "http://hfx.link/2ay1"
    },
    {
      "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": "http://hfx.link/2az1"
    },
    {
      "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": "http://hfx.link/2b31"
    },
    {
      "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": "http://hfx.link/2b81"
    },
    {
      "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": "http://hfx.link/2b21"
    },
    {
      "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": "http://hfx.link/2b51"
    },
    {
      "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": "http://hfx.link/2b71"
    },
    {
      "name": "延庆",
      "id": "101010800",
      "lat": "40.46532",
      "lon": "115.98500",
      "adm2": "北京",
      "adm1": "北京市",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "33",
      "fxLink": "http://hfx.link/2b41"
    },
    {
      "name": "平谷",
      "id": "101011500",
      "lat": "40.14478",
      "lon": "117.11233",
      "adm2": "北京",
      "adm1": "北京市",
      "country": "中国",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "33",
      "fxLink": "http://hfx.link/2bb1"
    }
  ],
  "refer": {
    "sources": [
      "qweather.com"
    ],
    "license": [
      "commercial license"
    ]
  }
}
参数 描述
code

API状态码,具体含义请参考状态码

location.name

地区/城市名称

location.id

地区/城市ID

location.lat

地区/城市纬度

location.lon

地区/城市经度

location.adm2

地区/城市的上级行政区划名称

location.adm1

地区/城市所属一级行政区域

location.country

地区/城市所属国家名称

location.tz

地区/城市所在时区

location.utcOffset

地区/城市目前与UTC时间偏移的小时数,参考详细说明

location.isDst

地区/城市是否当前处于夏令时
1 表示当前处于夏令时
0 表示当前不是夏令时

location.type

地区/城市的属性

location.rank

地区评分

location.fxLink

该地区的天气预报网页链接,便于嵌入你的网站或应用

refer.sources

原始数据来源,或数据源说明,可能为空

refer.license

数据许可或版权声明,可能为空