A lightweight, type-safe JavaScript/TypeScript client for the Frankfurter Currency Exchange Rates API, designed for developers who want clean abstractions, strong date validation, and a minimal API surface. This package wraps the Frankfurter API with strict input validation, predictable error handling, and zero runtime configuration.
npm install frankfurter-api-client💡 Note: This client is powered by the official Frankfurter API. No API Keys are required. The package is currently supporting Frankfurter Client V1, next version package will come up in the near future.
- TypeScript-first with full type definitions
- Strict date validation (including leap years & future dates)
- Supports historical rates and time-series queries
- Minimal dependencies: dayjs only
- Clean, promise-based API - Works in both Node.js and modern browsers
- Get Latest Exchange Rates
import { getLatestRates } from 'frankfurter-api-client';
const response = await getLatestRates({
base: 'EUR',
symbols: ['USD', 'INR'] /* symbols part in the input props is optional */,
});
/*
{
base: "EUR",
date: "2025-01-10",
rates: {
USD: 1.09,
INR: 90.42,
...
}
}
*/- Get Historical Rates for a Specific Date
import { getHistoricalRatesForDate } from 'frankfurter-api-client';
const data = await getHistoricalRatesForDate({
base: 'USD',
symbols: ['EUR', 'GBP'] /* symbols part in the input props is optional */,
period: {
year: 2023,
month: 10 /* 1 (Jan) ... 12 (Dec), not indexed value */,
date: 12 /* range between 1 and 31 */,
},
});
/*
{
base: "USD",
date: "2023-10-12",
rates: {
EUR: 0.94,
GBP: 0.82,
...
}
}
*/- Get Time Series Rates Between Two Dates
import { getTimeSeriesRates } from 'frankfurter-api-client';
const data = await getTimeSeriesRates({
base: 'EUR',
symbols: ['USD'] /* symbols part in the input props is optional */,
start: {
year: 2023,
month: 1 /* 1 (Jan) ... 12 (Dec), not indexed value */,
date: 1 /* range between 1 and 31 */,
},
end: {
year: 2023,
month: 1 /* 1 (Jan) ... 12 (Dec), not indexed value */,
date: 5 /* range between 1 and 31 */,
},
});
/*
{
base: "EUR",
start_date: "2023-01-01",
end_date: "2023-01-05",
rates: {
"2023-01-01": { USD: 1.07 },
"2023-01-02": { USD: 1.06 },
"2023-01-03": { USD: 1.05 }
...
...
}
}
*/- Get Supported Currencies
import { getSupportedCurrencies } from 'frankfurter-api-client';
const data = await getSupportedCurrencies(); /* no input props required */
/*
{
USD: "United States Dollar",
EUR: "Euro",
GBP: "British Pound Sterling",
INR: "Indian Rupee",
...
...
}
*/PASS src/get-supported-currencies/test/index.test.ts
getSupportedCurrencies
✓ throws when fetch response is not ok
✓ returns payload when response ok
✓ targets the currencies endpoint
PASS src/get-latest-rates/test/index.test.ts
getLatestRates
✓ throws when fetch response is not ok
✓ returns payload when response ok
✓ targets the latest rates endpoint with base only
✓ adds symbols when provided
PASS src/get-timeseries-rates/test/index.test.ts
getTimeSeriesRates
✓ throws when start date is after end date
✓ throws when fetch response is not ok
✓ returns payload when response ok
✓ targets the timeseries endpoint with base only
✓ adds symbols when provided
PASS src/shared/test/index.test.ts
shared
✓ API_ROOT points to frankfurter api base
validateAndFormatDate
✓ returns YYYY-MM-DD for valid date
✓ throws for invalid year
✓ throws for invalid month
✓ throws for invalid date
✓ throws for date after today
✓ throws for future year
PASS src/get-historical-rates/test/index.test.ts
getHistoricalRatesForDate
✓ throws when fetch response is not ok
✓ returns payload when response ok
✓ targets the historical endpoint with base only
✓ adds symbols when provided
Test Suites: 5 passed, 5 total
Tests: 23 passed, 23 total
Snapshots: 0 total
------------------------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
------------------------------|---------|----------|---------|---------|-------------------
All files | 99.43 | 96.77 | 100 | 99.43 |
get-historical-rates | 100 | 100 | 100 | 100 |
index.ts | 100 | 100 | 100 | 100 |
get-latest-rates | 100 | 100 | 100 | 100 |
index.ts | 100 | 100 | 100 | 100 |
get-supported-currencies | 100 | 100 | 100 | 100 |
index.ts | 100 | 100 | 100 | 100 |
get-timeseries-rates | 100 | 100 | 100 | 100 |
index.ts | 100 | 100 | 100 | 100 |
shared | 97.5 | 90.9 | 100 | 97.5 |
index.ts | 100 | 100 | 100 | 100 |
validate-and-format-date.ts | 97.43 | 90.9 | 100 | 97.43 | 29
------------------------------|---------|----------|---------|---------|-------------------
- Frankfurter API Client: V1: https://www.npmjs.com/package/frankfurter-api-client
- Frankfurter API Client: V2: https://www.npmjs.com/package/frankfurter-api-client-v2
- Frankfurter API Status Client: https://www.npmjs.com/package/frankfurter-api-status-client
Contributions, suggestions, and improvements are welcome.
Feel free to open issues or pull requests.
- This package is open source and intended to provide reusable utilities for application development. It does not collect, store, transmit, sell, or share user data, and it does not include analytics, tracking, telemetry, cookies, local storage usage, backend services, or project-owned data collection mechanisms.
- For more details, including vulnerability reporting guidance and consumer security recommendations, please see the Security Policy.
Like this project? Support it with a github star, it would mean a lot to me! Cheers and Happy Coding.