Docs
Open Lodol
DocumentationIntegrationsAPI

countries.dev

App · Misc References · 34 actions

Look up country data (ISO, numeric and IOC codes, capitals, currencies, languages, time zones, calling codes, neighbours and flags), search cities and places, resolve postal codes, measure distances and geolocate IP addresses with countries.dev's keyless public API. No account or API key required.

Actions

ActionWhat it does
Filter countries by areaList the countries whose area in square kilometres falls within a range.
Filter countries by calling codeList the countries reachable under an international calling code, e.g. 1 or 44.
Filter countries by currencyList the countries that use a currency, given its ISO 4217 code.
Filter countries by demonymList the countries whose people are called by a demonym, e.g. French or Australian (exact match, case-insensitive).
Filter countries by independenceList the independent states, or the dependent territories (such as Puerto Rico or Greenland), by UN independence status.
Filter countries by languageList the countries that speak a language, given its ISO 639 code.
Filter countries by populationList the countries whose population falls within a range.
Filter countries by regionList the countries in a region, e.g. Africa, Americas, Asia, Europe or Oceania.
Filter countries by subregionList the countries in a subregion, e.g. Northern Europe, Caribbean or South-Eastern Asia.
Filter countries by time zoneList the countries that observe a UTC offset, e.g. UTC+02:00 or UTC-05:00.
Filter countries by top-level domainList the countries that own an internet top-level domain, e.g. .uk or .de.
Find nearest citiesList the cities closest to a latitude and longitude, nearest first, each with its distance in kilometres.
Find nearest placesList the GeoNames features of any kind closest to a latitude and longitude, nearest first, each with its distance in kilometres.
Geolocate an IP addressResolve the country an IPv4 or IPv6 address is located in, with the full country record.
Geolocate IP addresses in bulkResolve the countries of up to 100 IPv4 or IPv6 addresses in one call.
Get cityGet one city by its GeoNames id, as returned by Search cities.
Get country by codeLook up a single country by its ISO 3166 alpha-2 or alpha-3 code (for example, US or USA).
Get country by IOC codeLook up a single country by its International Olympic Committee code (for example, GER for Germany), as used in sports results.
Get country by numeric codeLook up a single country by its ISO 3166-1 numeric code (for example, 840 for the United States).
Get distance between two pointsGreat-circle distance between two cities (by GeoNames id) or two coordinates, in kilometres and miles.
Get neighbouring countriesList the countries that share a land border with a country, given its name or ISO code.
Get placeGet one GeoNames feature by its id, as returned by Search places.
Get random countryGet one randomly chosen country.
List countriesList every country, with optional field selection, sorting and paging to keep the payload small.
List currenciesList every currency in circulation, with its ISO 4217 code, name and symbol.
List languagesList every language spoken across all countries, with its ISO 639 codes and native name.
List regionsList every region name (Africa, Americas, Asia, Europe, Oceania, ...), alphabetically.
List subregionsList every subregion name (Caribbean, Northern Europe, South-Eastern Asia, ...), alphabetically.
List time zonesList every UTC offset observed somewhere in the world, from UTC-12:00 to UTC+14:00, with how many countries observe each.
Look up postal codeResolve a postal or ZIP code in a country to its town, state/region and approximate coordinates.
Search citiesSearch the world's cities (populated places over 15,000 people, plus capitals) by name and/or country, largest first.
Search countries by capitalFind the countries whose capital city name contains the given text, e.g. 'paris' or 'wash'.
Search countries by nameSearch for countries whose name contains the given text.
Search placesSearch the full GeoNames gazetteer of some 12 million features worldwide (cities, towns, mountains, rivers, parks, airports, ...) by name, country and kind, largest first.

Filter countries by area

List the countries whose area in square kilometres falls within a range. Give a minimum, a maximum or both (inclusive).

Inputs

Minimum area (km²)min_areanumber
Smallest area to include, in square kilometres.At least 0.
Maximum area (km²)max_areanumber
Largest area to include, in square kilometres.At least 0.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by calling code

List the countries reachable under an international calling code, e.g. 1 or 44.

