Unirate Node.js API Client

A comprehensive Node.js/TypeScript client for the Unirate API - providing free, real-time and historical currency exchange rates, plus VAT rates.

Features

• 🔄 Real-time exchange rates - Get current currency conversion rates
• 📈 Historical data - Access historical exchange rates for any date (1999-2025)
• ⏰ Time series data - Retrieve exchange rate data over date ranges (max 5 years)
• 💰 Currency conversion - Convert amounts between currencies (current and historical)
• 🏛️ VAT rates - Get VAT rates for countries worldwide
• 📊 Multiple output formats - JSON, XML, CSV, TSV support
• 🌍 170+ currencies supported - Including cryptocurrencies
• 🆓 Completely free - No credit card required
• 🚀 Easy to use - Simple, intuitive API
• ⚡ TypeScript support - Full type definitions included

Installation

npm install unirate-api

Quick Start

import{UnirateClient}from'unirate-api';// Initialize the clientconstclient=newUnirateClient('your-api-key-here');asyncfunctionmain(){// Get current exchange rateconstrate=awaitclient.getRate('USD','EUR');console.log(`USD to EUR rate: ${rate}`);// Convert currency (note: toCurrency is now first parameter)constamount=awaitclient.convert('EUR',100,'USD');console.log(`100 USD = ${amount} EUR`);// Get supported currenciesconstcurrencies=awaitclient.getSupportedCurrencies()asstring[];console.log(`Supported currencies: ${currencies.length}`);}main();

API Methods

Current Rates & Conversion

getRate(fromCurrency?, toCurrency?, format?, callback?)

Get current exchange rates. If toCurrency is omitted, returns rates for all currencies.

// Single currency rateconstrate=awaitclient.getRate('USD','EUR');// All rates for base currencyconstallRates=awaitclient.getRate('USD')asRecord<string,number>;// Get rates in CSV formatconstcsvData=awaitclient.getRate('USD','EUR','csv')asstring;

convert(toCurrency, amount?, fromCurrency?, format?, callback?)

Convert an amount from one currency to another using current rates.

// Convert with default amount (1)constconverted=awaitclient.convert('EUR',1,'USD');// Convert specific amountconstconverted=awaitclient.convert('EUR',100,'USD');// Get conversion result in XML formatconstxmlResult=awaitclient.convert('EUR',100,'USD','xml')asstring;

getSupportedCurrencies(format?, callback?)

Get a list of all supported currency codes.

constcurrencies=awaitclient.getSupportedCurrencies()asstring[];// Get currencies in CSV formatconstcsvCurrencies=awaitclient.getSupportedCurrencies('csv')asstring;

Historical Data

getHistoricalRate(date, amount?, fromCurrency?, toCurrency?, format?, callback?)

Get historical exchange rates for a specific date. If toCurrency is omitted, returns rates for all currencies.

// Single currency historical rateconstrate=awaitclient.getHistoricalRate('2024-01-01',1,'USD','EUR');// All historical rates for base currencyconstallRates=awaitclient.getHistoricalRate('2024-01-01',1,'USD')asRecord<string,number>;// Historical conversion with amountconstconverted=awaitclient.getHistoricalRate('2024-01-01',100,'USD','EUR');

getHistoricalRates(date, amount?, baseCurrency?, format?, callback?)

Alias for getHistoricalRate to get all exchange rates for a base currency on a specific date.

constrates=awaitclient.getHistoricalRates('2024-01-01',1,'USD')asRecord<string,number>;

convertHistorical(amount, fromCurrency, toCurrency, date, format?, callback?)

Convert an amount using historical exchange rates for a specific date.

constconverted=awaitclient.convertHistorical(100,'USD','EUR','2024-01-01');

getTimeSeries(startDate, endDate, amount?, baseCurrency?, currencies?, format?, callback?)

Get time series exchange rate data over a date range (max 5 years).

// Time series for specific currenciesconsttimeSeries=awaitclient.getTimeSeries('2024-01-01','2024-01-07',1,'USD',['EUR','GBP'])asRecord<string,Record<string,number>>;// Time series for all currenciesconstallSeries=awaitclient.getTimeSeries('2024-01-01','2024-01-07',1,'USD');// Time series with amount conversionconstconvertedSeries=awaitclient.getTimeSeries('2024-01-01','2024-01-07',100,'USD',['EUR']);

