https://github.com/ethauvin/frankfurter4j
Retrieve Reference Exchange Rates
https://github.com/ethauvin/frankfurter4j
currency currency-api currency-converter currency-data currency-exchange currency-exchange-rates exchange exchange-rates frankfurter money rates
Last synced: 3 days ago
JSON representation
Retrieve Reference Exchange Rates
- Host: GitHub
- URL: https://github.com/ethauvin/frankfurter4j
- Owner: ethauvin
- License: bsd-3-clause
- Created: 2025-05-20T21:47:04.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-28T00:03:28.000Z (about 1 month ago)
- Last Synced: 2026-05-28T00:22:24.260Z (about 1 month ago)
- Topics: currency, currency-api, currency-converter, currency-data, currency-exchange, currency-exchange-rates, exchange, exchange-rates, frankfurter, money, rates
- Language: Java
- Homepage:
- Size: 643 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Frankfurter for Java: Retrieve Reference Exchange Rates
[](http://opensource.org/licenses/BSD-3-Clause)
[](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
[](https://rife2.com/bld)
[](https://github.com/ethauvin/frankfurter4j/releases/latest)
[](https://central.sonatype.com/artifact/net.thauvin.erik/frankfurter4j)
[](https://github.com/ethauvin/frankfurter4j/packages/2561141/versions)
[](https://snyk.io/test/github/ethauvin/frankfurter4j?targetFile=pom.xml)
[](https://sonarcloud.io/summary/new_code?id=ethauvin_frankfurter4j)
[](https://github.com/ethauvin/frankfurter4j/actions/workflows/bld.yml)
[](https://circleci.com/gh/ethauvin/frankfurter4j/tree/main)
Retrieve reference exchange rates from
[Frankfurter.dev](https://frankfurter.dev/), a free, open-source currency data
API (v2)
## Examples (TL;DR)
```java
var client = new Frankfurter();
var latestRates = client.getRates();
if (latestRates instanceof ExchangeRates latest) {
var pound = latest.find("GBP");
pound.ifPresent(rate ->
System.out.println("1 GBP: " + rate.exchangeRate() + " EUR"));
}
var rate = client.getRate("USD", "EUR");
if (rate instanceof Rate dollar) {
System.out.println("1 USD: " + dollar.exchangeRate() + " EUR");
}
```
To get the latest exchange rates for the British Pound and
United States Dollar in Euro.
## bld
To use with [bld](https://rife2.com/bld), include the following dependency
in your build file:
```java
repositories = List.of(MAVEN_CENTRAL, CENTRAL_SNAPSHOTS);
scope(compile)
.include(dependency("net.thauvin.erik:frankfurter4j:1.0.0-SNAPSHOT"));
```
## Gradle, Maven, etc
To use with [Gradle](https://gradle.org/), include the following dependency
in your build file:
```gradle
repositories {
maven {
name = 'Central Portal Snapshots'
url = 'https://central.sonatype.com/repository/maven-snapshots/'
}
mavenCentral()
}
dependencies {
implementation("net.thauvin.erik:frankfurter4j:1.0.0-SNAPSHOT")
}
```
Instructions for using with Maven, Ivy, etc. can be found
on [Maven Central](https://central.sonatype.com/artifact/net.thauvin.erik/frankfurter4j).
## Latest Rates
Fetch the latest exchange rates.
```java
var client = new Frankfurter();
var latestRates = client.getRates();
```
The latest exchange rates are stored in the
[ExchangeRates](https://ethauvin.github.io/frankfurter4j/net/thauvin/erik/frankfurter/models/ExchangeRates.html)
class.
Find a specific rate.
```java
if (latestRates instanceof ExchangeRates rates) {
var gbp = rates.find("GBP").orElse(null);
}
```
The rate is stored in the [Rate](https://ethauvin.github.io/frankfurter4j/net/thauvin/erik/frankfurter/models/Rate.html)
class.
Change the base currency with base. Filter target currencies with quotes.
```java
var client = new Frankfurter();
var latestResult = client.getRates(
new RatesConfig.Builder()
.base("USD")
.quotes("EUR", "GBP")
.build()
);
```
## Historical Rates
Look up rates for a specific date.
```java
var client = new Frankfurter();
var historicalRates = client.getRates(
new RatesConfig.Builder()
.date(LocalDate.parse("1999-01-04"))
.build()
);
```
**Note**: As mentioned on the website, Frankfurter stores dates in UTC.
If you use a different time zone, be aware that you may be querying
with a different calendar date than intended. Also, data returned
for today is not stable and will update if new rates are published.
## Time Series Data
Fetch rates over a period with from and to.
```java
var client = new Frankfurter();
var timeSeries = client.getRates(
new RatesConfig.Builder()
.from(LocalDate.parse("2024-01-01"))
.to(LocalDate.parse("2024-01-10"))
.build()
);
```
## Grouping
Downsample a time series with group.
```java
var client = new Frankfurter();
var group = client.getRates(
new RatesConfig.Builder()
.from(LocalDate.of(2024, 1, 1))
.group(Group.MONTH)
.build()
);
```
## Filter by Provider
Scope to specific providers with providers.
```java
var client = new Frankfurter();
var filtered = client.getRates(
new RatesConfig.Builder()
.providers("ECB", "BAM")
.build()
);
```
## Rate
Get the rate for a single currency pair.
```java
var client = new Frankfurter();
var rate = client.getRate("USD", "EUR");
```
Optionally add date or providers.
```java
var rate = client.getRate(
new RateConfig.Builder()
.base("USD")
.quote("EUR")
.date(LocalDate.of(2026, 1, 1))
.build()
);
```
## Currency
Get details and provider coverage for a single currency.
```java
var client = new Frankfurter();
var currency = client.getCurrency("EUR");
if (currency instanceof Currency eur) {
var name = eur.name();
}
```
## Providers
List the data sources behind the API.
```java
var client = new Frankfurter();
var providers = client.getProviders();
if (providers instanceof Providers p) {
var ecb = p.find("ECB");
}
```
## Currencies
Get available currencies with provider coverage.
```java
var client = new Frankfurter();
var currencies = client.getCurrencies();
if (currencies instanceof Currencies c) {
var usd = c.find("USD");
}
```
## Currency Format
Format amounts to specific local currencies.
```java
var rate = client.getRate("USD", "GBP");
if (rate instanceof Rate r) {
var amount = 12;
var usd = CurrencyFormatter.format(amount, "USD");
var gbp = CurrencyFormatter.format(r.exchangeRate() * amount, "GBP");
System.out.println(usd + ": " + gbp); // e.g. $12.00: £9.00468
}
```
## Error
The API returns standard HTTP status codes with an error message.
```java
var rate = client.getRate("FOO", "BAR");
if (rate instanceof ErrorResponse error) {
// 422: invalid currency: FOO,BAR
System.out.println(error.status() + ": " + error.message());
}
```
## Contributing
See [CONTRIBUTING.md](https://github.com/ethauvin/frankfurter4j?tab=contributing-ov-file#readme) for information about
contributing to this project.
## More…
If all else fails, there's always more
[Documentation](https://ethauvin.github.io/frankfurter4j/).