API Documentation - Endpoints & Examples

Overview

The Countries by Currency endpoint returns a list of all countries that use a specific currency. This is particularly useful for financial applications, e-commerce platforms, and economic analysis tools that need to identify markets based on currency usage.

Authentication

All requests require an API key passed as a query parameter. You can obtain your API key by registering at CountryDataAPI.

Request

HTTP GET

https://api.countrydataapi.com/v1/countries/currency

Returns a list of all countries that use a specific currency.

Common Currency Codes:

• EUR: Euro (used by 19+ countries)
• USD: US Dollar (used by 14+ countries/territories)
• GBP: British Pound
• JPY: Japanese Yen
• CNY: Chinese Yuan

There are 4 types of operations:

• BASIC: Returns the fields id, lang, country_name, country_short_iso, country_phone_code, country_cca2, country_ccn3, country_cca3, country_cioc.

• NORMAL: Returns the previous fields and adds country_independent, country_status, country_unMember, country_flag, country_map_googleMaps, country_map_openStreetMaps, country_fifa, country_flag_png, country_flag_svg, country_flag_alt, country_coatOfArms_png, country_coatOfArms_svg, country_startofWeek, country_continent_code, country_current_currency, country_GDP, country_location, country_land, country_terrain, country_climate, country_natural_hazards, country_note, country_history, country_GDP_per_capita_PPP, country_life_expectancy, country_median_age, country_birth_rate, country_death_rate, country_sex_ratio, country_literacy, country_roadways, country_airports, country_railways, country_waterways, country_heliports, country_airports_paved, country_wikipedia_url.

• ADVANCED: Returns the previous fields and adds country_car_info, _country_idd_info.

• ALL: Returns the previous fields and adds country_tld, country_capital, country_altSpellings, country_latLng, country_borders, country_timezones, country_continents, country_currencies, country_languages, country_translations, country_capital_info, country_demonyms, country_name.nativeName.

Each country returned with the BASIC method will cost 1 tokens.

Each country returned with the NORMAL method will cost 2 tokens.

Each country returned with the ADVANCED method will cost 3 tokens.

Each country returned with the ALL method will cost 4 tokens.

Query Params

Response

Example Response

[
  {
    "id": "33be30c5-80fc-429d-bf10-bd11f2e3e84c",
    "lang": "en",
    "country_name": "Germany",
    "country_short_iso": "DE",
    "country_phone_code": "49",
    "country_cca2": "DE",
    "country_ccn3": "276",
    "country_cca3": "DEU",
    "country_cioc": "GER"
  },
  {
    "id": "a1b2c3d4-5678-90ab-cdef-123456789012",
    "lang": "en",
    "country_name": "France",
    "country_short_iso": "FR",
    "country_phone_code": "33",
    "country_cca2": "FR",
    "country_ccn3": "250",
    "country_cca3": "FRA",
    "country_cioc": "FRA"
  }
]

Code Examples

cURL

# Find all countries using Euro
curl -X GET "https://api.countrydataapi.com/v1/countries/currency?apikey=YOUR_API_KEY&currency=EUR"

# Find all countries using US Dollar
curl -X GET "https://api.countrydataapi.com/v1/countries/currency?apikey=YOUR_API_KEY&currency=USD"

JavaScript (Fetch)

const API_KEY = 'YOUR_API_KEY';

