Retrieve detailed information about countries, including codes, currencies, languages, timezones, and neighboring countries.
Standards Used
- ISO 3166-1
- IANA TZDB
- ISO 4217
- ISO 639-1
The Country object#
| Field | Type | Required | Description |
|---|---|---|---|
| alpha3 | string | Yes | ISO 3166-1 alpha-3 code. Example: JPN |
| cctld | string | No | Country code top-level domain. Example: .jp |
| code | string | Yes | ISO 3166-1 alpha-2 code. Example: JP |
| continent | string | Yes | Continent name. Example: Asia |
| currencies | string[] | Yes | All currencies (ISO 4217 codes). Example: ["JPY"] |
| languages | string[] | Yes | Official/primary languages (ISO 639-1 codes). Example: ["ja"] |
| name | string | Yes | Common country name. Example: Japan |
| neighbors | string[] | Yes | Neighboring countries (alpha-2 codes). Example: [] |
| numeric | integer (int32) | Yes | ISO 3166-1 numeric code. Example: 392 |
| official_name | string | Yes | Official country name. Example: Japan |
| primary_currency | string | No | Primary currency (ISO 4217 code). Example: JPY |
| primary_language | string | No | Primary language (ISO 639-1 code). Example: ja |
| timezones | string[] | Yes | Timezones (IANA identifiers). Example: ["Asia/Tokyo"] |
Endpoints#
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| pagequery | integer | No | Page number (1-indexed). Example: 1 |
| per_pagequery | integer | No | Number of results per page (1-100). Example: 20 |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| data | object[] | Yes | The data items for this page. |
| pagination | object | Yes | Pagination metadata in response. |
| page | integer | Yes | Current page number. Example: 1 |
| per_page | integer | Yes | Items per page. Example: 20 |
| total_items | integer | Yes | Total number of items. Example: 100 |
| total_pages | integer | Yes | Total number of pages. Example: 5 |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/countries?page=1&per_page=20',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/countries',
params={
'page': 'eyJpZCI6MTB9',
'per_page': 'eyJpZCI6MTB9'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/countries?page=1&per_page=20"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 429 | Rate limit exceeded |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| identifierpath | string | Yes | Country code (alpha-2, alpha-3, numeric) or name |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| alpha3 | string | Yes | ISO 3166-1 alpha-3 code. Example: JPN |
| cctld | string | No | Country code top-level domain. Example: .jp |
| code | string | Yes | ISO 3166-1 alpha-2 code. Example: JP |
| continent | string | Yes | Continent name. Example: Asia |
| currencies | string[] | Yes | All currencies (ISO 4217 codes). Example: ["JPY"] |
| languages | string[] | Yes | Official/primary languages (ISO 639-1 codes). Example: ["ja"] |
| name | string | Yes | Common country name. Example: Japan |
| neighbors | string[] | Yes | Neighboring countries (alpha-2 codes). Example: [] |
| numeric | integer (int32) | Yes | ISO 3166-1 numeric code. Example: 392 |
| official_name | string | Yes | Official country name. Example: Japan |
| primary_currency | string | No | Primary currency (ISO 4217 code). Example: JPY |
| primary_language | string | No | Primary language (ISO 639-1 code). Example: ja |
| timezones | string[] | Yes | Timezones (IANA identifiers). Example: ["Asia/Tokyo"] |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/countries/example',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/countries/example',
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/countries/example"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 404 | Country not found |