World Currencies

A comprehensive, multi-language library providing detailed information about world currencies. Access currency data including ISO codes, symbols, native names, denominations, and more across JavaScript/TypeScript, Python, Ruby, and PHP.

Features

• 🌍 Complete Coverage: All 150+ world currencies with detailed information
• 🌐 Native Names: Currency names in their native languages and scripts
• 💱 Rich Metadata: ISO codes, symbols, decimal digits, rounding rules
• 💵 Denominations: Information about banknotes and coins in circulation
• 🏳️ Country Mapping: Countries where each currency is used
• 📦 Multi-Platform: Available for JavaScript/TypeScript, Python, Ruby, and PHP
• 🔄 Consistent API: Similar interface across all supported languages
• 📊 JSON Data Source: Single source of truth for all implementations

Installation

JavaScript/TypeScript (npm)

npm install @devmehq/world-currencies

const currencies = require('@devmehq/world-currencies');
// or
import currencies from '@devmehq/world-currencies';

Python (pip)

pip install world-currencies

from world_currencies import currencies

Ruby (gem)

gem install devmehq-world-currencies

require 'world_currencies'

PHP (Composer)

composer require devmehq/world-currencies

use DevMe\WorldCurrencies\Currencies;

Usage Examples

JavaScript/TypeScript

import { getCurrency, getAllCurrencies, getCurrenciesByCountry } from '@devmehq/world-currencies';

// Get specific currency
const usd = getCurrency('USD');
console.log(usd);
// {
//   name: 'US Dollar',
//   name_native: 'US Dollar',
//   symbol: '$',
//   symbol_native: '$',
//   decimal_digits: 2,
//   countries: ['US', 'AS', 'BQ', ...],
//   ...
// }

// Get all currencies
const allCurrencies = getAllCurrencies();

// Get currencies for a specific country
const countryCurrencies = getCurrenciesByCountry('US');

Python

from world_currencies import get_currency, get_all_currencies, get_currencies_by_country

# Get specific currency
usd = get_currency('USD')
print(usd['name'])  # 'US Dollar'
print(usd['symbol'])  # '$'

# Get all currencies
all_currencies = get_all_currencies()

# Get currencies for a specific country
us_currencies = get_currencies_by_country('US')

Ruby

require 'world_currencies'

# Get specific currency
usd = WorldCurrencies.get_currency('USD')
puts usd['name']  # 'US Dollar'
puts usd['symbol']  # '$'

# Get all currencies
all_currencies = WorldCurrencies.get_all_currencies

# Get currencies for a specific country
us_currencies = WorldCurrencies.get_currencies_by_country('US')

PHP

use DevMe\WorldCurrencies\Currencies;

$currencies = new Currencies();

// Get specific currency
$usd = $currencies->getCurrency('USD');
echo $usd['name'];  // 'US Dollar'
echo $usd['symbol'];  // '$'

// Get all currencies
$allCurrencies = $currencies->getAllCurrencies();

// Get currencies for a specific country
$usCurrencies = $currencies->getCurrenciesByCountry('US');

Currency Data Structure

Each currency object contains the following information:

{
  "name": "United States Dollar",
  "name_native": "US Dollar",
  "name_plural": "US dollars",
  "name_plural_native": "US Dollars",
  "iso": {
    "code": "USD",
    "number": "840"
  },
  "symbol": "$",
  "symbol_native": "$",
  "decimal_digits": 2,
  "rounding": 0,
  "units": {
    "major": {
      "name": "dollar",
      "symbol": "$"
    },
    "minor": {
      "name": "cent",
      "symbol": "¢",
      "majorValue": 0.01
    }
  },
  "banknotes": {
    "frequent": ["$1", "$5", "$10", "$20", "$50", "$100"],
    "rare": ["$2"]
  },
  "coins": {
    "frequent": ["1¢", "5¢", "10¢", "25¢"],
    "rare": ["50¢", "$1"]
  },
  "countries": ["US", "AS", "BQ", "IO", "EC", "SV", "GU", "HT", "MH", "FM", "MP", "PW", "PA", "PR", "TL", "TC", "VI", "UM"]
}

API Reference

Core Functions

All implementations provide these core functions:

Function	Description	Parameters	Returns
getCurrency(code)	Get currency by ISO code	code: string	Currency object or null
getAllCurrencies()	Get all currencies	None	Object/Dict of all currencies
getCurrenciesByCountry(country)	Get currencies used in a country	country: string	Array of currency codes
getCurrencyBySymbol(symbol)	Find currencies by symbol	symbol: string	Array of currency objects
getCurrenciesByDecimalDigits(digits)	Find currencies by decimal digits	digits: number	Array of currency objects

Available Currency Codes

The library includes all ISO 4217 currency codes, including but not limited to:

• Major Currencies: USD, EUR, GBP, JPY, CNY, CHF, CAD, AUD
• Regional Currencies: XAF, XCD, XOF, XPF (monetary unions)
• Crypto-friendly: Many currencies used in crypto exchanges
• Historical: Recently redenominated currencies with their current codes

Data Source

The currency data is maintained in a single JSON file (data/world-currencies.json) that serves as the source of truth for all language implementations. This ensures consistency across all platforms.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Clone the repository:

git clone https://github.com/devmehq/world-currencies.git
cd world-currencies

2. Install dependencies for your language:

JavaScript/TypeScript:

npm install
npm run build
npm test

Python:

pip install -e .[dev]
pytest tests/python

Ruby:

bundle install
bundle exec rspec

PHP:

composer install
composer test

Testing

All implementations include comprehensive test suites. Run tests with:

• JavaScript: npm test
• Python: pytest
• Ruby: bundle exec rspec
• PHP: composer test

Deployment

The library is automatically published to all package managers when a new version tag is pushed:

git tag v1.0.0
git push origin v1.0.0

This triggers GitHub Actions workflows that publish to:

• NPM (@devmehq/world-currencies)
• PyPI (world-currencies)
• RubyGems (devmehq-world-currencies)
• Packagist (devmehq/world-currencies)

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 💖 Sponsor: GitHub Sponsors

Credits

Created and maintained by DevMe.

Changelog

See CHANGELOG.md for a list of changes.

---

Made with ❤️ by DEV.ME