Inputs

Calling codecalling_codetextRequired
International calling code, e.g. '1' or '44'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by currency

List the countries that use a currency, given its ISO 4217 code.

Inputs

Currency codecurrencytextRequired
ISO 4217 currency code, e.g. 'USD' or 'EUR'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by demonym

List the countries whose people are called by a demonym, e.g. French or Australian (exact match, case-insensitive).

Inputs

DemonymdemonymtextRequired
What a national is called, e.g. 'French'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by independence

List the independent states, or the dependent territories (such as Puerto Rico or Greenland), by UN independence status.

Inputs

Independentindependenttrue/falseRequired
On to list independent states; off to list dependent territories.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by language

List the countries that speak a language, given its ISO 639 code.

Inputs

Language codelanguagetextRequired
ISO 639 language code, e.g. 'en' or 'es'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by population

List the countries whose population falls within a range. Give a minimum, a maximum or both (inclusive).

Inputs

Minimum populationmin_populationnumber
Lowest population to include, e.g. 1000000.At least 0.
Maximum populationmax_populationnumber
Highest population to include, e.g. 5000000.At least 0.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by region

List the countries in a region, e.g. Africa, Americas, Asia, Europe or Oceania.

Inputs

RegionregiontextRequired
Region name, e.g. 'Europe'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by subregion

List the countries in a subregion, e.g. Northern Europe, Caribbean or South-Eastern Asia. Use List subregions for the exact names.

Inputs

SubregionsubregiontextRequired
Subregion name, e.g. 'Northern Europe'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by time zone

List the countries that observe a UTC offset, e.g. UTC+02:00 or UTC-05:00. Use List time zones for the offsets in use.

Inputs

UTC offsettimezonetextRequired
UTC offset as countries.dev writes it, e.g. 'UTC+02:00' or 'UTC'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Filter countries by top-level domain

List the countries that own an internet top-level domain, e.g. .uk or .de. The leading dot is optional.

Inputs

Top-level domaintldtextRequired
Country-code top-level domain, e.g. '.uk' or 'uk'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Find nearest cities

List the cities closest to a latitude and longitude, nearest first, each with its distance in kilometres.

Inputs

LatitudelatitudenumberRequired
Latitude of the point, e.g. 48.8534.From -90 to 90.
LongitudelongitudenumberRequired
Longitude of the point, e.g. 2.3488.From -180 to 180.
Limitlimitnumber
Maximum number of results, 1 to 100. 20 if left empty.From 1 to 100.

Outputs

citieslist
Matching cities, largest (or nearest) first
Example output
{
  "cities": [
    {
      "admin1Code": "11",
      "asciiName": "Paris",
      "countryCode": "FR",
      "distanceKm": 0.4,
      "featureCode": "PPLC",
      "geonameId": 2988507,
      "latitude": 48.85341,
      "longitude": 2.3488,
      "name": "Paris",
      "population": 2138551,
      "timezone": "Europe/Paris"
    }
  ]
}

Find nearest places

List the GeoNames features of any kind closest to a latitude and longitude, nearest first, each with its distance in kilometres.

Inputs

LatitudelatitudenumberRequired
Latitude of the point, e.g. 48.8534.From -90 to 90.
LongitudelongitudenumberRequired
Longitude of the point, e.g. 2.3488.From -180 to 180.
Limitlimitnumber
Maximum number of results, 1 to 100. 20 if left empty.From 1 to 100.

Outputs

placeslist
Matching places, largest (or nearest) first
Example output
{
  "places": [
    {
      "admin1Code": "06",
      "asciiName": "Kilimanjaro",
      "countryCode": "TZ",
      "distanceKm": 1.2,
      "featureClass": "T",
      "featureCode": "MT",
      "geonameId": 157452,
      "latitude": -3.07583,
      "longitude": 37.35333,
      "name": "Kilimanjaro",
      "population": 0,
      "timezone": "Africa/Dar_es_Salaam"
    }
  ]
}

Geolocate an IP address

Resolve the country an IPv4 or IPv6 address is located in, with the full country record.

