3 releases
new 0.0.2 | Dec 3, 2024 |
---|---|
0.0.1 | Nov 13, 2024 |
0.0.0 | Nov 3, 2024 |
#244 in Web programming
259 downloads per month
54KB
1K
SLoC
Frankfurte-rs
Rust library and CLI to interface with any Frankfurter API.
Frankfurter is a free, open source and self-hostable currency exchange rate API. It is based on data sets published by the European Central Bank.
Table of Contents
About
Frankfurte-rs (Frankfurters) is available as both an executable (frs
) and a Rust library,
with the hope of providing safe and correct bindings for the API.
[!NOTE] While the Frankfurter API works well most of the time, there are many edge cases and the returned errors are not exactly informative. If you run into any problems while using these bindings, please open an issue with the details of the error encountered.
Library
Install with cargo add lib_frankfurter
or simply add lib_frankfurter
your Cargo.toml
.
Then, check out the this example to see basic usage.
CLI
Installation
Cargo
cargo install frankfurter_cli
AUR
paru -S frs
Usage
# List the latest supported currencies
frs currencies
# Get the latest exchange rates, converting from the EUR
frs convert
# Get exchange rates from 01/01/2024 (or the closest available date with data), converting from the USD to PHP and NOK
frs convert USD -d 2024-01-01
# Get exchange rates over a time period from 01/01/2024 to the present date, converting from EUR to AUD
frs period EUR 2024-01-01 -t AUD
# Get exchange rates over a time period from 01/01/2024 to the 10/01/2024, converting from GBP to EUR and USD
frs period GBP -t EUR,USD 2024-01-01 2024-01-10
All options will print results in a table, but also accept the following options if you want the results in a different format:
--raw
: prints values only separated by tabs, useful for piping the data to different commands--json
: prints the fullJSON
response from the server
View the full usage with frs --help
.
Self-hosting
A public, free-to-use version of the API is available here, and will be used by default. However, this repo comes with a docker-compose.yml for easy self-hosting of the Frankfurter
API.
To set up and use a self-hosted version of the API, follow these steps:
- Copy/clone the
docker-compose.yml
file to your system - Run
docker compose up -d --wait
to start up both thepostgresql
database and theFrankfurter
API itself locally using Docker - When running commands, specify the desired API URL using either the
--url
flag or theFRANKFURTER_URL
environment variable:frs --url http://localhost:8080/v1
FRANKFURTER_URL="http://localhost:8080/v1 frs
Related Projects
- moneyman: Currency conversion using the same data sets from the ECB, but without the intermediary step of going through a separate API. Note that the caveat outlined there would also apply to
Frankfurter
.
Credit
- Frankfurter of course, for be the underlying API that this project wraps
- LanguageTool-Rust for inspiration and a look at how Rust API bindings should look/function
Licence
Dependencies
~11–22MB
~303K SLoC