Lookup currency codes, symbols, and countries based on ISO 4217 standard
npm install curcode
A lightweight Node.js module to lookup and work with currency codes, symbols, and countries based on the ISO 4217 standard.
- 🔍 Lookup currencies by code, symbol, number, or country
- 💱 179 currencies with complete ISO 4217 data
- 🌍 260+ countries coverage
- 💲 Currency symbols for all codes
- 📦 Zero dependencies for production use
- 📘 TypeScript support with full type definitions
- ⚡ Fast & efficient - pure data lookups, no async operations
Install using your preferred package manager:
bash
npm install curcode
`$3
bash
yarn add curcode
`$3
bash
pnpm add curcode
`$3
bash
bun add curcode
`Usage
$3
javascript
const curcode = require('curcode');// Lookup by currency code
const euro = curcode.code('EUR');
console.log(euro);
// {
// code: 'EUR',
// number: '978',
// digits: 2,
// currency: 'Euro',
// symbol: '€',
// countries: ['Åland Islands', 'Andorra', 'Austria', ...]
// }
// Lookup by symbol
const dollar = curcode.symbol('$');
console.log(dollar.code); // 'AED' (first match)
// Lookup by country
const colombianCurrencies = curcode.country('Colombia');
console.log(colombianCurrencies);
// [
// { code: 'COP', number: '170', ... },
// { code: 'COU', number: '970', ... }
// ]
// Lookup by numeric code
const zambian = curcode.number(967);
console.log(zambian.currency); // 'Zambian Kwacha'
`$3
typescript
import * as curcode from 'curcode';
// or
import { code, symbol, country, number, codes, numbers, countries, data, symbols, publishDate, CurrencyCodeRecord } from 'curcode';// Type-safe currency lookup
const eur: CurrencyCodeRecord | undefined = curcode.code('EUR');
if (eur) {
console.log(eur.symbol); // '€'
console.log(eur.digits); // 2
}
// Get all currency codes
const allCodes: string[] = curcode.codes();
console.log(allCodes.length); // 179
// Get all countries
const allCountries: string[] = curcode.countries();
console.log(allCountries.length); // 260
`$3
javascript
import curcode from 'curcode';const usd = curcode.code('USD');
console.log(usd.currency); // 'US Dollar'
`$3
typescript
import curcode from 'curcode';// Bun works with both CommonJS and ES modules
const gbp = curcode.code('GBP');
console.log(gbp.symbol); // '£'
`API Reference
$3
Lookup currency by ISO 4217 code.
javascript
const eur = curcode.code('EUR');
console.log(eur.currency); // 'Euro'
`$3
Lookup currency by symbol. Returns the first matching currency.
javascript
const euro = curcode.symbol('€');
console.log(euro.code); // 'EUR'
`$3
Lookup currencies by country name (case insensitive). Returns an array as some countries use multiple currencies.
javascript
const currencies = curcode.country('switzerland');
// Returns currencies used in Switzerland
`$3
Lookup currency by ISO 4217 numeric code.
javascript
const usd = curcode.number('840');
// or
const usd = curcode.number(840);
console.log(usd.code); // 'USD'
`$3
Get all ISO 4217 currency codes.
javascript
const allCodes = curcode.codes();
console.log(allCodes); // ['AED', 'AFN', 'ALL', ...]
`$3
Get all ISO 4217 numeric codes.
javascript
const allNumbers = curcode.numbers();
console.log(allNumbers); // ['784', '971', '008', ...]
`$3
Get all unique country names.
javascript
const allCountries = curcode.countries();
console.log(allCountries.length); // 260
`$3
Direct access to the raw currency data array.
javascript
const rawData = curcode.data;
console.log(rawData.length); // 179
`$3
Direct access to currency symbols mapped by code.
javascript
const symbols = curcode.symbols;
console.log(symbols.USD); // '$'
console.log(symbols.EUR); // '€'
console.log(symbols.GBP); // '£'
`$3
ISO 4217 data publish date.
javascript
console.log(curcode.publishDate); // '2018-08-29'
`TypeScript Types
$3
typescript
interface CurrencyCodeRecord {
code: string; // ISO 4217 alpha code (e.g., 'USD')
number: string; // ISO 4217 numeric code (e.g., '840')
digits: number; // Decimal places (e.g., 2)
currency: string; // Currency name (e.g., 'US Dollar')
symbol?: string; // Currency symbol (e.g., '$')
countries: string[]; // Countries using this currency
}
`Examples
$3
javascript
const curcode = require('curcode');function formatCurrency(amount, code) {
const currency = curcode.code(code);
if (!currency) return
${amount};
const formatted = amount.toFixed(currency.digits);
return ${currency.symbol || currency.code} ${formatted};
}console.log(formatCurrency(1234.5, 'USD')); // '$ 1234.50'
console.log(formatCurrency(1234.5, 'EUR')); // '€ 1234.50'
console.log(formatCurrency(1234.5, 'JPY')); // '¥ 1235' (0 digits)
`$3
javascript
const curcode = require('curcode');const europeanCountries = ['germany', 'france', 'italy', 'spain', 'poland'];
europeanCountries.forEach(country => {
const currencies = curcode.country(country);
console.log(
${country}: ${currencies.map(c => c.code).join(', ')});
});
`$3
javascript
const curcode = require('curcode');function isValidCurrency(code) {
return curcode.code(code) !== undefined;
}
console.log(isValidCurrency('USD')); // true
console.log(isValidCurrency('XXX')); // true (valid test code)
console.log(isValidCurrency('INVALID')); // false
`$3
typescript
import { code, CurrencyCodeRecord } from 'curcode';interface ConversionRate {
from: CurrencyCodeRecord;
to: CurrencyCodeRecord;
rate: number;
}
function convert(amount: number, fromCode: string, toCode: string, rate: number): string {
const from = code(fromCode);
const to = code(toCode);
if (!from || !to) {
throw new Error('Invalid currency code');
}
const converted = amount * rate;
return
${from.symbol}${amount.toFixed(from.digits)} = ${to.symbol}${converted.toFixed(to.digits)};
}console.log(convert(100, 'USD', 'EUR', 0.85));
// '$100.00 = €85.00'
`Data Source
This package uses official ISO 4217 data from the International Organization for Standardization. The data includes:
- 179 active currency codes
- 260+ countries and territories
- Currency symbols from multiple sources
- Decimal place information
- Numeric codes
Last updated: 2018-08-29
Development
$3
bash
npm test
or
yarn test
or
pnpm test
or
bun test
`$3
To fetch and ingest the latest ISO 4217 XML data:
bash
npm run iso
or
pnpm run iso
``This will:
1. Fetch the latest XML from the official ISO 4217 source
2. Parse and convert it to the internal format
While this package is designed for Node.js, it can be used in browsers with bundlers like:
- Webpack
- Rollup
- Vite
- esbuild
- Parcel
The package has zero runtime dependencies, making it lightweight for browser bundles.
Contributions are welcome! Please feel free to submit a Pull Request.
MIT © idimetrix
- currency-symbol-map - Map currency codes to symbols
- iso-4217 - Alternative ISO 4217 implementation
- GitHub Repository
- npm Package
- ISO 4217 Standard
- Issue Tracker