New Features

getHistoricalLimits(format?, callback?)

Get information about available historical data limits per currency.

import{HistoricalLimitsResponse}from'unirate-api';constlimits=awaitclient.getHistoricalLimits()asHistoricalLimitsResponse;console.log(`Total currencies with historical data: ${limits.total_currencies}`);Object.entries(limits.currencies).forEach(([currency,info])=>{console.log(`${currency}: ${info.earliest_date} to ${info.latest_date}`);});

getVATRates(country?, format?, callback?)

Get VAT rates for all countries or a specific country.

import{VATRatesResponse,VATRateResponse}from'unirate-api';// Get all VAT ratesconstallVAT=awaitclient.getVATRates()asVATRatesResponse;console.log(`Total countries: ${allVAT.total_countries}`);// Get VAT rate for specific countryconstgermanyVAT=awaitclient.getVATRates('DE')asVATRateResponse;console.log(`Germany VAT rate: ${germanyVAT.vat_data.vat_rate}%`);// Get VAT rates in CSV formatconstcsvVAT=awaitclient.getVATRates(undefined,'csv')asstring;

Output Formats

All methods support multiple output formats:

• json (default) - Returns TypeScript objects
• xml - Returns XML string
• csv - Returns CSV string
• tsv - Returns TSV string

// JSON (default)constjsonData=awaitclient.getRate('USD','EUR');// XML formatconstxmlData=awaitclient.getRate('USD','EUR','xml')asstring;// CSV formatconstcsvData=awaitclient.getRate('USD','EUR','csv')asstring;// TSV formatconsttsvData=awaitclient.getRate('USD','EUR','tsv')asstring;

JSONP Support

For JSON responses, you can specify a JSONP callback function:

constjsonpData=awaitclient.getRate('USD','EUR','json','myCallback');

Complete Example

