GEO Country Currency

Get currency information by country code or find countries using a specific currency

Overview

This endpoint provides currency information for countries based on ISO 3166-1 country codes and ISO 4217 currency codes. You can query which currency a specific country uses, or find all countries that use a particular currency.

The endpoint returns:

  • Currency code (ISO 4217 alpha-3) for a given country
  • List of countries using a specific currency
  • Support for all 249 countries and territories worldwide

Pricing

📊 1 Credit per Request

Each request costs 1 data credit and counts as a billable request.

Endpoint

GET /country/currency?c2={country_code}
GET /country/currency?c3={currency_code}

Query Parameters

ParameterTypeRequiredDescription
c2stringNo*ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE")
c3stringNo*ISO 4217 alpha-3 currency code (e.g., "USD", "EUR", "GBP")

*Note: Either c2 or c3 is required, but not both.

Response Format

Get Currency by Country (c2 parameter)

{
  "c2": "US",
  "c3": "USD"
}

Get Countries by Currency (c3 parameter)

{
  "c3": "EUR",
  "countries": [
    "AD", "AT", "BE", "CY", "DE", "EE", "ES", "FI", "FR", "GR",
    "IE", "IT", "LT", "LU", "LV", "MC", "ME", "MT", "NL", "PT",
    "SI", "SK", "SM", "VA"
  ]
}

Response Fields

By Country Response

FieldTypeDescription
c2stringISO 3166-1 alpha-2 country code
c3stringISO 4217 alpha-3 currency code used by the country

By Currency Response

FieldTypeDescription
c3stringISO 4217 alpha-3 currency code
countriesarrayArray of ISO 3166-1 alpha-2 country codes using this currency

Example Requests

Get Currency for United States

curl -X GET "https://api.boxapi.com/country/currency?c2=US" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "c2": "US",
  "c3": "USD"
}

Get Currency for Germany

curl -X GET "https://api.boxapi.com/country/currency?c2=DE" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "c2": "DE",
  "c3": "EUR"
}

Get All Countries Using EUR

curl -X GET "https://api.boxapi.com/country/currency?c3=EUR" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "c3": "EUR",
  "countries": [
    "AD", "AT", "BE", "BL", "CY", "DE", "EE", "ES", "FI", "FR",
    "GF", "GP", "GR", "IE", "IT", "LT", "LU", "LV", "MC", "ME",
    "MF", "MQ", "MT", "NL", "PM", "PT", "RE", "SI", "SK", "SM",
    "TF", "VA", "YT"
  ]
}

Get All Countries Using USD

curl -X GET "https://api.boxapi.com/country/currency?c3=USD" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "c3": "USD",
  "countries": [
    "AS", "BQ", "EC", "FM", "GU", "IO", "MH", "MP", "PR", "PW",
    "SV", "TC", "TL", "UM", "US", "VG", "VI"
  ]
}

Usage Examples

JavaScript/Node.js