Inputs

IP addressiptextRequired
The IPv4 or IPv6 address to geolocate, e.g. '8.8.8.8'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.

Outputs

locationobject
Example output
{
  "location": {
    "country": {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    },
    "countryCode": "US",
    "ip": "8.8.8.8"
  }
}

Geolocate IP addresses in bulk

Resolve the countries of up to 100 IPv4 or IPv6 addresses in one call. Every address must be valid, or the whole call fails.

Inputs

IP addressesipslistRequired
Up to 100 IPv4 or IPv6 addresses. Add them one by one or pass a list from an earlier step. Pasted text separated by commas, spaces or new lines works too.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.

Outputs

locationslist
One entry per address, in the order given
Example output
{
  "locations": [
    {
      "country": {
        "alpha2Code": "US",
        "alpha3Code": "USA",
        "area": 9629091,
        "borders": [
          "CAN",
          "MEX"
        ],
        "callingCodes": [
          "1"
        ],
        "capital": "Washington, D.C.",
        "cioc": "USA",
        "currencies": [
          {
            "code": "USD",
            "name": "United States dollar",
            "symbol": "$"
          }
        ],
        "demonym": "American",
        "flag": "\ud83c\uddfa\ud83c\uddf8",
        "flags": {
          "png": "https://flagcdn.com/w320/us.png",
          "svg": "https://flagcdn.com/us.svg"
        },
        "gini": 41.4,
        "independent": true,
        "languages": [
          {
            "iso639_1": "en",
            "iso639_2": "eng",
            "name": "English",
            "nativeName": "English"
          }
        ],
        "latlng": [
          38,
          -97
        ],
        "name": "United States of America",
        "nativeName": "United States",
        "numericCode": "840",
        "population": 329484123,
        "populationDensity": 34.22,
        "region": "Americas",
        "subregion": "Northern America",
        "timezones": [
          "UTC-12:00",
          "UTC-11:00",
          "UTC-10:00",
          "UTC-09:00",
          "UTC-08:00"
        ],
        "topLevelDomain": [
          ".us"
        ]
      },
      "countryCode": "US",
      "ip": "8.8.8.8"
    }
  ]
}

Get city

Get one city by its GeoNames id, as returned by Search cities.

Inputs

GeoNames idgeoname_idnumberRequired
The GeoNames id, as returned by a search (e.g. 2988507 for Paris).

Outputs

cityobject
Example output
{
  "city": {
    "admin1Code": "11",
    "asciiName": "Paris",
    "countryCode": "FR",
    "featureCode": "PPLC",
    "geonameId": 2988507,
    "latitude": 48.85341,
    "longitude": 2.3488,
    "name": "Paris",
    "population": 2138551,
    "timezone": "Europe/Paris"
  }
}

Get country by code

Look up a single country by its ISO 3166 alpha-2 or alpha-3 code (for example, US or USA).

Inputs

Country codecodetextRequired
ISO 3166 alpha-2 or alpha-3 code, e.g. 'US' or 'USA'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Full recordfulltrue/false
Return the complete record, including the bulky translations, altSpellings, maps and regionalBlocs fields that are left out by default.

Outputs

countryobject
Example output
{
  "country": {
    "alpha2Code": "US",
    "alpha3Code": "USA",
    "area": 9629091,
    "borders": [
      "CAN",
      "MEX"
    ],
    "callingCodes": [
      "1"
    ],
    "capital": "Washington, D.C.",
    "cioc": "USA",
    "currencies": [
      {
        "code": "USD",
        "name": "United States dollar",
        "symbol": "$"
      }
    ],
    "demonym": "American",
    "flag": "\ud83c\uddfa\ud83c\uddf8",
    "flags": {
      "png": "https://flagcdn.com/w320/us.png",
      "svg": "https://flagcdn.com/us.svg"
    },
    "gini": 41.4,
    "independent": true,
    "languages": [
      {
        "iso639_1": "en",
        "iso639_2": "eng",
        "name": "English",
        "nativeName": "English"
      }
    ],
    "latlng": [
      38,
      -97
    ],
    "name": "United States of America",
    "nativeName": "United States",
    "numericCode": "840",
    "population": 329484123,
    "populationDensity": 34.22,
    "region": "Americas",
    "subregion": "Northern America",
    "timezones": [
      "UTC-12:00",
      "UTC-11:00",
      "UTC-10:00",
      "UTC-09:00",
      "UTC-08:00"
    ],
    "topLevelDomain": [
      ".us"
    ]
  }
}

