Frankfurter runs on a public instance so you can use it without having to install anything. In production, consider self-hosting.

Documentation

The Frankfurter API tracks foreign exchange references rates published by the European Central Bank. The data refreshes around 16:00 CET every working day.

Frankfurter integrates seamlessly with libraries like Money.js and Dinero.js.

Usage

The API is organised around paths that designate the requested date or date range.

Latest

This endpoint returns the latest rates.


          GET /latest HTTP/1.1
        

Rates quote against the Euro by default. You can quote against other currencies using the from parameter.


          GET /latest?from=USD HTTP/1.1
        

to limits returned rates to specified values.


          GET /latest?to=USD,GBP HTTP/1.1
        

Historical

This endpoint returns historical rates for any working day since 4 January 1999.


          GET /1999-01-04 HTTP/1.1
        

You can again tweak the response using the from and to parameters.

Time Series

This endpoint returns a set of historical rates for a given time period.


          GET /2010-01-01..2010-01-31 HTTP/1.1
        

If you omit the final date, Frankfurter returns all dates up to the present.


          GET /2010-01-01.. HTTP/1.1
        

With a full list of currencies, the response grows large in size. For better performance, use the to parameter to only view rates you are interested in.


          GET /2010-01-01..?to=USD HTTP/1.1
        

Frankfurter returns all data points for up to 90 days. Above that, it samples weekly or monthly based on the breadth of the date range.

Conversion

You can convert any value between currencies using the above endpoints in combination with the amount parameter.

Below, we convert 10 British Pounds to US Dollars.


          const host = 'frankfurter.app';
          fetch(`https://${host}/latest?amount=10&from=GBP&to=USD`)
            .then(resp => resp.json())
            .then((data) => {
              alert(`10 GBP = ${data.rates.USD} USD`);
            });
        

A simpler approach is to fetch rates once and convert client-side using Money.js or Dinero.js.

Currencies

This endpoint gets a list of available currency symbols along with their full names.


          GET /currencies HTTP/1.1
        

Deployment

If you prefer to self-host, you can install Frankfurter in 5 minutes.

Docker

Run Frankfurter in the environment of your choice with Docker.

Frankfurter provides a Docker image via Dockerhub that can be used for deployments on any system running Docker. Here’s a one-liner that will start a Frankfurter container with an existing PostgreSQL server running on the host or elsewhere.


          docker run -d -p 8080:8080 \
            -e "DATABASE_URL=<postgres_url>" \
            --name frankfurter hakanensari/frankfurter
        

This launches a Frankfurter instance on port 8080. Once the app starts, it will automatically build the database and populate it with data from the European Central Bank.

Docker Compose

You can run a multi-container Frankfurter with PostgreSQL and HTTPS-enabled NGINX proxy.

Copy this and this file from the source repo. Create a .env file based on this sample. Finally, run this one-liner.


          docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
        

Within a few minutes, the app should be live at the domain you defined in .env.

Heroku

Deploy Frankfurter to Heroku with just a click.

Bear in mind that if you use the default free dyno, Heroku will sleep your app if you don’t access it for a while. It can then seem like the app is initially slow to respond when actually it is just Heroku waking up the environment.

Support

Post issues on GitHub.

Or say thank you