wagtail-unirate 0.1.0

Wagtail integration for the UniRate currency-exchange API — StreamField blocks, Django template tags, and a cached client wired through Django settings.

wagtail-unirate

Wagtail + Django integration for the UniRate currency-exchange API. Drop currency rates, conversions, and multi-currency price tables straight into Wagtail page bodies; use template tags anywhere in Django templates.

• StreamField blocks: CurrencyRateBlock, CurrencyConversionBlock, MultiCurrencyPriceBlock.
• Template tags under {% load unirate %}: unirate_rate, unirate_convert, unirate_to, unirate_format, unirate_currencies, unirate_historical_rate.
• Cached lookups via Django's standard cache framework (opt-in via UNIRATE_CACHE_TIMEOUT).
• Wagtail 5.x / 6.x · Django 4.2 / 5.0 / 5.1 / 5.2 · Python 3.10–3.13.
• No new HTTP code: every network call goes through the official unirate-api Python client.

Install

pip install wagtail-unirate

Add to INSTALLED_APPS (after the wagtail.* apps):

INSTALLED_APPS = [
    # …
    "wagtail",
    "wagtail_unirate",
]

Set your API key in settings.py or as an environment variable:

UNIRATE_API_KEY = os.environ["UNIRATE_API_KEY"]

Get a free key at https://unirateapi.com.

Settings

Setting	Default	Description
UNIRATE_API_KEY	—	API key. Falls back to the UNIRATE_API_KEY env var.
UNIRATE_BASE_URL	https://api.unirateapi.com	Override the API base (rare; testing or a self-hosted proxy).
UNIRATE_TIMEOUT	30	Per-request timeout in seconds.
UNIRATE_CACHE_TIMEOUT	0 (off)	If positive, latest-rate / convert / supported-currency lookups are cached for this many seconds via Django's cache framework.
UNIRATE_CACHE_ALIAS	default	The CACHES alias used when caching is enabled.
UNIRATE_DEFAULT_BASE_CURRENCY	USD	Default base for the unirate_to template tag.

Template tags

{% load unirate %}

Today's USD/EUR rate: {% unirate_rate "USD" "EUR" %}

100 USD ≈ {% unirate_convert 100 "USD" "EUR" %} EUR

A price of 9.99 in the configured base ≈
{% unirate_to 9.99 "JPY" %} JPY

{% unirate_format 1234.56 "EUR" %}   {# → "1,234.56 EUR" #}

{% unirate_currencies as codes %}
Supported codes: {{ codes|join:", " }}

Historical (Pro plan):
{% unirate_historical_rate "USD" "EUR" "2025-01-15" %}

Every value-returning tag falls back silently to None (or [] for unirate_currencies) on API errors so a third-party blip cannot break a page render.

StreamField blocks

from wagtail import blocks
from wagtail.fields import StreamField
from wagtail_unirate.blocks import (
    CurrencyConversionBlock,
    CurrencyRateBlock,
    MultiCurrencyPriceBlock,
)


class HomePage(Page):
    body = StreamField(
        [
            ("paragraph", blocks.RichTextBlock()),
            ("currency_rate", CurrencyRateBlock()),
            ("currency_conversion", CurrencyConversionBlock()),
            ("multi_currency_price", MultiCurrencyPriceBlock()),
        ],
        use_json_field=True,
    )

Editors then get three new blocks in the Wagtail page editor. Each block renders inline HTML and silently swallows API failures (it falls back to an empty fragment) so a transient blip never breaks the page.

Caching tip

Currency rates change slowly. A 5- to 15-minute cache window is usually plenty and removes virtually all per-request UniRate calls on a busy site:

UNIRATE_CACHE_TIMEOUT = 600  # 10 minutes

License

MIT.