Get country by IOC code

Look up a single country by its International Olympic Committee code (for example, GER for Germany), as used in sports results.

Inputs

IOC codecodetextRequired
International Olympic Committee code, e.g. 'GER' or 'USA'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.

Outputs

countryobject
Example output
{
  "country": {
    "alpha2Code": "US",
    "alpha3Code": "USA",
    "area": 9629091,
    "borders": [
      "CAN",
      "MEX"
    ],
    "callingCodes": [
      "1"
    ],
    "capital": "Washington, D.C.",
    "cioc": "USA",
    "currencies": [
      {
        "code": "USD",
        "name": "United States dollar",
        "symbol": "$"
      }
    ],
    "demonym": "American",
    "flag": "\ud83c\uddfa\ud83c\uddf8",
    "flags": {
      "png": "https://flagcdn.com/w320/us.png",
      "svg": "https://flagcdn.com/us.svg"
    },
    "gini": 41.4,
    "independent": true,
    "languages": [
      {
        "iso639_1": "en",
        "iso639_2": "eng",
        "name": "English",
        "nativeName": "English"
      }
    ],
    "latlng": [
      38,
      -97
    ],
    "name": "United States of America",
    "nativeName": "United States",
    "numericCode": "840",
    "population": 329484123,
    "populationDensity": 34.22,
    "region": "Americas",
    "subregion": "Northern America",
    "timezones": [
      "UTC-12:00",
      "UTC-11:00",
      "UTC-10:00",
      "UTC-09:00",
      "UTC-08:00"
    ],
    "topLevelDomain": [
      ".us"
    ]
  }
}

Get country by numeric code

Look up a single country by its ISO 3166-1 numeric code (for example, 840 for the United States). Leading zeros are optional.

Inputs

Numeric codecodetextRequired
ISO 3166-1 numeric code, e.g. '840' or '004'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.

Outputs

countryobject
Example output
{
  "country": {
    "alpha2Code": "US",
    "alpha3Code": "USA",
    "area": 9629091,
    "borders": [
      "CAN",
      "MEX"
    ],
    "callingCodes": [
      "1"
    ],
    "capital": "Washington, D.C.",
    "cioc": "USA",
    "currencies": [
      {
        "code": "USD",
        "name": "United States dollar",
        "symbol": "$"
      }
    ],
    "demonym": "American",
    "flag": "\ud83c\uddfa\ud83c\uddf8",
    "flags": {
      "png": "https://flagcdn.com/w320/us.png",
      "svg": "https://flagcdn.com/us.svg"
    },
    "gini": 41.4,
    "independent": true,
    "languages": [
      {
        "iso639_1": "en",
        "iso639_2": "eng",
        "name": "English",
        "nativeName": "English"
      }
    ],
    "latlng": [
      38,
      -97
    ],
    "name": "United States of America",
    "nativeName": "United States",
    "numericCode": "840",
    "population": 329484123,
    "populationDensity": 34.22,
    "region": "Americas",
    "subregion": "Northern America",
    "timezones": [
      "UTC-12:00",
      "UTC-11:00",
      "UTC-10:00",
      "UTC-09:00",
      "UTC-08:00"
    ],
    "topLevelDomain": [
      ".us"
    ]
  }
}

Get distance between two points

Great-circle distance between two cities (by GeoNames id) or two coordinates, in kilometres and miles. Give both city ids, or all four coordinates.

Inputs

