Getting Started
Welcome to the ISOCODE.CV API! Our RESTful API provides access to comprehensive ISO standards data including countries (ISO 3166), languages (ISO 639), and currencies (ISO 4217).
Base URL for all API endpoints
Quick Start Example
// Fetch all countries
fetch('https://api.isocode.cv/v1/countries')
.then(response => response.json())
.then(data => console.log(data));
// Fetch specific country by code
fetch('https://api.isocode.cv/v1/countries/US')
.then(response => response.json())
.then(data => console.log(data));
Authentication
The ISOCODE.CV API is currently free and does not require authentication for basic usage. For higher rate limits and advanced features, API keys will be available in the future.
All endpoints are currently public and can be accessed without any API key or authentication headers.
Countries API (ISO 3166)
Access comprehensive country data including names, codes, capitals, regions, and more.
Retrieve all countries with their ISO 3166 codes
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| region | string | optional | Filter by region (Africa, Americas, Asia, Europe, Oceania) |
| limit | number | optional | Number of results to return (default: 50, max: 250) |
| offset | number | optional | Number of results to skip for pagination |
Example Response
{
"data": [
{
"name": "United States",
"alpha2": "US",
"alpha3": "USA",
"numeric": "840",
"capital": "Washington, D.C.",
"region": "Americas",
"subregion": "North America",
"languages": ["en"],
"currency": "USD"
}
],
"meta": {
"total": 249,
"count": 1,
"offset": 0
}
}
Response will appear here...
Retrieve a specific country by its ISO code
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| code | string | required | Country code (alpha-2, alpha-3, or numeric) |
Response will appear here...
Languages API (ISO 639)
Access language data with ISO 639 codes, native names, language families, and speaker counts.
Retrieve all languages with their ISO 639 codes
Example Response
{
"data": [
{
"name": "English",
"native_name": "English",
"iso639_1": "en",
"iso639_2": "eng",
"iso639_3": "eng",
"family": "Indo-European",
"script": "Latn",
"speakers": "380000000",
"countries": ["US", "GB", "CA", "AU"]
}
],
"meta": {
"total": 30,
"count": 1,
"offset": 0
}
}
Currencies API (ISO 4217)
Access currency data with ISO 4217 codes, symbols, decimal places, and usage countries.
Retrieve all currencies with their ISO 4217 codes
Example Response
{
"data": [
{
"name": "US Dollar",
"code": "USD",
"number": "840",
"decimals": 2,
"symbol": "$",
"countries": ["United States", "Ecuador", "El Salvador"]
}
],
"meta": {
"total": 40,
"count": 1,
"offset": 0
}
}
Error Handling
The API uses conventional HTTP response codes to indicate the success or failure of requests.
- 200 - OK: Request succeeded
- 400 - Bad Request: Invalid request parameters
- 404 - Not Found: Resource not found
- 429 - Too Many Requests: Rate limit exceeded
- 500 - Internal Server Error: Server error
Error Response Format
{
"error": {
"code": "NOT_FOUND",
"message": "Country with code 'XYZ' not found",
"details": {
"parameter": "code",
"value": "XYZ"
}
}
}
Rate Limits
To ensure fair usage and maintain service quality, the API implements rate limiting.
- 1000 requests per hour per IP address
- 100 requests per minute per IP address
- Rate limit headers included in all responses
Rate Limit Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1643723400