# countries.dev

> 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.

App · Misc References · 34 actions. Web page: https://docs.lodol.com/docs/integrations/countries-dev

## Actions

### 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_area`, number): Smallest area to include, in square kilometres. At least 0.
- Maximum area (km²) (`max_area`, number): Largest area to include, in square kilometres. At least 0.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 code (`calling_code`, text, required): International calling code, e.g. '1' or '44'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 code (`currency`, text, required): ISO 4217 currency code, e.g. 'USD' or 'EUR'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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**

- Demonym (`demonym`, text, required): What a national is called, e.g. 'French'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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**

- Independent (`independent`, true/false, required): On to list independent states; off to list dependent territories.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 code (`language`, text, required): ISO 639 language code, e.g. 'en' or 'es'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 population (`min_population`, number): Lowest population to include, e.g. 1000000. At least 0.
- Maximum population (`max_population`, number): Highest population to include, e.g. 5000000. At least 0.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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**

- Region (`region`, text, required): Region name, e.g. 'Europe'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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**

- Subregion (`subregion`, text, required): Subregion name, e.g. 'Northern Europe'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 offset (`timezone`, text, required): UTC offset as countries.dev writes it, e.g. 'UTC+02:00' or 'UTC'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 domain (`tld`, text, required): Country-code top-level domain, e.g. '.uk' or 'uk'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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**

- Latitude (`latitude`, number, required): Latitude of the point, e.g. 48.8534. From -90 to 90.
- Longitude (`longitude`, number, required): Longitude of the point, e.g. 2.3488. From -180 to 180.
- Limit (`limit`, number): Maximum number of results, 1 to 100. 20 if left empty. From 1 to 100.

**Outputs**

- `cities` (list): Matching cities, largest (or nearest) first

**Example output**