From city (GeoNames id)from_city_idnumber
GeoNames id of the origin city, e.g. 2988507 for Paris.
To city (GeoNames id)to_city_idnumber
GeoNames id of the destination city, e.g. 2643743 for London.
From latitudefrom_latitudenumber
Origin latitude, when not using city ids.From -90 to 90.
From longitudefrom_longitudenumber
Origin longitude, when not using city ids.From -180 to 180.
To latitudeto_latitudenumber
Destination latitude, when not using city ids.From -90 to 90.
To longitudeto_longitudenumber
Destination longitude, when not using city ids.From -180 to 180.

Outputs

distanceKmnumber
Great-circle distance in kilometres
distanceMilesnumber
Great-circle distance in miles
fromobject
The endpoint: the full city record when looked up by GeoNames id, or just its latitude and longitude when given as coordinates
toobject
The endpoint: the full city record when looked up by GeoNames id, or just its latitude and longitude when given as coordinates
Example output
{
  "distanceKm": 343.8,
  "distanceMiles": 213.6,
  "from": {
    "admin1Code": "11",
    "asciiName": "Paris",
    "countryCode": "FR",
    "featureCode": "PPLC",
    "geonameId": 2988507,
    "latitude": 48.85341,
    "longitude": 2.3488,
    "name": "Paris",
    "population": 2138551,
    "timezone": "Europe/Paris"
  },
  "to": {
    "admin1Code": "ENG",
    "asciiName": "London",
    "countryCode": "GB",
    "featureCode": "PPLC",
    "geonameId": 2643743,
    "latitude": 51.50853,
    "longitude": -0.12574,
    "name": "London",
    "population": 8961989,
    "timezone": "Europe/London"
  }
}

Get neighbouring countries

List the countries that share a land border with a country, given its name or ISO code. An island nation returns an empty list.

Inputs

CountrycountrytextRequired
The country's exact name (e.g. 'France') or its ISO 3166 alpha-2 / alpha-3 code (e.g. 'FR' or 'FRA').
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Get place

Get one GeoNames feature by its id, as returned by Search places.

Inputs

GeoNames idgeoname_idnumberRequired
The GeoNames id, as returned by a search (e.g. 2988507 for Paris).

Outputs

placeobject
Example output
{
  "place": {
    "admin1Code": "06",
    "asciiName": "Kilimanjaro",
    "countryCode": "TZ",
    "featureClass": "T",
    "featureCode": "MT",
    "geonameId": 157452,
    "latitude": -3.07583,
    "longitude": 37.35333,
    "name": "Kilimanjaro",
    "population": 0,
    "timezone": "Africa/Dar_es_Salaam"
  }
}

Get random country

Get one randomly chosen country. A different country comes back on every run.

Inputs

Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.

Outputs

countryobject
Example output
{
  "country": {
    "alpha2Code": "US",
    "alpha3Code": "USA",
    "area": 9629091,
    "borders": [
      "CAN",
      "MEX"
    ],
    "callingCodes": [
      "1"
    ],
    "capital": "Washington, D.C.",
    "cioc": "USA",
    "currencies": [
      {
        "code": "USD",
        "name": "United States dollar",
        "symbol": "$"
      }
    ],
    "demonym": "American",
    "flag": "\ud83c\uddfa\ud83c\uddf8",
    "flags": {
      "png": "https://flagcdn.com/w320/us.png",
      "svg": "https://flagcdn.com/us.svg"
    },
    "gini": 41.4,
    "independent": true,
    "languages": [
      {
        "iso639_1": "en",
        "iso639_2": "eng",
        "name": "English",
        "nativeName": "English"
      }
    ],
    "latlng": [
      38,
      -97
    ],
    "name": "United States of America",
    "nativeName": "United States",
    "numericCode": "840",
    "population": 329484123,
    "populationDensity": 34.22,
    "region": "Americas",
    "subregion": "Northern America",
    "timezones": [
      "UTC-12:00",
      "UTC-11:00",
      "UTC-10:00",
      "UTC-09:00",
      "UTC-08:00"
    ],
    "topLevelDomain": [
      ".us"
    ]
  }
}

List countries

List every country, with optional field selection, sorting and paging to keep the payload small.

