Currency conversion

One of the most important features of TEDective is to visualize the money flow. Not all notices provide their values in Euro, so the ETL have to do conversion from different possible currencies to Euro for simplicity. In order to keep it fair, we present the value in Euro converted using the rate from the date Award/Contract was issued. This opens a need to use an external API to obtain historical currency rates. We use Frankfurter API (opens in a new tab) - an free and open-source API for current and historical foreign exchange rates published by the European Central Bank.

Obtaining the rates

When the ETL is run with such arguments:

run-pipeline --first-month 2023-10 --last-month 2023-11

one API request is going to be made obtaining rates from days that lay into the range of 2023-10 and 2023-11. These are stored as JSON file for later use.

Converting the non-EUR values

The conversion process starts when a Award/Tender is found by processor function (more details in case of eForms may be found here). Attributes needed to create OCDS object are passed to dedicated extractor.

Extractor checks if the value is in Euro currency, and if it is not, it invokes convert function from tedective_etl.utils module. This function takes amount, currency and date as attribute. The date will be used to determine the rates that are going to be used.

The way it works is pretty straight forward, the conversion function loads the rates (that were fetched before) for all available currencies that are closest to provided date.

closest_date = min(
    dates, key=lambda date: abs(datetime.strptime(date, "%Y-%m-%d") - target_date)
)

Then the actual conversion takes place:

if currency in rates:
    rate = Decimal(rates[currency])
    if rate == 0.0:
        amountEur = 0.0
    else:
        amountEur = round(Decimal(amount) / rate)
        return amountEur
    else:
        return None

The amount is then returned to the processor function.