---
title: Countries API - Retrieve Global Countries Data
version: 1.0.0
description: Retrieve a complete list of 250 countries and territories with ISO codes (alpha-2, alpha-3, numeric), capital cities, and geographic region/subregion assignments. Optionally filter by region or subregion name to narrow results. Each country object includes the full English name, ISO codes, numeric code, capital city, region, and subregion. Returns all countries by default when no filters are applied. capital, region, and subregion are empty strings (not omitted) for a handful of uninhabited or dependent territories with no assigned value, e.g. Bouvet Island and Heard Island and McDonald Islands have no region/subregion at all, and Antarctica/Tokelau/US Minor Outlying Islands have no capital.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 3
---

## Table of Contents

- [Countries API - Retrieve Global Countries Data v1.0.0](#countries-api-retrieve-global-countries-data-v100)
  - [Authentication](#authentication)
  - [GeoDB APIs](#geodb-apis)
    - [getCountries](#getcountries)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [CountriesResponse](#countriesresponse)
    - [CountryItem](#countryitem)
    - [ErrorResponse](#errorresponse)



# Countries API - Retrieve Global Countries Data v1.0.0

Retrieve a complete list of 250 countries and territories with ISO codes (alpha-2, alpha-3, numeric), capital cities, and geographic region/subregion assignments. Optionally filter by region or subregion name to narrow results. Each country object includes the full English name, ISO codes, numeric code, capital city, region, and subregion. Returns all countries by default when no filters are applied. capital, region, and subregion are empty strings (not omitted) for a handful of uninhabited or dependent territories with no assigned value, e.g. Bouvet Island and Heard Island and McDonald Islands have no region/subregion at all, and Antarctica/Tokelau/US Minor Outlying Islands have no capital.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## GeoDB APIs

### getCountries

`GET /geo/countries`

*Retrieve a list of countries with optional region or subregion filtering*

Returns all countries with their ISO codes, capital cities, regions, and subregions. Optional region and subregion parameters narrow results.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|region|query|string|false|Optional filter to return countries within a specific region (e.g., Europe, Asia).|
|subregion|query|string|false|Optional filter to return countries within a specific subregion (e.g., Northern Europe, Southern Asia).|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful response with list of countries

```json
{
  "countries": [
    {
      "name": "United Kingdom",
      "iso_alpha_2": "GB",
      "iso_alpha_3": "GBR",
      "iso_numeric": 826,
      "capital": "London",
      "region": "Europe",
      "subregion": "Northern Europe"
    },
    {
      "name": "France",
      "iso_alpha_2": "FR",
      "iso_alpha_3": "FRA",
      "iso_numeric": 250,
      "capital": "Paris",
      "region": "Europe",
      "subregion": "Western Europe"
    },
    {
      "name": "Germany",
      "iso_alpha_2": "DE",
      "iso_alpha_3": "DEU",
      "iso_numeric": 276,
      "capital": "Berlin",
      "region": "Europe",
      "subregion": "Western Europe"
    }
  ]
}
```

```json
{
  "countries": [
    {
      "name": "Bouvet Island",
      "iso_alpha_2": "BV",
      "iso_alpha_3": "BVT",
      "iso_numeric": 74,
      "capital": "",
      "region": "",
      "subregion": ""
    },
    {
      "name": "Antarctica",
      "iso_alpha_2": "AQ",
      "iso_alpha_3": "ATA",
      "iso_numeric": 10,
      "capital": "",
      "region": "Polar",
      "subregion": ""
    }
  ]
}
```

> Bad Request — Invalid region or subregion name

```json
{
  "timestamp": "2026-07-24T10:51:01.695Z",
  "path": "/v1/countries",
  "status": 400,
  "error": "Invalid Region Name provided",
  "message": "Please provide a valid region name."
}
```

```json
{
  "timestamp": "2026-07-24T10:51:02.247Z",
  "path": "/v1/countries",
  "status": 400,
  "error": "Invalid Subregion Name provided",
  "message": "Please provide a valid subregion name."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response with list of countries|[CountriesResponse](#countriesresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Invalid region or subregion name|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### CountriesResponse

Response containing the list of countries matching the applied region/subregion filters (or all 250 when unfiltered).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|countries|[[CountryItem](#countryitem)]|true|none|An array of country objects matching the applied filters.|

### CountryItem

A country object containing ISO codes, capital, and region information.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|The full English name of the country.|
|iso_alpha_2|string|true|none|The ISO 3166-1 alpha-2 two-letter country code.|
|iso_alpha_3|string|true|none|The ISO 3166-1 alpha-3 three-letter country code.|
|iso_numeric|integer|true|none|The ISO 3166-1 numeric country code.|
|capital|string|true|none|The capital city of the country. Empty string for uninhabited/dependent territories with no capital.|
|region|string|true|none|The broad geographical region the country belongs to. Empty string for a small number of territories with no assigned region.|
|subregion|string|true|none|The more specific subregion the country belongs to. Empty string for a small number of territories with no assigned subregion.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|