async function getCountriesByCurrency(currencyCode) {
  try {
    const response = await fetch(
      `https://api.countrydataapi.com/v1/countries/currency?apikey=${API_KEY}&currency=${currencyCode}`
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const countries = await response.json();
    console.log(`Countries using ${currencyCode}:`, countries);
    return countries;
  } catch (error) {
    console.error('Error fetching countries by currency:', error);
    throw error;
  }
}

// Find all Eurozone countries
getCountriesByCurrency('EUR');

JavaScript (Axios)

import axios from 'axios';

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.countrydataapi.com/v1';

async function getCountriesByCurrency(currencyCode) {
  try {
    const { data } = await axios.get(`${BASE_URL}/countries/currency`, {
      params: {
        apikey: API_KEY,
        currency: currencyCode,
        fields: 'id,country_name,country_short_iso,country_flag_png,country_current_currency'
      }
    });

    console.log(`Countries using ${currencyCode}:`, data);
    return data;
  } catch (error) {
    console.error('Error fetching countries by currency:', error.response?.data || error.message);
    throw error;
  }
}

// Find all countries using British Pound
getCountriesByCurrency('GBP');

React

import { useState } from 'react';

const API_KEY = 'YOUR_API_KEY';

const POPULAR_CURRENCIES = [
  { code: 'EUR', name: 'Euro' },
  { code: 'USD', name: 'US Dollar' },
  { code: 'GBP', name: 'British Pound' },
  { code: 'JPY', name: 'Japanese Yen' },
  { code: 'CNY', name: 'Chinese Yuan' },
  { code: 'CHF', name: 'Swiss Franc' }
];

function CurrencyCountrySearch() {
  const [currency, setCurrency] = useState('');
  const [countries, setCountries] = useState([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  async function handleSearch(currencyCode) {
    if (!currencyCode) return;

    setLoading(true);
    setError(null);
    setCurrency(currencyCode);

    try {
      const response = await fetch(
        `https://api.countrydataapi.com/v1/countries/currency?apikey=${API_KEY}&currency=${currencyCode}`
      );

      if (!response.ok) {
        throw new Error('Failed to fetch countries');
      }

      const data = await response.json();
      setCountries(data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div className="currency-search">
      <h2>Find Countries by Currency</h2>

      <div className="currency-buttons">
        {POPULAR_CURRENCIES.map((curr) => (
          <button
            key={curr.code}
            onClick={() => handleSearch(curr.code)}
            className={currency === curr.code ? 'active' : ''}
          >
            {curr.code} - {curr.name}
          </button>
        ))}
      </div>

      {loading && <div className="loading">Loading countries...</div>}
      {error && <div className="error">Error: {error}</div>}

      {countries.length > 0 && (
        <div className="results">
          <h3>Countries using {currency} ({countries.length} countries)</h3>
          <ul>
            {countries.map((country) => (
              <li key={country.id}>
                <img src={country.country_flag_png} alt={country.country_name} width="24" />
                <span>{country.country_name}</span>
                <span className="code">({country.country_cca2})</span>
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

export default CurrencyCountrySearch;

Vue 3

<script setup>
import { ref } from 'vue';

const API_KEY = 'YOUR_API_KEY';

const POPULAR_CURRENCIES = [
  { code: 'EUR', name: 'Euro' },
  { code: 'USD', name: 'US Dollar' },
  { code: 'GBP', name: 'British Pound' },
  { code: 'JPY', name: 'Japanese Yen' },
  { code: 'CNY', name: 'Chinese Yuan' }
];

const currency = ref('');
const countries = ref([]);
const loading = ref(false);
const error = ref(null);

async function searchByCurrency(currencyCode) {
  if (!currencyCode) return;

  loading.value = true;
  error.value = null;
  currency.value = currencyCode;

  try {
    const response = await fetch(
      `https://api.countrydataapi.com/v1/countries/currency?apikey=${API_KEY}&currency=${currencyCode}`
    );

    if (!response.ok) {
      throw new Error('Failed to fetch countries');
    }

    countries.value = await response.json();
  } catch (err) {
    error.value = err.message;
  } finally {
    loading.value = false;
  }
}
</script>

<template>
  <div class="currency-search">
    <h2>Find Countries by Currency</h2>

    <div class="currency-buttons">
      <button
        v-for="curr in POPULAR_CURRENCIES"
        :key="curr.code"
        @click="searchByCurrency(curr.code)"
        :class="{ active: currency === curr.code }"
      >
        {{ curr.code }} - {{ curr.name }}
      </button>
    </div>

    <div v-if="loading" class="loading">Loading countries...</div>
    <div v-if="error" class="error">Error: {{ error }}</div>

    <div v-if="countries.length > 0" class="results">
      <h3>Countries using {{ currency }} ({{ countries.length }} countries)</h3>
      <ul>
        <li v-for="country in countries" :key="country.id">
          <img :src="country.country_flag_png" :alt="country.country_name" width="24" />
          <span>{{ country.country_name }}</span>
          <span class="code">({{ country.country_cca2 }})</span>
        </li>
      </ul>
    </div>
  </div>
</template>

Angular

import { Component, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { CommonModule } from '@angular/common';

interface Country {
  id: string;
  country_name: string;
  country_short_iso: string;
  country_cca2: string;
  country_flag_png?: string;
}

interface Currency {
  code: string;
  name: string;
}

@Component({
  selector: 'app-currency-search',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="currency-search">
      <h2>Find Countries by Currency</h2>

      <div class="currency-buttons">
        <button
          *ngFor="let curr of currencies"
          (click)="searchByCurrency(curr.code)"
          [class.active]="currency === curr.code"
        >
          {{ curr.code }} - {{ curr.name }}
        </button>
      </div>

      <div *ngIf="loading" class="loading">Loading countries...</div>
      <div *ngIf="error" class="error">Error: {{ error }}</div>

      <div *ngIf="countries.length > 0" class="results">
        <h3>Countries using {{ currency }} ({{ countries.length }} countries)</h3>
        <ul>
          <li *ngFor="let country of countries">
            <img [src]="country.country_flag_png" [alt]="country.country_name" width="24" />
            <span>{{ country.country_name }}</span>
            <span class="code">({{ country.country_cca2 }})</span>
          </li>
        </ul>
      </div>
    </div>
  `
})
export class CurrencySearchComponent {
  private http = inject(HttpClient);
  private readonly API_KEY = 'YOUR_API_KEY';
  private readonly BASE_URL = 'https://api.countrydataapi.com/v1';

  currencies: Currency[] = [
    { code: 'EUR', name: 'Euro' },
    { code: 'USD', name: 'US Dollar' },
    { code: 'GBP', name: 'British Pound' },
    { code: 'JPY', name: 'Japanese Yen' },
    { code: 'CNY', name: 'Chinese Yuan' }
  ];

  currency = '';
  countries: Country[] = [];
  loading = false;
  error: string | null = null;

  searchByCurrency(currencyCode: string): void {
    this.loading = true;
    this.error = null;
    this.currency = currencyCode;

    this.http.get<Country[]>(
      `${this.BASE_URL}/countries/currency`,
      {
        params: {
          apikey: this.API_KEY,
          currency: currencyCode
        }
      }
    ).subscribe({
      next: (data) => {
        this.countries = data;
        this.loading = false;
      },
      error: (err) => {
        this.error = err.message;
        this.loading = false;
      }
    });
  }
}

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.countrydataapi.com/v1'

def get_countries_by_currency(currency_code):
    """Find all countries that use a specific currency."""
    try:
        response = requests.get(
            f'{BASE_URL}/countries/currency',
            params={
                'apikey': API_KEY,
                'currency': currency_code
            }
        )
        response.raise_for_status()

        countries = response.json()
        return countries
    except requests.exceptions.RequestException as e:
        print(f'Error fetching countries by currency: {e}')
        raise

# Usage
if __name__ == '__main__':
    # Find all Eurozone countries
    euro_countries = get_countries_by_currency('EUR')
    print(f"Countries using EUR ({len(euro_countries)} countries):")
    for country in euro_countries:
        print(f"  - {country['country_name']} ({country['country_short_iso']})")

    print()

    # Find countries using USD
    usd_countries = get_countries_by_currency('USD')
    print(f"Countries using USD ({len(usd_countries)} countries):")
    for country in usd_countries:
        print(f"  - {country['country_name']} ({country['country_short_iso']})")

PHP

<?php

$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://api.countrydataapi.com/v1';

function getCountriesByCurrency($apiKey, $baseUrl, $currencyCode) {
    $url = sprintf(
        '%s/countries/currency?apikey=%s&currency=%s',
        $baseUrl,
        urlencode($apiKey),
        urlencode($currencyCode)
    );

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Accept: application/json']
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("HTTP Error: $httpCode");
    }

    return json_decode($response, true);
}

// Usage
try {
    // Find all Eurozone countries
    $euroCountries = getCountriesByCurrency($apiKey, $baseUrl, 'EUR');
    echo "Countries using EUR (" . count($euroCountries) . " countries):\n";
    foreach ($euroCountries as $country) {
        echo sprintf("  - %s (%s)\n", $country['country_name'], $country['country_short_iso']);
    }

    echo "\n";

    // Find countries using USD
    $usdCountries = getCountriesByCurrency($apiKey, $baseUrl, 'USD');
    echo "Countries using USD (" . count($usdCountries) . " countries):\n";
    foreach ($usdCountries as $country) {
        echo sprintf("  - %s (%s)\n", $country['country_name'], $country['country_short_iso']);
    }
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Error Handling

Error Response Example

{
  "statusCode": 404,
  "message": "No countries found with currency: XYZ",
  "error": "Not Found"
}

Common Currency Codes