| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Name | Name | Last commit date | ||
|---|---|---|---|---|
A comprehensive Node.js/TypeScript client for the Unirate API - providing free, real-time and historical currency exchange rates, plus VAT rates.
npm install unirate-apiimport { UnirateClient } from 'unirate-api';
// Initialize the client
const client = new UnirateClient('your-api-key-here');
async function main() {
// Get current exchange rate
const rate = await client.getRate('USD', 'EUR');
console.log(`USD to EUR rate: ${rate}`);
// Convert currency (note: toCurrency is now first parameter)
const amount = await client.convert('EUR', 100, 'USD');
console.log(`100 USD = ${amount} EUR`);
// Get supported currencies
const currencies = await client.getSupportedCurrencies() as string[];
console.log(`Supported currencies: ${currencies.length}`);
}
main();Get current exchange rates. If toCurrency is omitted, returns rates for all currencies.
// Single currency rate
const rate = await client.getRate('USD', 'EUR');
// All rates for base currency
const allRates = await client.getRate('USD') as Record<string, number>;
// Get rates in CSV format
const csvData = await client.getRate('USD', 'EUR', 'csv') as string;Convert an amount from one currency to another using current rates.
// Convert with default amount (1)
const converted = await client.convert('EUR', 1, 'USD');
// Convert specific amount
const converted = await client.convert('EUR', 100, 'USD');
// Get conversion result in XML format
const xmlResult = await client.convert('EUR', 100, 'USD', 'xml') as string;Get a list of all supported currency codes.
const currencies = await client.getSupportedCurrencies() as string[];
// Get currencies in CSV format
const csvCurrencies = await client.getSupportedCurrencies('csv') as string;Get historical exchange rates for a specific date. If toCurrency is omitted, returns rates for all currencies.
// Single currency historical rate
const rate = await client.getHistoricalRate('2024-01-01', 1, 'USD', 'EUR');
// All historical rates for base currency
const allRates = await client.getHistoricalRate('2024-01-01', 1, 'USD') as Record<string, number>;
// Historical conversion with amount
const converted = await client.getHistoricalRate('2024-01-01', 100, 'USD', 'EUR');Alias for getHistoricalRate to get all exchange rates for a base currency on a specific date.
const rates = await client.getHistoricalRates('2024-01-01', 1, 'USD') as Record<string, number>;Convert an amount using historical exchange rates for a specific date.
const converted = await client.convertHistorical(100, 'USD', 'EUR', '2024-01-01');Get time series exchange rate data over a date range (max 5 years).
// Time series for specific currencies
const timeSeries = await client.getTimeSeries(
'2024-01-01',
'2024-01-07',
1,
'USD',
['EUR', 'GBP']
) as Record<string, Record<string, number>>;
// Time series for all currencies
const allSeries = await client.getTimeSeries('2024-01-01', '2024-01-07', 1, 'USD');
// Time series with amount conversion
const convertedSeries = await client.getTimeSeries(
'2024-01-01',
'2024-01-07',
100,
'USD',
['EUR']
);Get information about available historical data limits per currency.
import { HistoricalLimitsResponse } from 'unirate-api';
const limits = await client.getHistoricalLimits() as HistoricalLimitsResponse;
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}`);
});Get VAT rates for all countries or a specific country.
import { VATRatesResponse, VATRateResponse } from 'unirate-api';
// Get all VAT rates
const allVAT = await client.getVATRates() as VATRatesResponse;
console.log(`Total countries: ${allVAT.total_countries}`);
// Get VAT rate for specific country
const germanyVAT = await client.getVATRates('DE') as VATRateResponse;
console.log(`Germany VAT rate: ${germanyVAT.vat_data.vat_rate}%`);
// Get VAT rates in CSV format
const csvVAT = await client.getVATRates(undefined, 'csv') as string;All methods support multiple output formats:
// JSON (default)
const jsonData = await client.getRate('USD', 'EUR');
// XML format
const xmlData = await client.getRate('USD', 'EUR', 'xml') as string;
// CSV format
const csvData = await client.getRate('USD', 'EUR', 'csv') as string;
// TSV format
const tsvData = await client.getRate('USD', 'EUR', 'tsv') as string;For JSON responses, you can specify a JSONP callback function:
const jsonpData = await client.getRate('USD', 'EUR', 'json', 'myCallback');import {
UnirateClient,
UnirateError,
AuthenticationError,
RateLimitError,
HistoricalLimitsResponse,
VATRatesResponse
} from 'unirate-api';
async function main() {
const client = new UnirateClient('your-api-key-here');
try {
console.log('=== Current Rates ===');
// Current exchange rate
const rate = await client.getRate('USD', 'EUR');
console.log(`Current USD to EUR: ${rate}`);
// All rates for USD
const allRates = await client.getRate('USD') as Record<string, number>;
console.log(`EUR: ${allRates.EUR}, GBP: ${allRates.GBP}`);
// Currency conversion
const converted = await client.convert('EUR', 1000, 'USD');
console.log(`1000 USD = ${converted} EUR`);
console.log('\n=== Historical Data ===');
// Historical rate
const historicalRate = await client.getHistoricalRate('2024-01-01', 1, 'USD', 'EUR');
console.log(`USD to EUR on 2024-01-01: ${historicalRate}`);
// Historical conversion
const historicalConverted = await client.convertHistorical(1000, 'USD', 'EUR', '2024-01-01');
console.log(`1000 USD = ${historicalConverted} EUR (on 2024-01-01)`);
// Time series data
const timeSeries = await client.getTimeSeries(
'2024-01-01', '2024-01-05',
1,
'USD',
['EUR', 'GBP']
) as Record<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 limits
const limits = await client.getHistoricalLimits() as HistoricalLimitsResponse;
console.log(`Total currencies: ${limits.total_currencies}`);
// VAT rates
const vatRates = await client.getVATRates() as VATRatesResponse;
console.log(`Total countries with VAT: ${vatRates.total_countries}`);
// Germany VAT
const germanyVAT = await client.getVATRates('DE');
console.log(`Germany VAT: ${(germanyVAT as any).vat_data.vat_rate}%`);
console.log('\n=== Format Examples ===');
// CSV format
const csvData = await client.getRate('USD', 'EUR', 'csv') as string;
console.log('CSV format:', csvData.substring(0, 50) + '...');
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof RateLimitError) {
console.error('Rate limit exceeded');
} else if (error instanceof UnirateError) {
console.error('API Error:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
}
main();The client provides specific exception types for different error scenarios:
import {
UnirateClient,
UnirateError,
AuthenticationError,
RateLimitError,
InvalidCurrencyError,
InvalidDateError,
APIError
} from 'unirate-api';
const client = new UnirateClient('your-api-key');
try {
const rate = await client.getRate('USD', 'INVALID');
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof InvalidCurrencyError) {
console.error('Invalid currency code');
} else if (error instanceof RateLimitError) {
console.error('Rate limit exceeded');
} else if (error instanceof InvalidDateError) {
console.error('Invalid date format');
} else if (error instanceof APIError) {
console.error(`API Error: ${error.message} (Status: ${error.statusCode})`);
} else if (error instanceof UnirateError) {
console.error(`General API Error: ${error.message}`);
}
}const client = new UnirateClient(
'your-api-key', // API key (required)
30000 // Timeout in milliseconds (optional, default: 30000)
);You can also use environment variables:
const client = new UnirateClient(process.env.UNIRATE_API_KEY!);Get your free API key from https://unirateapi.com. No credit card required!
The API supports 170+ currencies including:
Use getSupportedCurrencies() to get the complete list.
Historical data is available from 1999 to 2025, with coverage varying by currency:
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 / TypeScript React · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC
Static-site generators Astro · Eleventy · Hugo · Jekyll
CMS & e-commerce Wagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus
Data, AI & backend LangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt
Platform & tools MCP server · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian
Money library bridges money gem (Ruby) · NodaMoney (.NET)
Get a free API key at unirateapi.com.
MIT License
| Back | FazBrowse Home | New Git URL |