CurrencyConverter

Warnings

• gotcha The default `CurrencyConverter()` constructor uses embedded historical data that is packaged with the library and might be significantly outdated. It does not query real-time APIs. For up-to-date historical rates, you must explicitly initialize it with `ECB_URL` (e.g., `CurrencyConverter(ECB_URL)`), which downloads the latest full historical data from the European Central Bank upon initialization.
  Fix: Always initialize with `CurrencyConverter(ECB_URL)` if you need recent historical rates. Be aware this requires an internet connection and will download the full historical dataset on initialization. Consider caching the downloaded file for performance in production environments.
• gotcha The ECB data primarily provides rates against the Euro (EUR) and starts from January 1, 1999. Requesting conversions for dates before 1999 will raise a `RateNotFoundError` by default.
  Fix: If you need to handle dates outside the ECB's historical range, initialize the converter with `fallback_on_wrong_date=True` (e.g., `CurrencyConverter(fallback_on_wrong_date=True)`). This will use the earliest or latest available rate for dates before or after the data's bounds, respectively. Also, be aware that while it converts between non-EUR currencies, these conversions are implicitly routed through EUR.
• gotcha A `RateNotFoundError` can occur if specific currency rates are missing for a requested date within the available data range. This is distinct from requesting dates outside the overall data bounds.
  Fix: To enable fallbacks for missing rates on specific dates, initialize the converter with `fallback_on_missing_rate=True`. You can also configure the method of fallback (e.g., `fallback_on_missing_rate_method='last_known'` or `'linear_interpolation'`).

Install

• pip install currencyconverter Install via pip

Imports

• CurrencyConverter

  from currency_converter import CurrencyConverter

• ECB_URL

  from currency_converter import ECB_URL

  Used to fetch the latest historical data from ECB.

Quickstart

Initialize the `CurrencyConverter` object, optionally providing `ECB_URL` to download the latest historical rates. Then use the `convert()` method to perform conversions between an amount, source currency, target currency, and an optional specific date.

from currency_converter import CurrencyConverter, ECB_URL
from datetime import date
import os

# Initialize converter with the latest historical data from ECB (requires internet connection)
# This downloads the full history, which can take a moment.
# If you prefer to use the embedded data (might be outdated), use `c = CurrencyConverter()`
c = CurrencyConverter(ECB_URL)

# Convert 100 USD to EUR using the latest available rate
amount_eur = c.convert(100, 'USD', 'EUR')
print(f"100 USD = {amount_eur:.2f} EUR (latest historical rate)")

# Convert 50 EUR to GBP on a specific date
specific_date = date(2020, 1, 15)
amount_gbp = c.convert(50, 'EUR', 'GBP', date=specific_date)
print(f"50 EUR on {specific_date} = {amount_gbp:.2f} GBP")

# List available currencies (e.g., to check supported codes)
# print(c.currencies)