---
title: Country Details API Reference
version: 1.0.0
description: Get comprehensive metadata for a specific country identified by its ISO 3166-1 alpha-2 code. Returns the country name, ISO codes (alpha-2, alpha-3, numeric), phone code, capital city, top-level domain, native name, region and subregion, nationality, flag emoji, and currency details (code, name, symbol). A valid two-letter country code is required. capital, region, and subregion are empty strings (not omitted) for the same handful of uninhabited/dependent territories as the Countries list endpoint — every other field, including currency and phone code, is populated for those territories.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 2
---

## Table of Contents

- [Country Details API Reference v1.0.0](#country-details-api-reference-v100)
  - [Authentication](#authentication)
  - [GeoDB APIs](#geodb-apis)
    - [getCountryDetails](#getcountrydetails)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [CountryDetailsResponse](#countrydetailsresponse)
    - [ErrorResponse](#errorresponse)



# Country Details API Reference v1.0.0

Get comprehensive metadata for a specific country identified by its ISO 3166-1 alpha-2 code. Returns the country name, ISO codes (alpha-2, alpha-3, numeric), phone code, capital city, top-level domain, native name, region and subregion, nationality, flag emoji, and currency details (code, name, symbol). A valid two-letter country code is required. capital, region, and subregion are empty strings (not omitted) for the same handful of uninhabited/dependent territories as the Countries list endpoint — every other field, including currency and phone code, is populated for those territories.

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

### getCountryDetails

`GET /geo/country/details`

*Retrieve comprehensive metadata for a specific country*

Returns complete country details for a single country identified by its ISO 3166-1 alpha-2 code, including ISO codes, capital, currency, phone code, nationality, and flag emoji.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|country|query|string|true|Country code in ISO 3166-1 alpha-2 format (e.g., US, PK).|

##### Enumerated Values

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

> Example responses

> Successful response with country details

```json
{
  "name": "United States",
  "iso_alpha_2": "US",
  "iso_alpha_3": "USA",
  "iso_numeric": 840,
  "phone_code": 1,
  "capital": "Washington",
  "top_level_domain": ".us",
  "native_name": "United States",
  "region": "Americas",
  "subregion": "Northern America",
  "nationality": "American",
  "flag_emoji": "🇺🇸",
  "currency_code": "USD",
  "currency_name": "United States dollar",
  "currency_symbol": "$"
}
```

```json
{
  "name": "Bouvet Island",
  "iso_alpha_2": "BV",
  "iso_alpha_3": "BVT",
  "iso_numeric": 74,
  "phone_code": 55,
  "capital": "",
  "top_level_domain": ".bv",
  "native_name": "Bouvetøya",
  "region": "",
  "subregion": "",
  "nationality": "Bouvet Island",
  "flag_emoji": "🇧🇻",
  "currency_code": "NOK",
  "currency_name": "Norwegian krone",
  "currency_symbol": "ko"
}
```

> Bad Request — Missing country parameter, or country is not a valid/known ISO 3166-1 alpha-2 code

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/geo/country/details",
  "status": 400,
  "timestamp": "2026-07-24T10:54:42.188Z"
}
```

```json
{
  "timestamp": "2026-07-24T10:54:42.684Z",
  "path": "/v1/country/details",
  "status": 400,
  "error": "Invalid Country Code provided",
  "message": "Only ISO 3166-1 alpha-2 codes country codes are supported."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response with country details|[CountryDetailsResponse](#countrydetailsresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing country parameter, or country is not a valid/known ISO 3166-1 alpha-2 code|[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

### CountryDetailsResponse

Comprehensive metadata for a single country resolved from an ISO 3166-1 alpha-2 code.

#### 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.|
|phone_code|integer|true|none|The international dialing/phone code for the country.|
|capital|string|true|none|The capital city of the country. Empty string for uninhabited/dependent territories with no capital.|
|top_level_domain|string|true|none|The country-code top-level internet domain.|
|native_name|string|true|none|The name of the country in its native language.|
|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.|
|nationality|string|true|none|The demonym for citizens of the country.|
|flag_emoji|string|true|none|The emoji flag representing the country.|
|currency_code|string|true|none|The ISO 4217 currency code used in the country.|
|currency_name|string|true|none|The full name of the currency used in the country.|
|currency_symbol|string|true|none|The symbol of the currency used in the country.|

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