Top City

Top City API can get a list of popular cities around the world.

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/top?[params]

Request Parameters #

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

key

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

For example: key=12334567890ABC

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 #

// Top 5 cities in China 
// https://geoapi.qweather.com/v2/city/top?number=5&range=cn&lang=en&key=YOUR_KEY

{
  "code": "200",
  "topCityList": [
    {
      "name": "Yuhang",
      "id": "101210106",
      "lat": "30.42118",
      "lon": "120.30173",
      "adm2": "Hangzhou",
      "adm1": "Zhejiang",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "25",
      "fxLink": "http://hfx.link/32t1"
    },
    {
      "name": "Jiading",
      "id": "101020500",
      "lat": "31.38352",
      "lon": "121.25033",
      "adm2": "Shanghai",
      "adm1": "Shanghai",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "http://hfx.link/2bf1"
    },
    {
      "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": "Xiaoshan",
      "id": "101210102",
      "lat": "30.16293",
      "lon": "120.27069",
      "adm2": "Hangzhou",
      "adm1": "Zhejiang",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "23",
      "fxLink": "http://hfx.link/32p1"
    },
    {
      "name": "Jianggan",
      "id": "101210111",
      "lat": "30.26660",
      "lon": "120.20263",
      "adm2": "Hangzhou",
      "adm1": "Zhejiang",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "25",
      "fxLink": "http://hfx.link/1tvn1"
    }
  ],
  "refer": {
    "sources": [
      "qweather.com"
    ],
    "license": [
      "commercial license"
    ]
  }
}

Parameters	Description
`code`	API status code, please refer to Status Code
`topCityList.name`	Location Name
`topCityList.id`	Location ID
`topCityList.lat`	Latitude of the location
`topCityList.lon`	Longitude of the location
`topCityList.adm2`	Name of the superior administrative division of the location
`topCityList.adm1`	The first-level administrative area of the location
`topCityList.country`	Country name of the location
`topCityList.tz`	Location timezone
`topCityList.utcOffset`	The number of hours offset between local time and UTC time, refer to UTC Offset
`topCityList.isDst`	Is the location currently on daylight saving time `1` in daylight saving time `0` not in daylight saving time
`topCityList.type`	Location type
`topCityList.rank`	Location Rank
`topCityList.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