Frankfurter for Java: Retrieve Reference Exchange Rates

Retrieve reference exchange rates from Frankfurter.dev, a free, open-source currency data API (v2)

Examples (TL;DR)

var client = new Frankfurter();

var latestRates = client.getRates();
if (latestRates instanceof ExchangeRates latest) {
    var pound = latest.find(CurrencyCode.GBP); // or latest.find("GBP")
    pound.ifPresent(rate ->
        System.out.println("1 GBP: " + rate.exchangeRate() + " EUR"));
}

var rate = client.getRate(CurrencyCode.USD, CurrencyCode.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, include the following dependency in your build file:

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, include the following dependency in your build file:

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.

Latest Rates

Fetch the latest exchange rates.

var client = new Frankfurter();
var latestRates = client.getRates();

The latest exchange rates are stored in the ExchangeRates class.

Find a specific rate.

if (latestRates instanceof ExchangeRates rates) {
   var gbp = rates.find(CurrencyCode.GBP).orElse(null);
}

The rate is stored in the Rate class.

Change the base currency with base. Filter target currencies with quotes.

var client = new Frankfurter();
var latestResult = client.getRates(
        new RatesConfig.Builder()
                .base(CurrencyCode.USD)
                .quotes(CurrencyCode.EUR, CurrencyCode.GBP)
                .build()
    );

Historical Rates

Look up rates for a specific date.

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.

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.

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.

var client = new Frankfurter();
var filtered = client.getRates(
            new RatesConfig.Builder()
                    .providers("ECB", "BAM")
                    .build()
    );

Rate

Get the rate for a single currency pair.

var client = new Frankfurter();
var rate = client.getRate(CurrencyCode.USD, CurrencyCode.EUR);

Optionally add date or providers.

var rate = client.getRate(
        new RateConfig.Builder()
        .base(CurrencyCode.USD)
        .quote(CurrencyCode.EUR)
        .date(LocalDate.of(2026, 1, 1))
        .build()
    );

Currency

Get details and provider coverage for a single currency.

var client = new Frankfurter();
var currency = client.getCurrency(CurrencyCode.EUR);

if (currency instanceof Currency eur) {
    var name = eur.name();
}

Providers

List the data sources behind the API.

var client = new Frankfurter();
var providers = client.getProviders();

if (providers instanceof Providers p) {
        var ecb = p.find(CurrencyCode.ECB);
}

Currencies

Get available currencies with provider coverage.

var client = new Frankfurter();
var currencies = client.getCurrencies();

if (currencies instanceof Currencies c) {
        var usd = c.find(CurrencyCode.USD);
}

Currency Format

Format amounts to specific local currencies.

var rate = client.getRate(CurrencyCode.USD, CurrencyCode.GBP);

if (rate instanceof Rate r) {
    var amount = 12;
    var usd = CurrencyFormatter.format(amount, CurrencyCode.USD);
    var gbp = CurrencyFormatter.format(r.exchangeRate() * amount, CurrencyCode.GBP);
    System.out.println(usd + ": " + gbp); // e.g. $12.00: £9.00468
}

Error

The API returns standard HTTP status codes with an error message.

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 for information about contributing to this project.

More…

If all else fails, there's always more Documentation.