REST Countries

https://restcountries.com/v3.1/
Admin
REST Countries is an open-source and free RESTful API that provides comprehensive information about...
Tokens:3,509
Snippets:13
Trust Score:9
Update:1 year ago
Show doc for...
Tokens:
Raw
### GET /v3.1/name/{name}

Source: https://restcountries.com/v3.1/index

Search for countries by their common or official name.

```APIDOC
## GET /v3.1/name/{name}

### Description
Searches for countries based on their name. This endpoint can match either the common or official name of a country.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/name/{name}

### Path Parameters
- **name** (string) - Required - The name of the country to search for.

### Query Parameters
- **fullText** (boolean) - Optional - If set to `true`, requires an exact match of the country's full name.
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/name/eesti
```
```
https://restcountries.com/v3.1/name/aruba?fullText=true
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Estonia",
      "official": "Republic of Estonia"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/capital/{capital}

Source: https://restcountries.com/v3.1/index

Search for countries based on their capital city.

```APIDOC
## GET /v3.1/capital/{capital}

### Description
Finds countries by their capital city.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/capital/{capital}

### Path Parameters
- **capital** (string) - Required - The name of the capital city to search for (e.g., `tallinn`).

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/capital/tallinn
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Estonia",
      "official": "Republic of Estonia"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/demonym/{demonym}

Source: https://restcountries.com/v3.1/index

Search for countries based on their demonym (the name given to residents of a particular place).

```APIDOC
## GET /v3.1/demonym/{demonym}

### Description
Finds countries based on their demonym (e.g., "Peruvian" for Peru).

### Method
GET

### Endpoint
https://restcountries.com/v3.1/demonym/{demonym}

### Path Parameters
- **demonym** (string) - Required - The demonym to search for (e.g., `peruvian`).

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/demonym/peruvian
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Peru",
      "official": "Republic of Peru"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/translation/{translation}

Source: https://restcountries.com/v3.1/index

Search for countries by their translated name in various languages.

```APIDOC
## GET /v3.1/translation/{translation}

### Description
Searches for countries using their translated names in different languages.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/translation/{translation}

### Path Parameters
- **translation** (string) - Required - The translated name of the country to search for (e.g., `germany`, `alemania`, `Saksamaa`).

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/translation/germany
```
```
https://restcountries.com/v3.1/translation/alemania
```
```
https://restcountries.com/v3.1/translation/Saksamaa
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Germany",
      "official": "Federal Republic of Germany"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/alpha?codes={code},{code},{code}

Source: https://restcountries.com/v3.1/index

Search for multiple countries using a comma-separated list of their ISO 3166-1 alpha-2, alpha-3, numeric, or UN M49 codes.

```APIDOC
## GET /v3.1/alpha?codes={code},{code},{code}

### Description
Fetches information for multiple countries by providing a comma-separated list of their country codes.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/alpha

### Query Parameters
- **codes** (string) - Required - A comma-separated string of country codes (e.g., `170,no,est,pe`).
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/alpha?codes=170,no,est,pe
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Peru",
      "official": "Republic of Peru"
    }
  },
  {
    "name": {
      "common": "Norway",
      "official": "Kingdom of Norway"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/currency/{currency}

Source: https://restcountries.com/v3.1/index

Search for countries that use a specific currency, identified by its code or name.

```APIDOC
## GET /v3.1/currency/{currency}

### Description
Finds countries that use a specified currency. The currency can be identified by its code or name.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/currency/{currency}

### Path Parameters
- **currency** (string) - Required - The currency code (e.g., `cop`) or currency name.

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/currency/cop
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.
- **currencies** (object) - Contains information about the currencies used by the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Colombia",
      "official": "Republic of Colombia"
    },
    "currencies": {
      "COP": {
        "name": "Colombian peso",
        "symbol": "$"
      }
    }
  }
]
```
```

--------------------------------

### GET /v3.1/subregion/{subregion}

Source: https://restcountries.com/v3.1/index

Search for countries within a specific subregion.

```APIDOC
## GET /v3.1/subregion/{subregion}

### Description
Finds countries that are part of a specified subregion (e.g., "Northern Europe").

### Method
GET

### Endpoint
https://restcountries.com/v3.1/subregion/{subregion}

### Path Parameters
- **subregion** (string) - Required - The name of the subregion to search for.

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/subregion/Northern Europe
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Denmark",
      "official": "Kingdom of Denmark"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/region/{region}

Source: https://restcountries.com/v3.1/index

Search for countries belonging to a specific region.

```APIDOC
## GET /v3.1/region/{region}

### Description
Retrieves a list of countries that belong to a specified region (e.g., "Europe", "Asia").

### Method
GET