// Get currency for a country
const getCountryCurrency = async (countryCode) => {
  const response = await fetch(
    `https://api.boxapi.com/country/currency?c2=${countryCode}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  console.log(`${data.c2} uses currency: ${data.c3}`);
  return data;
};

// Get all countries using a specific currency
const getCountriesByCurrency = async (currencyCode) => {
  const response = await fetch(
    `https://api.boxapi.com/country/currency?c3=${currencyCode}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  console.log(`${data.c3} is used by ${data.countries.length} countries`);
  return data;
};

// Usage
await getCountryCurrency('US');       // Get USD for United States
await getCountryCurrency('GB');       // Get GBP for United Kingdom
await getCountriesByCurrency('EUR');  // Get all Eurozone countries
await getCountriesByCurrency('USD');  // Get all dollarized countries

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Get currency for a country
def get_country_currency(country_code):
    response = requests.get(
        f'https://api.boxapi.com/country/currency?c2={country_code}',
        headers=headers
    )
    data = response.json()
    print(f"{data['c2']} uses currency: {data['c3']}")
    return data

# Get all countries using a specific currency
def get_countries_by_currency(currency_code):
    response = requests.get(
        f'https://api.boxapi.com/country/currency?c3={currency_code}',
        headers=headers
    )
    data = response.json()
    print(f"{data['c3']} is used by {len(data['countries'])} countries")
    return data

# Usage
get_country_currency('US')        # Get USD for United States
get_country_currency('JP')        # Get JPY for Japan
get_countries_by_currency('EUR')  # Get all Eurozone countries
get_countries_by_currency('GBP')  # Get all countries using GBP

PHP

<?php
$apiKey = 'YOUR_API_KEY';

// Get currency for a country
function getCountryCurrency($countryCode) {
    global $apiKey;

    $ch = curl_init("https://api.boxapi.com/country/currency?c2={$countryCode}");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $data = json_decode($response, true);

    echo "{$data['c2']} uses currency: {$data['c3']}\n";
    return $data;
}

// Get all countries using a specific currency
function getCountriesByCurrency($currencyCode) {
    global $apiKey;

    $ch = curl_init("https://api.boxapi.com/country/currency?c3={$currencyCode}");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $data = json_decode($response, true);

    echo "{$data['c3']} is used by " . count($data['countries']) . " countries\n";
    return $data;
}

// Usage
getCountryCurrency('US');        // Get USD for United States
getCountryCurrency('CA');        // Get CAD for Canada
getCountriesByCurrency('EUR');   // Get all Eurozone countries
getCountriesByCurrency('CHF');   // Get all countries using Swiss Franc
?>

Error Responses

Missing Required Parameter

{
  "error": "Missing required parameter: c2 or c3",
  "statusCode": 400,
  "usage": {
    "byCountry": "GET /country/currency?c2=US",
    "byCurrency": "GET /country/currency?c3=EUR"
  }
}

HTTP Status: 400 Bad Request

Country Not Found

{
  "error": "Country not found",
  "statusCode": 404
}

HTTP Status: 404 Not Found

Currency Not Found

{
  "error": "Currency not found or not used by any country",
  "statusCode": 404
}

HTTP Status: 404 Not Found

Authentication Error

{
  "error": "Unauthorized"
}

HTTP Status: 401 Unauthorized

Rate Limits

The following rate limits apply per IP address:

  • 10,000 requests per minute for successful responses (2xx status codes)
  • 60 requests per minute for client errors (4xx status codes)
  • 60 requests per minute for server errors (5xx status codes)

⚠️ If you exceed these limits, your IP will be temporarily blocked and you'll receive a 429 status code.

Important Notes

  • Case-insensitive: Both country codes and currency codes are case-insensitive
  • Complete coverage: Supports all 249 countries and territories worldwide
  • Multi-currency countries: Some countries may officially use multiple currencies, but this endpoint returns the primary currency
  • Historical accuracy: The currency mapping reflects current official usage as of 2025
  • Eurozone: 33 countries and territories use the Euro (EUR)
  • USD usage: 17 countries and territories use the US Dollar (USD)

Euro (EUR) - 33 countries/territories

The Euro is the most widely used currency by country count, used across the European Union and some associated territories.

US Dollar (USD) - 17 countries/territories

The US Dollar is used not only in the United States but also in many territories and countries that have dollarized their economies.

East Caribbean Dollar (XCD) - 8 countries

Used by the Eastern Caribbean Currency Union members.

Australian Dollar (AUD) - 7 territories

Used in Australia and several Pacific territories.

CFA Franc (XOF, XAF) - Multiple countries

Used by countries in West and Central Africa.

Use Cases

The Country Currency API is ideal for:

  • 💱 E-commerce platforms displaying prices in local currencies
  • 🌍 International payment systems routing to correct currency processors
  • 📊 Financial applications showing currency by country
  • 🗺️ Travel applications displaying currency information
  • 📱 Mobile apps for currency conversion with country context
  • 🏦 Banking systems validating country-currency combinations
  • 📈 Analytics platforms grouping transactions by currency zones
  • Currency API - Get detailed currency information and exchange rates
  • Country List - Get complete country information with translations
  • GEO IP - Get country code from IP address

Combining with Other Endpoints

You can combine this endpoint with other APIs for powerful workflows:

// Example: Get currency for user's country based on IP
const ipResponse = await fetch('https://api.boxapi.com/geo/ip', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const ipData = await ipResponse.json();

const currencyResponse = await fetch(
  `https://api.boxapi.com/country/currency?c2=${ipData.c2}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const currencyData = await currencyResponse.json();

console.log(`User's country: ${ipData.c2}, Currency: ${currencyData.c3}`);