```json
{
  "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**

- Latitude (`latitude`, number, required): Latitude of the point, e.g. 48.8534. From -90 to 90.
- Longitude (`longitude`, number, required): Longitude of the point, e.g. 2.3488. From -180 to 180.
- Limit (`limit`, number): Maximum number of results, 1 to 100. 20 if left empty. From 1 to 100.

**Outputs**

- `places` (list): Matching places, largest (or nearest) first

**Example output**

```json
{
  "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 address (`ip`, text, required): The IPv4 or IPv6 address to geolocate, e.g. '8.8.8.8'.
- Fields (`fields`, text): 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**

- `location` (object)

**Example output**

```json
{
  "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 addresses (`ips`, list, required): 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.
- Fields (`fields`, text): 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**

- `locations` (list): One entry per address, in the order given

**Example output**

```json
{
  "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 id (`geoname_id`, number, required): The GeoNames id, as returned by a search (e.g. 2988507 for Paris).

**Outputs**

- `city` (object)

**Example output**

```json
{
  "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 code (`code`, text, required): ISO 3166 alpha-2 or alpha-3 code, e.g. 'US' or 'USA'.
- Fields (`fields`, text): 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 record (`full`, true/false): Return the complete record, including the bulky translations, altSpellings, maps and regionalBlocs fields that are left out by default.

**Outputs**

- `country` (object)

**Example output**

```json
{
  "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 code (`code`, text, required): International Olympic Committee code, e.g. 'GER' or 'USA'.
- Fields (`fields`, text): 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**

- `country` (object)

**Example output**

```json
{
  "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 code (`code`, text, required): ISO 3166-1 numeric code, e.g. '840' or '004'.
- Fields (`fields`, text): 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**

- `country` (object)

**Example output**

```json
{
  "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_id`, number): GeoNames id of the origin city, e.g. 2988507 for Paris.
- To city (GeoNames id) (`to_city_id`, number): GeoNames id of the destination city, e.g. 2643743 for London.
- From latitude (`from_latitude`, number): Origin latitude, when not using city ids. From -90 to 90.
- From longitude (`from_longitude`, number): Origin longitude, when not using city ids. From -180 to 180.
- To latitude (`to_latitude`, number): Destination latitude, when not using city ids. From -90 to 90.
- To longitude (`to_longitude`, number): Destination longitude, when not using city ids. From -180 to 180.

**Outputs**

- `distanceKm` (number): Great-circle distance in kilometres
- `distanceMiles` (number): Great-circle distance in miles
- `from` (object): The endpoint: the full city record when looked up by GeoNames id, or just its latitude and longitude when given as coordinates
- `to` (object): The endpoint: the full city record when looked up by GeoNames id, or just its latitude and longitude when given as coordinates

**Example output**

```json
{
  "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**

- Country (`country`, text, required): The country's exact name (e.g. 'France') or its ISO 3166 alpha-2 / alpha-3 code (e.g. 'FR' or 'FRA').
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 id (`geoname_id`, number, required): The GeoNames id, as returned by a search (e.g. 2988507 for Paris).

**Outputs**

- `place` (object)

**Example output**

```json
{
  "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**

- Fields (`fields`, text): 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**

- `country` (object)

**Example output**

```json
{
  "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**

- Fields (`fields`, text): 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 record (`full`, true/false): Return the complete record, including the bulky translations, altSpellings, maps and regionalBlocs fields that are left out by default.
- Sort by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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**

- `currencies` (list): Every currency, sorted by code

**Example output**

```json
{
  "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**

- `languages` (list): Every language, sorted by name

**Example output**

```json
{
  "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**

- `regions` (list): Region names

**Example output**

```json
{
  "regions": [
    "Africa",
    "Americas",
    "Asia",
    "Europe",
    "Oceania"
  ]
}
```

### List subregions

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

**Inputs**: None.

**Outputs**

- `subregions` (list): Subregion names

**Example output**

```json
{
  "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**

- `timezones` (list): Every UTC offset, from UTC-12:00 to UTC+14:00

**Example output**

```json
{
  "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 code (`country`, text, required): ISO 3166-1 alpha-2 code of the country, e.g. 'US'.
- Postal code (`postal_code`, text, required): The postal / ZIP code, e.g. '10001' or 'SW1A'.

**Outputs**

- `places` (list): Every place the code maps to (usually one)

**Example output**

```json
{
  "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 name (`q`, text): Text the city name must contain, e.g. 'paris'.
- Country code (`country`, text): ISO 3166-1 alpha-2 code to search within, e.g. 'FR'.
- Limit (`limit`, number): Maximum number of results, 1 to 100. 20 if left empty. From 1 to 100.

**Outputs**

- `cities` (list): Matching cities, largest (or nearest) first

**Example output**

```json
{
  "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 city (`capital`, text, required): Full or partial capital city name, e.g. 'Paris'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 name (`name`, text, required): Full or partial country name, e.g. 'united' or 'canada'.
- Fields (`fields`, text): 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 by (`sort`, text): Optional field to sort by, e.g. 'population', 'area' or 'name'.
- Order (`order`, text): Sort direction. Ascending unless 'desc' is chosen. One of: `asc` (Ascending), `desc` (Descending).
- Limit (`limit`, number): Maximum number of countries to return.
- Offset (`offset`, number): Number of countries to skip before returning results, for paging.

**Outputs**

- `countries` (list): Matching countries

**Example output**

```json
{
  "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 name (`q`, text): Text the place name must contain, e.g. 'kilimanjaro' (accents and punctuation are ignored).
- Country code (`country`, text): ISO 3166-1 alpha-2 code to search within, e.g. 'TZ'.
- Kind of place (`feature_class`, text): 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).
- Limit (`limit`, number): Maximum number of results, 1 to 100. 20 if left empty. From 1 to 100.

**Outputs**

- `places` (list): Matching places, largest (or nearest) first

**Example output**

```json
{
  "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"
    }
  ]
}
```