Inputs

Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Full recordfulltrue/false
Return the complete record, including the bulky translations, altSpellings, maps and regionalBlocs fields that are left out by default.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

List currencies

List every currency in circulation, with its ISO 4217 code, name and symbol.

Inputs

None.

Outputs

currencieslist
Every currency, sorted by code
Example output
{
  "currencies": [
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "\u20ac"
    },
    {
      "code": "USD",
      "name": "United States dollar",
      "symbol": "$"
    }
  ]
}

List languages

List every language spoken across all countries, with its ISO 639 codes and native name.

Inputs

None.

Outputs

languageslist
Every language, sorted by name
Example output
{
  "languages": [
    {
      "iso639_1": "en",
      "iso639_2": "eng",
      "name": "English",
      "nativeName": "English"
    },
    {
      "iso639_1": "es",
      "iso639_2": "spa",
      "name": "Spanish",
      "nativeName": "Espa\u00f1ol"
    }
  ]
}

List regions

List every region name (Africa, Americas, Asia, Europe, Oceania, ...), alphabetically.

Inputs

None.

Outputs

regionslist
Region names
Example output
{
  "regions": [
    "Africa",
    "Americas",
    "Asia",
    "Europe",
    "Oceania"
  ]
}

List subregions

List every subregion name (Caribbean, Northern Europe, South-Eastern Asia, ...), alphabetically.

Inputs

None.

Outputs

subregionslist
Subregion names
Example output
{
  "subregions": [
    "Caribbean",
    "Northern Europe",
    "South-Eastern Asia"
  ]
}

List time zones

List every UTC offset observed somewhere in the world, from UTC-12:00 to UTC+14:00, with how many countries observe each.

Inputs

None.

Outputs

timezoneslist
Every UTC offset, from UTC-12:00 to UTC+14:00
Example output
{
  "timezones": [
    {
      "countries": 13,
      "timezone": "UTC-05:00"
    },
    {
      "countries": 50,
      "timezone": "UTC+01:00"
    }
  ]
}

Look up postal code

Resolve a postal or ZIP code in a country to its town, state/region and approximate coordinates. Covers about 100 countries. A code with no match fails with HTTP 404.

Inputs

Country codecountrytextRequired
ISO 3166-1 alpha-2 code of the country, e.g. 'US'.
Postal codepostal_codetextRequired
The postal / ZIP code, e.g. '10001' or 'SW1A'.

Outputs

placeslist
Every place the code maps to (usually one)
Example output
{
  "places": [
    {
      "accuracy": 4,
      "admin1": {
        "code": "NY",
        "name": "New York"
      },
      "admin2": {
        "code": "061",
        "name": "New York"
      },
      "countryCode": "US",
      "latitude": 40.7484,
      "longitude": -73.9967,
      "placeName": "New York",
      "postalCode": "10001"
    }
  ]
}

Search cities

Search the world's cities (populated places over 15,000 people, plus capitals) by name and/or country, largest first.

Inputs

City nameqtext
Text the city name must contain, e.g. 'paris'.
Country codecountrytext
ISO 3166-1 alpha-2 code to search within, e.g. 'FR'.
Limitlimitnumber
Maximum number of results, 1 to 100. 20 if left empty.From 1 to 100.

Outputs

citieslist
Matching cities, largest (or nearest) first
Example output
{
  "cities": [
    {
      "admin1Code": "11",
      "asciiName": "Paris",
      "countryCode": "FR",
      "featureCode": "PPLC",
      "geonameId": 2988507,
      "latitude": 48.85341,
      "longitude": 2.3488,
      "name": "Paris",
      "population": 2138551,
      "timezone": "Europe/Paris"
    }
  ]
}

Search countries by capital

Find the countries whose capital city name contains the given text, e.g. 'paris' or 'wash'.

Inputs

Capital citycapitaltextRequired
Full or partial capital city name, e.g. 'Paris'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Search countries by name

Search for countries whose name contains the given text.

Inputs

