Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
192 lines (184 sloc) 8.25 KB
---
layout: default
title: Documentation
description: >
Documentation and code examples for the Frankfurter API - current and
historical exchange rates for world currencies
---
<section class="section has-background-light">
<div class="container">
<div class="columns is-centered is-vcentered is-mobile">
<div class="column is-narrow">
<i class="fal fa-info-circle fa-2x has-text-info"></i>
</div>
<div class="column is-9-tablet is-9-desktop">
<p>
Frankfurter runs on a public instance so you can use it without having to install anything. In production, consider self-hosting.
</p>
</div>
</div>
</div>
</section>
<section class="documentation section">
<div class="container">
<div class="columns">
<div class="column is-3 is-hidden-mobile">
{% include docs-sidebar.html %}
</div>
<div class="column is-9 content">
<h1>
Documentation
</h1>
<p>
The Frankfurter API tracks foreign exchange references rates published by the <a href="https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html" target="_blank">European Central Bank</a>. The data refreshes around 16:00 CET every working day.
</p>
<p>
Frankfurter integrates seamlessly with libraries like <a href="https://openexchangerates.github.io/money.js/" target="_blank">Money.js</a> and <a href="https://sarahdayan.github.io/dinero.js/" target="_blank">Dinero.js</a>.
</p>
<h2 id="usage">Usage</h2>
<p>
The API is organised around paths that designate the requested date or date range.
<h3 id="latest">Latest</h3>
<p>
This endpoint returns the latest rates.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /latest HTTP/1.1
</code></pre>
<!--googleon: index-->
<p>
Rates quote against the Euro by default. You can quote against other currencies using the <code>from</code> parameter.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /latest?from=USD HTTP/1.1
</code></pre>
<!--googleon: index-->
<p>
<code>to</code> limits returned rates to specified values.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /latest?to=USD,GBP HTTP/1.1
</code></pre>
<!--googleon: index-->
<h3 id="historical">Historical</h3>
<p>
This endpoint returns historical rates for any working day since 4 January 1999.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /1999-01-04 HTTP/1.1
</code></pre>
<!--googleon: index-->
<p>
You can again tweak the response using the <code>from</code> and <code>to</code> parameters.
</p>
<h3 id="timeseries">Time Series</h3>
<p>
This endpoint returns a set of historical rates for a given time period.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /2010-01-01..2010-01-31 HTTP/1.1
</code></pre>
<!--googleon: index-->
<p>
If you omit the final date, Frankfurter returns all dates up to the present.</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /2010-01-01.. HTTP/1.1
</code></pre>
<!--googleon: index-->
<p>
With a full list of currencies, the response grows large in size. For better performance, use the <code>to</code> parameter to limit result to rates you are interested in.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /2010-01-01..?to=USD HTTP/1.1
</code></pre>
<!--googleon: index-->
<p>
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.
</p>
<h3 id="conversion">Conversion</h3>
<p>
You can convert any value between currencies using the above endpoints in combination with the <code>amount</code> parameter.
</p>
<p>
Below, we convert 10 British Pounds to US Dollars.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="js">
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`);
});
</code></pre>
<!--googleon: index-->
<p>
A better approach is to fetch rates once and convert client-side using <a href="https://openexchangerates.github.io/money.js/" target="_blank">Money.js</a> or <a href="https://sarahdayan.github.io/dinero.js/" target="_blank">Dinero.js</a>.
</p>
<h3 id="currencies">Currencies</h3>
<p>
This endpoint gets a list of available currency symbols along with their full names.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="http">
GET /currencies HTTP/1.1
</code></pre>
<!--googleon: index-->
<h2 id="deployment">Deployment</h2>
<p>
If you prefer to self-host, you can install Frankfurter in a few minutes.
</p>
<h3 id="docker">Docker</h3>
<p>
Run Frankfurter in the environment of your choice with Docker.
</p>
<p>
Frankfurter provides a Docker image via <a href="http://hub.docker.com/r/hakanensari/frankfurter/" target="_blank">Dockerhub</a> 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.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="sh">
docker run -d -p 8080:8080 \
-e "DATABASE_URL=&lt;postgres_url&gt;" \
--name frankfurter hakanensari/frankfurter
</code></pre>
<!--googleon: index-->
<p>
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.
</p>
<h3 id="docker-compose">Docker Compose</h3>
<p>
The source code also includes a Docker Compose configuration to run a Postgres-backed Frankfurter behind an HTTPS-enabled NGINX proxy.
</p>
<p>
Copy <a href="https://github.com/hakanensari/frankfurter/blob/master/docker-compose.yml" target="_blank">this</a> and <a href="https://github.com/hakanensari/frankfurter/blob/master/docker-compose.prod.yml" target="_blank">this file</a> from the source repo, create a <code>.env</code> file based on <a href="https://github.com/hakanensari/frankfurter/blob/master/.env.example" target="_blank">this sample</i></a>, and run the following one-liner.
</p>
<!--googleoff: index-->
<pre class="snippet"><code class="sh">
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
</code></pre>
<!--googleon: index-->
<p>
Once Let's Encrypt issues the certificate, the app will go live at the domain you defined in <code>.env</code>.
</p>
<h3 id="heroku">Heroku</h3>
<p>
Deploy a fully-functional Frankfurter to Heroku with a <a href="//heroku.com/deploy?template=https://github.com/hakanensari/frankfurter" target="_blank">single click.</a>
</p>
<p>
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.
</p>
<h2 id="support">Support</h2>
<p>
Post an issue on <a href="//github.com/hakanensari/frankfurter/issues" target="_blank">GitHub</a> or say thank you <a href="/contact">here</a>.
</p>
</div>
</div>
</div>
</section>
You can’t perform that action at this time.