Convert currencies using a dated reference rate

A currency conversion is more useful when the application explains which rate it used. Daily reference data is suitable for displaying a reference value or reporting a historical amount; it is not an executable trading quote.

Pick the amount and currencies

The conversion endpoint accepts from, to and amount, with an optional historical date. Use uppercase ISO currency codes from the supported-currencies endpoint rather than assuming every currency exists for every date.

import os
import httpx

base_url = "https://exchange-rates-api-ecb-history-conversion.p.rapidapi.com"
headers = {
    "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    "X-RapidAPI-Host": "exchange-rates-api-ecb-history-conversion.p.rapidapi.com",
}
response = httpx.get(
    base_url + "/v1/convert?from=USD&to=EUR&amount=100",
    headers=headers, timeout=120
)
response.raise_for_status()
print(response.json())

Use a published listing for production access. The free website converter uses a separate anonymous allowance. Never place your marketplace key in public frontend code.

Save the conversion with its date

Install httpx, set RAPIDAPI_KEY, and run the following on your server. Supplying query parameters separately avoids problems with URL escaping.

import os
from decimal import Decimal
import httpx

host = "exchange-rates-api-ecb-history-conversion.p.rapidapi.com"
response = httpx.get(
    f"https://{host}/v1/convert",
    headers={
        "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
        "X-RapidAPI-Host": host,
    },
    params={"from": "USD", "to": "EUR", "amount": 100},
    timeout=30,
)
response.raise_for_status()
body = response.json()
assert body["from"] == "USD" and body["to"] == "EUR"
converted = Decimal(str(body["result"]))
print(f"Reference value: {converted:.2f} EUR")
print("Rate publication date:", body["date"])

Use decimal arithmetic for subsequent monetary calculations and apply the rounding rules required by your application. Display rounding should not silently replace the full returned result in your stored record.

Understand weekends and historical dates

Reference rates are not published continuously. A weekend or publication holiday may resolve to an earlier business-day rate. Show the response's actual publication date, not the current system date. When requesting historical rates, preserve the requested date as well as the returned rate date.

For a chart, use the time-series operation rather than repeatedly requesting the same daily conversion. Stay within its documented date-span limit and retain the data's source and fixed-parity indicators where returned.

Make the failure path explicit

An unsupported currency, unavailable historical period or invalid amount can return HTTP 422. Correct the input instead of retrying it unchanged. On 429, inspect the active plan; do not treat an exhausted allowance as a transient failure. Temporary 502, 503 and 504 responses can be retried with bounded backoff.

Always label this output as a reference conversion. It does not establish the price offered by a bank, exchange or payment provider, and it is not investment guidance.