City Lookup

Weather data is based on geographic location, so you need to know the specific location information before you can get the weather.

With the GeoAPI - City Lookup, you can get the basic information of the city, including the Location ID of the city (you need this ID to get the weather), multilingual name, latitude and longitude, time zone, altitude, rank, administrative, etc.

In addition, GeoAPI - City Lookup can also help you to implement fuzzy search in your APP, users only need to type 1 or 2 words to get results.

GeoAPI is free for the first 50,000 calls per day for each account, more calls refer to price

Request URL #

https://geoapi.qweather.com/v2/city/lookup?[params]

Request Parameters #

All parameters are separated by &. If no optional parameters are set, the default value will be used.

location

The location to be queried, support text, LocationID, comma-separated longitude and latitude, Adcode(Chinese cities only).

For example: location=beijing or location=116.41,39.92

Fuzzy search, when the location passed as text, fuzzy search is supported, users can only enter a part of the city name to search, at least one Chinese character or 2 characters, and the results are sorted by correlation and Rank. It is easy for developers or users to choose which city they need to see the weather. For example, location=bei will return some of the most relevant results to bei, including Beirut in Lebanon and Beijing in China

Duplicate name, when the location is passed as text, cities with the same name may appear, such as Xi’an in Shaanxi Province, Xi’an District under Liaoyuan City in Jilin Province, and Xi’an District under Mudanjiang City in Heilongjiang Province. At this time, all results will be returned according to the Rank. In this case, you can use the adm parameter to further determine the city or region that needs to be queried, for example, location=Xi’an&adm=Heilongjiang

key

API authentication key, please refer to How To Get Your Key. Support Signature Authentication.

For example: key=12334567890ABC

adm

Superior administrative divisions of a city, useful for excluding cities with similar names or for filtering results.

For example adm = beijing

If with adm, like location=chaoyang&adm=beijing, the returned results only include Chaoyang District in Beijing, not Chaoyang City in Liaoning Province

If without adm, like location=chaoyang, the returned results include Chaoyang District in Beijing, Chaoyang City in Liaoning Province, and Chaoyang District in Changchun City

range

Set to search only within a certain country. The country name needs to use country code ISO 3166.

world Around the world, default
cn China
us United States
fr France
uk United Kingdom
ru Russia
See more country code

number

Number of the results in response, from 1 to 20, 10 is the default

lang

Multi-language setting, if data does not match the language you set, it will return results in English or its native language.

zh Chinese, default
en English
fr French
es Spanish
ja Japanese
ko Korean
See more language code

Response #

// Lookup the keyword "beij" 
// https://geoapi.qweather.com/v2/city/lookup?location=beij&lang=en&key=YOUR_KEY

{
  "code": "200",
  "location": [
    {
      "name": "Beijing",
      "id": "101010100",
      "lat": "39.90498",
      "lon": "116.40528",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "10",
      "fxLink": "http://hfx.link/2ax1"
    },
    {
      "name": "Haidian",
      "id": "101010200",
      "lat": "39.95607",
      "lon": "116.31031",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "15",
      "fxLink": "http://hfx.link/2ay1"
    },
    {
      "name": "Chaoyang",
      "id": "101010300",
      "lat": "39.92148",
      "lon": "116.48641",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "15",
      "fxLink": "http://hfx.link/2az1"
    },
    {
      "name": "Changping",
      "id": "101010700",
      "lat": "40.21808",
      "lon": "116.23590",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "http://hfx.link/2b31"
    },
    {
      "name": "Fangshan",
      "id": "101011200",
      "lat": "39.73553",
      "lon": "116.13916",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "http://hfx.link/2b81"
    },
    {
      "name": "Tongzhou",
      "id": "101010600",
      "lat": "39.90248",
      "lon": "116.65859",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "http://hfx.link/2b21"
    },
    {
      "name": "Fengtai",
      "id": "101010900",
      "lat": "39.86364",
      "lon": "116.28696",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "25",
      "fxLink": "http://hfx.link/2b51"
    },
    {
      "name": "Daxing",
      "id": "101011100",
      "lat": "39.72890",
      "lon": "116.33803",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "25",
      "fxLink": "http://hfx.link/2b71"
    },
    {
      "name": "Yanqing",
      "id": "101010800",
      "lat": "40.46532",
      "lon": "115.98500",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "33",
      "fxLink": "http://hfx.link/2b41"
    },
    {
      "name": "Pinggu",
      "id": "101011500",
      "lat": "40.14478",
      "lon": "117.11233",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "33",
      "fxLink": "http://hfx.link/2bb1"
    }
  ],
  "refer": {
    "sources": [
      "qweather.com"
    ],
    "license": [
      "commercial license"
    ]
  }
}

Parameters	Description
`code`	API status code, please refer to Status Code
`location.name`	Location Name
`location.id`	Location ID
`location.lat`	Latitude of the location
`location.lon`	Longitude of the location
`location.adm2`	Name of the superior administrative division of the location
`location.adm1`	The first-level administrative area of the location
`location.country`	Country name of the location
`location.tz`	Location timezone
`location.utcOffset`	The number of hours offset between local time and UTC time, refer to UTC Offset
`location.isDst`	Is the location currently on daylight saving time `1` in daylight saving time `0` not in daylight saving time
`location.type`	Location type
`location.rank`	Location Rank
`location.fxLink`	Responsive web page of this location, easy to embed in your website or APP
`refer.sources`	Data source and other statements, may be null
`refer.license`	Data license, may be null