import{UnirateClient,UnirateError,AuthenticationError,RateLimitError,HistoricalLimitsResponse,VATRatesResponse}from'unirate-api';asyncfunctionmain(){constclient=newUnirateClient('your-api-key-here');try{console.log('=== Current Rates ===');// Current exchange rateconstrate=awaitclient.getRate('USD','EUR');console.log(`Current USD to EUR: ${rate}`);// All rates for USDconstallRates=awaitclient.getRate('USD')asRecord<string,number>;console.log(`EUR: ${allRates.EUR}, GBP: ${allRates.GBP}`);// Currency conversionconstconverted=awaitclient.convert('EUR',1000,'USD');console.log(`1000 USD = ${converted} EUR`);console.log('\n=== Historical Data ===');// Historical rateconsthistoricalRate=awaitclient.getHistoricalRate('2024-01-01',1,'USD','EUR');console.log(`USD to EUR on 2024-01-01: ${historicalRate}`);// Historical conversionconsthistoricalConverted=awaitclient.convertHistorical(1000,'USD','EUR','2024-01-01');console.log(`1000 USD = ${historicalConverted} EUR (on 2024-01-01)`);// Time series dataconsttimeSeries=awaitclient.getTimeSeries('2024-01-01','2024-01-05',1,'USD',['EUR','GBP'])asRecord<string,Record<string,number>>;console.log('USD time series:');Object.entries(timeSeries).forEach(([date,rates])=>{console.log(` ${date}: EUR=${rates.EUR}, GBP=${rates.GBP}`);});console.log('\n=== New Features ===');// Historical limitsconstlimits=awaitclient.getHistoricalLimits()asHistoricalLimitsResponse;console.log(`Total currencies: ${limits.total_currencies}`);// VAT ratesconstvatRates=awaitclient.getVATRates()asVATRatesResponse;console.log(`Total countries with VAT: ${vatRates.total_countries}`);// Germany VATconstgermanyVAT=awaitclient.getVATRates('DE');console.log(`Germany VAT: ${(germanyVATasany).vat_data.vat_rate}%`);console.log('\n=== Format Examples ===');// CSV formatconstcsvData=awaitclient.getRate('USD','EUR','csv')asstring;console.log('CSV format:',csvData.substring(0,50)+'...');}catch(error){if(errorinstanceofAuthenticationError){console.error('Invalid API key');}elseif(errorinstanceofRateLimitError){console.error('Rate limit exceeded');}elseif(errorinstanceofUnirateError){console.error('API Error:',error.message);}else{console.error('Unexpected error:',error);}}}main();

Error Handling

The client provides specific exception types for different error scenarios:

import{UnirateClient,UnirateError,AuthenticationError,RateLimitError,InvalidCurrencyError,InvalidDateError,APIError}from'unirate-api';constclient=newUnirateClient('your-api-key');try{constrate=awaitclient.getRate('USD','INVALID');}catch(error){if(errorinstanceofAuthenticationError){console.error('Invalid API key');}elseif(errorinstanceofInvalidCurrencyError){console.error('Invalid currency code');}elseif(errorinstanceofRateLimitError){console.error('Rate limit exceeded');}elseif(errorinstanceofInvalidDateError){console.error('Invalid date format');}elseif(errorinstanceofAPIError){console.error(`API Error: ${error.message} (Status: ${error.statusCode})`);}elseif(errorinstanceofUnirateError){console.error(`General API Error: ${error.message}`);}}

Rate Limits

• Currency endpoints: Standard rate limits apply
• Historical endpoints: 50 requests per hour
• VAT endpoints: 1800 requests per hour

Configuration

Constructor Options

constclient=newUnirateClient('your-api-key',// API key (required)30000// Timeout in milliseconds (optional, default: 30000));

Environment Variables

You can also use environment variables:

constclient=newUnirateClient(process.env.UNIRATE_API_KEY!);

API Key

Get your free API key from https://unirateapi.com. No credit card required!

Supported Currencies

The API supports 170+ currencies including:

• Traditional currencies: USD, EUR, GBP, JPY, CAD, AUD, etc.
• Cryptocurrencies: BTC, ETH, LTC, and many more

Use getSupportedCurrencies() to get the complete list.

Historical Data Coverage

Historical data is available from 1999 to 2025, with coverage varying by currency:

• Major currencies: Full coverage from 1999-01-01
• Some currencies: Limited historical data (use getHistoricalLimits() to check)

Requirements

• Node.js 14+
• TypeScript 4+ (for TypeScript projects)

Dependencies

• axios - for HTTP requests

Changelog

Version 1.0.0

• NEW: VAT rates endpoint (getVATRates())
• NEW: Historical limits endpoint (getHistoricalLimits())
• NEW: Multiple output formats (JSON, XML, CSV, TSV)
• NEW: JSONP callback support
• BREAKING: Updated method signatures with optional parameters and defaults
• BREAKING: convert() method parameter order changed (toCurrency first)
• BREAKING: Historical methods now require date as first parameter
• IMPROVED: Better error handling with specific exception types
• IMPROVED: Enhanced response parsing for new API structure
• IMPROVED: Full TypeScript interface definitions for all new features

Related clients

• unirate-api-python — Python (PyPI: unirate-api)
• unirate-api-swift — Swift (SPM)
• unirate-api-java — Java (Maven)
• unirate-api-go — Go
• unirate-api-rust — Rust (crates.io: unirate-api)
• unirate-api-ruby — Ruby (gem: unirate-api)
• unirate-api-php — PHP (Composer: unirate-api/unirate-api)
• unirate-api-dotnet — .NET / C# (NuGet: UniRateApi)

UniRate ecosystem

UniRate ships official integrations for 40+ ecosystems, all maintained under the UniRate-API org.

Core clients (9 languages)Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift

JavaScript / TypeScriptReact · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC

Static-site generatorsAstro · Eleventy · Hugo · Jekyll

CMS & e-commerceWagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus

Data, AI & backendLangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt

Platform & toolsMCP server · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian

Money library bridgesmoney gem (Ruby) · NodaMoney (.NET)

Get a free API key at unirateapi.com.

License

MIT License