Frankfurter for Java: Retrieve Reference Exchange Rates

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

Examples (TL;DR)

var latestRates = new LatestRates.Builder()
        .amount(100.0)
        .base("USD")
        .symbols("EUR", "GBP")
        .build();
var exchangeRates = latestRates.getExchangeRates();
var euro = exchangeRates.getRateFor("EUR");
var britishPound = exchangeRates.getRateFor("GBP");

To get the latest exchange rates for the United States Dollar in Euro and British Pound.

bld

To use with bld, include the following dependency in your build file:

repositories = List.of(MAVEN_CENTRAL);

scope(compile)
    .include(dependency("net.thauvin.erik:frankfurter4j:0.9.0"));

Gradle, Maven, etc.

To use with Gradle, include the following dependency in your build file:

repositories {
    mavenCentral()
}

dependencies {
    implementation("net.thauvin.erik:frankfurter4j:0.9.0")
}

Instructions for using with Maven, Ivy, etc. can be found on Maven Central.

Latest Rates

To fetch the latest working day's rates:

var latestRates = new LatestRates.Builder().build();
var exchangeRates = latestRates.getExchangeRates();

The latest exchange rates will be stored in the ExchangeRates class:

if (exchangeRates.hasRateFor("JPY")) {
    var jpy = exchangeRates.getRateFor("JPY");
}

To change the base currency use the builder's base method. The default is EUR.

var latestRates = new LatestRates.Builder()
        .base("USD")
        .build();

To limit the response to specific target currencies.

var latestRates = new LatestRates.Builder()
        .symbols("CHF", "GBP")
        .build();

Historical Rates

To retrieve rates for a specific date.

var latestRates = new LatestRates.Builder()
        .date(LocalDate.of(1999, 1, 4))
        .build();

To change the base currency and filter target currencies.

var latestRates = new LatestRates.Builder()
        .base("USD")
        .date(LocalDate.of(1999, 1, 4))
        .symbols("EUR")
        .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

To fetch rates over a period.

var timeSeries = new TimeSeries.Builder()
        .startDate(LocalDate.of(2000, 1, 1))
        .endDate(LocalDate.of(2000, 12, 31))
        .build();
var periodicRates = timeSeries.getPeriodicRates();

The periodic rates will be stored in the TimeSeriesData class.

var firstMarketDay = LocalDate.of(2000, 1, 4);
if (periodicRates.hasRatesFor(firstMarketDay)) {
    // Get the Yen rate directly
    var yen = periodicRates.getRateFor(firstMarketDay, "JPY");

    // Get the Dollar rate if available
    var rates = periodicRates.getRatesFor(firstMarketDay);
    if (rates.containsKey("USD")) {
        var usd = rates.get("USD");
    }
}

// Loop through all dates
periodicRates.getDates().forEach(date -> {
    // Print the date
    System.out.println("Rates for " + date);
    // Loop through all rates
    periodicRates.getRatesFor(date).forEach((symbol, rate) -> {
        // Print the symbol and rate, e.g., USD: 0.9059
        System.out.println("    " + symbol + ": " + rate); 
    });
});

To fetch rates up to the present.

var timeSeries = new TimeSeries.Builder()
        .startDate(LocalDate.of(2025, 1, 1))
        .build();

To filter currencies to reduce response size and improve performance.

var timeSeries = new TimeSeries.Builder()
        .startDate(LocalDate.of(2025, 1, 1))
        .endDate(LocalDate.now())
        .symbols("USD")
        .build();

Available currencies

To get the supported currency symbols and their full names.

var currencies = AvailableCurrencies.getCurrencies();

The currencies are stored in a Currencies class that extends Hashmap.

currencies.get("USD"); // returns "United States Dollar"
currencies.getFullNameFor("usd"); // case-insensitive

currencies.getFullNameFor("EUR"); // returns "Euro"

currencies.getSymbolFor("euro"); // returns "EUR"
currencies.getSymbolFor(Pattern.compile(".*Japan.*")); // returns "JPY"

Currency Conversion

You can perform currency conversion by fetching the exchange rate with a specified amount.

var latestRates = new LatestRates.Builder()
        .amount(10)
        .base("USD")
        .symbols("EUR")
        .build();
var exchangeRates = latestRates.getExchangeRates();
var euro = exchangeRates.getRateFor("EUR");

System.out.println("$10 = €" + euro); // $10 = €8.8059

Working Days

You can retrieve a list of working days (non-weekends, non-closing days) between two dates.

var workingDays = FrankfurterUtils.workingDays(
        LocalDate.of(2021, 1, 1), LocalDate.of(2021, 1, 31));

var firstWorkingDay = workingDays.get(0); // 2021-01-04
var lastWorkingDay = workingDays.get(workingDays.size() - 1); // 2025-01-29

Currency Format

You can also format amounts for specific currencies.

FrankfurterUtils.formatCurrency("USD", 100.0); // $100.00
FrankfurterUtils.fomartCurrency("EUR", 1234.567); // 1.234,567 €
FrankfurterUtils.fomartCurrency("EUR", 1234.567, true); // 1.234,57 € rounded

Contributing

If you want to contribute to this project, all you have to do is clone the GitHub repository:

git clone git@github.com:ethauvin/frankfurter4j.git

Then use bld to build:

cd frankfurter4j
./bld compile

The project has an IntelliJ IDEA project structure. You can just open it after all the dependencies were downloaded and peruse the code.