Forex - European Central Bank (ECB) exchange rates for Elixir

Your Libraries & OS Mentoring Libraries
1

Hey, just released a small library called Forex, to retrieve the European Central Bank daily exchange rates.

The idea behind the library is to provide a simple, no API keys, no authentication, no rate limits, just a simple Elixir library that fetches the data from the European Central Bank and caches it for later use.

With this said take into account this is not aimed at building any type of transactional app, financial applications or any type of application that relies on to the second foreign exchange rates. The reference rates from the ECB are usually updated at around 16:00 CET every working day. This is useful for information purposes, for example, you might want to show on your job board how much is the role salary range in the user’s local currency, etc.

Usage

By default the base currency is the Euro (EUR), the same as the European Central Bank,
but you can change the base currency by passing the base option to the relevant functions.

Sample Usage

To fetch the latest exchange rates, you can use the current_rates/1 function:

iex> Forex.current_rates()
{:ok,
  %{
    base: :eur,
    date: ~D[2025-03-12],
    rates: %{
      usd: Decimal.new("1.1234"),
      jpy: Decimal.new("120.1234"),
      ...
      zar: Decimal.new("24.1442")
    }}
  }

If you use it and found a bug or have any suggestion, don’t hesitate to create an issue or post here. :slight_smile:

Thanks,

Nuno F.

Hex: forex | Hex
Repo:

13 Likes
2

Forex.base_currency_rate/0 is not documented. Looks like it’s used by other functions. Should it be defp instead or maybe @doc false (in case you use it in other modules too)?

I would rather suggest to return structs instead of maps in case you already know what keys and values you have to expect. This would save lots of time on debugging for trivial typos.

You should consider using typespecs now. I’ve got that’s not supposed to be a 1.0.0 release and it does not need to be a top #1 priority, but it would definitely affect the documentation. For example let’s take a look at Forex.options/1.

With a spec like:

@spec options(Keyword.t()) :: options
# or even
@spec options(input_options) :: options

You can define options type, move all options documentation there and finally use options type in spec for other functions. This way you don’t have to copy-paste same documentation as developers interested what options are supported would simply hover or click on the options type link in the function spec.

@spec current_rates(input_options | options) :: map

In this example both options types are just Keyword.t(), but with different @typedoc. The input_options only have to mention that options/1 function would be used to get validated options. This way documentation would be much easier to read.

Please do not use spaces before header syntax in markdown, see: Forex — forex v0.1.1

You should change this line:

to:

    source_ref: "v" <> @version,

This is because your tags have v before version (which is not bad at all) and you don’t have a branch with this version. I guess you have copy-pasted a “working” configuration, but forgot to work in the branch. Because of that tiny mistake all links to the source code does not work.

You may be interested in adding badges to your README.md file, see:

It would be amazing to have a function like Forex.exchange_historic_rate(historic_date). This way people can create an example sites (like shop template) with a real prices. In many cases there would be no need to update the prices because of inflation which may be especially useful if in such template are used base products like food.

Please keep in mind that’s a public post. You may already know what I wrote, but it may be helpful for others.

3 Likes
3

That’s actually quite nice. Usually that stuff comes with all of those limits. Also daily updates is actually fine for a lot of stuff.

2 Likes
4

Thanks for your suggestions! This was just a first release, I actually forgot to delete the application mod, the library is supposed to be started in the supervision tree, of course.
So already doing some changes.

1 Like
6

This is exactly what this library does, but with pluggable Cache and client and some extra utilities. :slight_smile:

Still rewriting some stuff, adding more tests and some extra utilities. Will release a new version soon.

1 Like
7

@greven Thanks for creating this library , I will check it for sure.
We are working on setting a fintech startup and one of the possibilities we study is working in EU where we found some compliance mandates about transparency with customers about FX and FX markup :slight_smile:

8

@greven Any prerequisites or configuration ? I am trying it in livebook and getting the below error on latest_rates call :

** (ArgumentError) raise/1 and reraise/2 expect a module name, string or exception as the first argument, got: {Forex.FeedError, %Req.TransportError{reason: {:tls_alert, {:unknown_ca, ~c"TLS client: In state wait_cert_cr at ssl_handshake.erl:2183 generated CLIENT ALERT: Fatal - Unknown CA\n"}}}}
    (forex 0.2.2) lib/forex.ex:257: Forex.latest_rates!/1
    #cell:35z7tfano3gndsoq:1: (file)
9

Hmm weird. I’m releasing a new version soon with the changes I highlighted above. So keep tuned for that.

There is no configuration needed. That’s an SSL issue. By default I’m using Req as the client. The error is an issue I had but it’s already fixed in the next version. Dunno why there might be a certificate error with the request tho.

Thanks for reporting.

2 Likes