Country namenametextRequired
Full or partial country name, e.g. 'united' or 'canada'.
Fieldsfieldstext
Optional comma-separated list of fields to return, to keep the payload small (for example, name,capital,flag). Naming a field also requests the ones left out by default (translations, altSpellings, maps, regionalBlocs). Leave empty for the standard country object.
Sort bysorttext
Optional field to sort by, e.g. 'population', 'area' or 'name'.
Orderordertext
Sort direction. Ascending unless 'desc' is chosen.One of: asc (Ascending), desc (Descending).
Limitlimitnumber
Maximum number of countries to return.
Offsetoffsetnumber
Number of countries to skip before returning results, for paging.

Outputs

countrieslist
Matching countries
Example output
{
  "countries": [
    {
      "alpha2Code": "US",
      "alpha3Code": "USA",
      "area": 9629091,
      "borders": [
        "CAN",
        "MEX"
      ],
      "callingCodes": [
        "1"
      ],
      "capital": "Washington, D.C.",
      "cioc": "USA",
      "currencies": [
        {
          "code": "USD",
          "name": "United States dollar",
          "symbol": "$"
        }
      ],
      "demonym": "American",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "flags": {
        "png": "https://flagcdn.com/w320/us.png",
        "svg": "https://flagcdn.com/us.svg"
      },
      "gini": 41.4,
      "independent": true,
      "languages": [
        {
          "iso639_1": "en",
          "iso639_2": "eng",
          "name": "English",
          "nativeName": "English"
        }
      ],
      "latlng": [
        38,
        -97
      ],
      "name": "United States of America",
      "nativeName": "United States",
      "numericCode": "840",
      "population": 329484123,
      "populationDensity": 34.22,
      "region": "Americas",
      "subregion": "Northern America",
      "timezones": [
        "UTC-12:00",
        "UTC-11:00",
        "UTC-10:00",
        "UTC-09:00",
        "UTC-08:00"
      ],
      "topLevelDomain": [
        ".us"
      ]
    }
  ]
}

Search places

Search the full GeoNames gazetteer of some 12 million features worldwide (cities, towns, mountains, rivers, parks, airports, ...) by name, country and kind, largest first.

Inputs

Place nameqtext
Text the place name must contain, e.g. 'kilimanjaro' (accents and punctuation are ignored).
Country codecountrytext
ISO 3166-1 alpha-2 code to search within, e.g. 'TZ'.
Kind of placefeature_classtext
GeoNames feature class to restrict the search to.One of: A (A — Administrative area (country, state, region)), P (P — Populated place (city, town, village)), H (H — Water (lake, river, sea)), T (T — Terrain (mountain, hill, valley)), L (L — Area (park, reserve, locality)), S (S — Spot (building, airport, landmark)), R (R — Road or railroad), V (V — Vegetation (forest, grassland)), U (U — Undersea feature).
Limitlimitnumber
Maximum number of results, 1 to 100. 20 if left empty.From 1 to 100.

Outputs

placeslist
Matching places, largest (or nearest) first
Example output
{
  "places": [
    {
      "admin1Code": "06",
      "asciiName": "Kilimanjaro",
      "countryCode": "TZ",
      "featureClass": "T",
      "featureCode": "MT",
      "geonameId": 157452,
      "latitude": -3.07583,
      "longitude": 37.35333,
      "name": "Kilimanjaro",
      "population": 0,
      "timezone": "Africa/Dar_es_Salaam"
    }
  ]
}

CosmyDay Astrology

Previous Page

Country.is

Next Page

On this page

ActionsFilter countries by areaFilter countries by calling codeFilter countries by currencyFilter countries by demonymFilter countries by independenceFilter countries by languageFilter countries by populationFilter countries by regionFilter countries by subregionFilter countries by time zoneFilter countries by top-level domainFind nearest citiesFind nearest placesGeolocate an IP addressGeolocate IP addresses in bulkGet cityGet country by codeGet country by IOC codeGet country by numeric codeGet distance between two pointsGet neighbouring countriesGet placeGet random countryList countriesList currenciesList languagesList regionsList subregionsList time zonesLook up postal codeSearch citiesSearch countries by capitalSearch countries by nameSearch places