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.

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