### Endpoint
https://restcountries.com/v3.1/region/{region}

### Path Parameters
- **region** (string) - Required - The name of the region to search for.

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/region/europe
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Germany",
      "official": "Federal Republic of Germany"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/independent

Source: https://restcountries.com/v3.1/index

Retrieve a list of independent or non-independent countries. The default status is 'true' if not specified.

```APIDOC
## GET /v3.1/independent

### Description
Fetches a list of countries based on their independence status. You can filter by specifying `status=true` or `status=false`.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/independent

### Query Parameters
- **status** (boolean) - Optional - Filter by independence status (`true` for independent, `false` for non-independent). Defaults to `true`.
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/independent?status=true&fields=languages,capital
```

### Response
#### Success Response (200)
- **languages** (object) - Key-value pairs of language codes and their names.
- **capital** (array) - Array of strings representing the capital city/cities.

#### Response Example
```json
[
  {
    "capital": ["Kabul"],
    "languages": {
      "pus": "Pashto",
      "tuk": "Turkmen"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/lang/{language}

Source: https://restcountries.com/v3.1/index

Search for countries based on a specific language, identified by its code or name.

```APIDOC
## GET /v3.1/lang/{language}

### Description
Finds countries where a specific language is spoken. The language can be identified by its code or name.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/lang/{language}

### Path Parameters
- **language** (string) - Required - The language code (e.g., `cop`) or language name (e.g., `spanish`).

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/lang/cop
```
```
https://restcountries.com/v3.1/lang/spanish
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Colombia",
      "official": "Republic of Colombia"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/alpha/{code}

Source: https://restcountries.com/v3.1/index

Search for a country using its ISO 3166-1 alpha-2, alpha-3, numeric, or UN M49 code.

```APIDOC
## GET /v3.1/alpha/{code}

### Description
Retrieves country information using various country codes, including ISO 3166-1 alpha-2, alpha-3, numeric (UN M49), and the former IOC code.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/alpha/{code}

### Path Parameters
- **code** (string) - Required - The country code (e.g., `co`, `col`, `170`, `170`).

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
https://restcountries.com/v3.1/alpha/co
```
```
https://restcountries.com/v3.1/alpha/col
```
```
https://restcountries.com/v3.1/alpha/170
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.

#### Response Example
```json
[
  {
    "name": {
      "common": "Colombia",
      "official": "Republic of Colombia"
    }
  }
]
```
```

--------------------------------

### GET /v3.1/all

Source: https://restcountries.com/v3.1/index

Retrieve all countries. It is mandatory to specify the fields you need (up to 10) to avoid a bad request response.

```APIDOC
## GET /v3.1/all

### Description
Retrieves a list of all countries. Users must specify desired fields (up to 10) in the query parameters for optimal performance and to prevent errors.

### Method
GET

### Endpoint
https://restcountries.com/v3.1/all

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response (e.g., `name,flags`). Up to 10 fields can be specified.

### Request Example
```
https://restcountries.com/v3.1/all?fields=name,flags
```

### Response
#### Success Response (200)
- **name** (object) - Contains the common and official name of the country.
- **flags** (object) - Contains URLs for the country's flags (e.g., `png`, `svg`).

#### Response Example
```json
[
  {
    "name": {
      "common": "Afghanistan",
      "official": "Islamic Republic of Afghanistan"
    },
    "flags": {
      "png": "https://flagcdn.com/w160/af.png",
      "svg": "https://flagcdn.com/af.svg"
    }
  }
]
```
```

--------------------------------

### Filter Response

Source: https://restcountries.com/v3.1/index

This section explains how to filter the API response to include only specific fields. You can specify the fields you want by appending `?fields=` followed by a comma-separated list of field names to the service URL.

```APIDOC
## GET /v3.1/{service}

### Description
Allows filtering of the API response to include only specified fields.

### Method
GET

### Endpoint
`https://restcountries.com/v3.1/{service}?fields={field},{field},{field}`

### Query Parameters
* **fields** (string) - Required - A comma-separated list of fields to include in the response (e.g., `name,capital,currencies`).

### Request Example
```
https://restcountries.com/v3.1/all?fields=name,capital,currencies
```

### Response
#### Success Response (200)
- **field** (any) - The data for the requested field.

#### Response Example
```json
{
  "name": {
    "common": "Canada",
    "official": "Canada",
    "nativeName": {
      "eng": {
        "official": "Canada",
        "common": "Canada"
      },
      "fra": {
        "official": "Canada",
        "common": "Canada"
      }
    }
  },
  "capital": [
    "Ottawa"
  ],
  "currencies": {
    "CAD": {
      "name": "Canadian dollar",
      "symbol": "$"
    }
  }
}
```
```
Tokens:
Raw