streamlit-unirate 0.1.0

Streamlit integration for the UniRate currency-exchange API — cached helpers with st.cache_resource and st.cache_data support.

streamlit-unirate

Streamlit integration for the UniRate API — live exchange rates, currency conversion, and VAT rates with automatic st.cache_data / st.cache_resource caching built in.

Installation

pip install streamlit-unirate

Quick start

import streamlit as st
import streamlit_unirate as ur

# List currencies (cached 1 h)
currencies = ur.list_currencies()

from_cur = st.selectbox("From", currencies)
to_cur   = st.selectbox("To",   currencies)
amount   = st.number_input("Amount", value=100.0)

if st.button("Convert"):
    result = ur.convert(to_cur, amount, from_cur)
    st.metric(f"{amount} {from_cur} →", f"{result:.4f} {to_cur}")

API key

Set UNIRATE_API_KEY in .streamlit/secrets.toml (preferred) or as an environment variable:

# .streamlit/secrets.toml
UNIRATE_API_KEY = "your_api_key_here"

UNIRATE_API_KEY=your_key streamlit run app.py

Get a free key at unirateapi.com.

API reference

All functions use Streamlit's caching automatically — no extra decorators needed.

get_client(api_key=None, base_url=None)

Returns the underlying unirate.UnirateClient singleton (cached via @st.cache_resource). Use this when you need direct access to Pro endpoints such as historical rates or time series.

client = ur.get_client()
data = client.get_time_series("2025-01-01", "2025-01-31", base_currency="USD")

get_rate(from_currency="USD", to_currency=None) → float | dict

Current exchange rate. Cached for 5 minutes.

rate = ur.get_rate("USD", "EUR")          # → 0.9214  (float)
all_rates = ur.get_rate("USD")            # → {"EUR": 0.92, "GBP": 0.79, ...}

convert(to_currency, amount=1.0, from_currency="USD") → float

Convert an amount. Cached for 5 minutes.

eur = ur.convert("EUR", 250.0, "USD")     # → 230.35

list_currencies() → list[str]

All supported currency codes. Cached for 1 hour.

codes = ur.list_currencies()              # → ["AED", "AFN", ..., "ZWL"]

get_vat_rates(country=None) → dict

VAT rates for all countries or a single ISO-3166 country code. Cached for 24 hours.

all_vat = ur.get_vat_rates()
de_vat  = ur.get_vat_rates("DE")

Error handling

All functions raise exceptions from unirate.exceptions:

Exception	Cause
AuthenticationError	Missing or invalid API key
RateLimitError	Free-tier rate limit exceeded
InvalidCurrencyError	Unknown currency code
APIError	Other API error (check .status_code)

from unirate.exceptions import RateLimitError, AuthenticationError
import streamlit_unirate as ur

try:
    rate = ur.get_rate("USD", "EUR")
except AuthenticationError:
    st.error("Check your UNIRATE_API_KEY.")
except RateLimitError:
    st.warning("Rate limit hit — try again in a moment.")

Related UniRate clients

Other UniRate integrations: Python · Node.js · Go · Rust · Ruby · PHP · Java · Swift · .NET · FastAPI · Flask · Django REST · Wagtail · Next.js · Nuxt · SvelteKit · React · Vue · Angular · Remix · NestJS · LangChain (Python) · LangChain.js · Astro · Eleventy · Hugo · Jekyll · Strapi · Directus · Medusa · MCP Server · CLI

License

MIT — see LICENSE.