rate-api-python 1.0.1

Official Python client for the Rate-API.com exchange-rate & crypto API

rate-api-python

Official Python client for Rate-API.com. Standard library only — no dependencies. Python 3.8+.

Install

pip install rate-api-python

Usage

from rate_api import RateApiClient, RateApiError

client = RateApiClient("YOUR_API_KEY")

rates = client.latest("USD", ["EUR", "GBP"])
print(rates["rates"]["EUR"])

client.convert("USD", "EUR", 100)                 # Pro+
client.historical("2026-01-15", "USD", ["EUR"])   # Pro+
client.pair("USD", "EUR")                          # single pair
client.timeseries("2026-01-01", "2026-01-31")     # Business+
client.fluctuation("2026-01-01", "2026-01-31")    # Business+
client.crypto(["BTC", "ETH"])                      # Pro+
client.currencies()                                # supported currencies
client.health()                                    # public

try:
    client.timeseries("2020-01-01", "2026-12-31")
except RateApiError as e:
    print(e, e.status)   # "Date range too large. Maximum is 366 days." 400

v2 features

The client exposes the v2 endpoints directly (they resolve to /api/v2 regardless of base URL):

# Latest with 24h change, metadata and precision
r = client.latest_v2("USD", ["EUR", "GBP"], include_change=True, include_metadata=True, precision=4)
print(r["changes_pct"]["EUR"])

# Historical comparison between two dates (Pro+)
cmp = client.historical_compare("2026-01-15", "2026-01-01", "USD", ["EUR"])

# Batch conversion — up to 100 pairs in one call (Pro+)
batch = client.batch_convert([
    {"from": "USD", "to": "EUR", "amount": 100},
    {"from": "GBP", "to": "JPY", "amount": 50},
])

# Your configured rate alerts (Business+)
alerts = client.alerts()

Errors

Every failure raises RateApiError (or a subclass), so a single except RateApiError catches everything:

import time
from rate_api import RateApiClient, RateApiError, RateLimitError, RateApiTimeoutError

try:
    client.latest("USD", ["EUR"])
except RateLimitError as e:
    time.sleep(e.retry_after)                  # honour the server's backoff
except RateApiTimeoutError:
    ...                                        # request exceeded `timeout`
except RateApiError as e:
    print(e, e.status, e.type, e.request_id)

Class	When	Extra attributes
RateApiError	any API/HTTP error	status (HTTP code; None on network/timeout), type (stable error.type slug), request_id (X-Request-Id — quote it when contacting support)
RateLimitError	HTTP 429	retry_after (seconds to wait)
RateApiTimeoutError	request exceeded timeout	—

Configuration

RateApiClient(api_key, base_url="https://rate-api.com/api/v1", timeout=15, max_retries=2)

Argument	Default	Notes
base_url	https://rate-api.com/api/v1	pass …/api/v2 to target v2 directly
timeout	15	per-request socket timeout in seconds (covers headers and body)
max_retries	2	automatically retries 429/503/network/timeout with exponential backoff, honouring the server's Retry-After header

License

MIT