GeoDB Cities API

Getting Cities using multiple filters

You can find cities using a combination of different filters simply by specifying them as parameters in the request.  Currently, the following filters are available:

countryIdsOnly cities in these countries (comma-delimited country codes or wikiDataIds)
excludedCountryIdsOnly cities NOT in these countries (comma-delimited country codes or wikiDataIds)
minPopulationOnly cities having at least this population
namePrefixOnly cities whose names start with this prefix
locationOnly cities near this location. Latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD
timeZoneIdsOnly cities in these time-zones (comma-delimited time-zone IDs). Note that you should use the IDs returned by the GeoDB service, as they correctly encode the '/' character. (Alternatively simply replace '/' with a double-underscore:  '__'.)


Here's an example returning cities starting with 'Los', having a minimum population of 100 thousand, and only in the US or Spain:

curl --get --include ',ES&offset=0&limit=10' \
    -H 'X-Mashape-Key: YOUR_API_KEY' \
    -H 'X-Mashape-Host:'

Note that several of the parameters are logically mutually exclusive of each other, and if your request includes them simultaneously, you will quickly be shown the error of your evil ways via a descriptive error response. These are:

  • countryIds, excludedCountryIds  You cannot both include and exclude countries at the same time.
  • location, (countryIds | excludedCountryIds | timeZoneIds)  You cannot include or exclude countries or constrain by time-zones when filtering by location.