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 limit result to 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 starts sampling by week or month 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 better 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 a few 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. The following one-liner starts 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 automatically builds the database, populating it with data from the European Central Bank.

Docker Compose

The source code also includes a Docker Compose configuration to run a Postgres-backed Frankfurter behind an HTTPS-enabled NGINX proxy.

Copy the configuration file from the source repo, create a .env file based on this sample, and run the following.


          docker-compose up -d
        

Once Let's Encrypt issues the certificate, the app will go live at the domain you defined in .env.

Heroku

Deploy a fully-functional Frankfurter to Heroku with a single 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 an issue on GitHub or say thank you here.