UniRateAPI.jl

Official Julia client for the UniRate API — free currency exchange rates, historical data, and VAT rates.

• Zero third-party dependencies. HTTP goes through the Julia standard library (Downloads) and JSON is parsed by a small internal parser, so installing this package pulls in nothing beyond the standard library.
• Full parity with the other UniRate clients: current rates, conversion, supported currencies, historical rates/timeseries/limits, and VAT rates.
• A typed error hierarchy and an injectable HTTP transport for offline testing.

Installation

using Pkg
Pkg.add("UniRateAPI")

or, in the Pkg REPL (]):

pkg> add UniRateAPI

Quick start

Get a free API key at unirateapi.com.

using UniRateAPI

client = UniRateClient("your-api-key")

# Current rate
rate = get_rate(client, "USD", "EUR")          # 0.92

# Convert an amount
eur = convert_amount(client, 100, "USD", "EUR") # 92.5

# All rates for a base currency
rates = get_all_rates(client, "USD")            # Dict("EUR" => 0.92, ...)

# Supported currencies
currencies = get_supported_currencies(client)   # ["USD", "EUR", ...]

# VAT rates
vat = get_vat_rate(client, "DE")
println(vat.vat_data.vat_rate)                   # 19.0

The client reads no environment variables itself — pass the key explicitly. The bundled example reads it from UNIRATE_API_KEY:

UNIRATE_API_KEY=your-key julia --project=. examples/basic.jl

API

Construct a client with UniRateClient(api_key; timeout=30, base_url=..., transport=nothing).

Method	Returns
get_rate(client, from, to)	Float64
get_all_rates(client, from="USD")	Dict{String,Float64}
convert_amount(client, amount, from, to)	Float64
get_supported_currencies(client)	Vector{String}
get_historical_rate(client, date, from, to)	Float64
get_historical_rates(client, date, base="USD")	Dict{String,Float64}
convert_historical(client, amount, from, to, date)	Float64
get_time_series(client, start_date, end_date; amount=1, base="USD", currencies=String[])	TimeSeriesData
get_historical_limits(client)	HistoricalLimits
get_vat_rates(client)	VatRatesResponse
get_vat_rate(client, country)	VatCountryResponse

Every method also accepts format and callback keyword arguments, passed through as query parameters. Currency and country codes are uppercased automatically.

The conversion method is named convert_amount (not convert) so it does not shadow Base.convert.

Historical endpoints require a Pro subscription

get_historical_rate, get_historical_rates, convert_historical, get_time_series, and get_historical_limits are Pro-gated. On the free tier they raise an APIError with status == 403.

Error handling

Every error subtypes UniRateError, so you can catch that one type to handle all failures, or match a specific type to branch on the HTTP status.

using UniRateAPI

try
    rate = get_rate(client, "USD", "EUR")
catch e
    if e isa AuthenticationError
        # 401 — missing or invalid API key
    elseif e isa RateLimitError
        # 429 — rate limit exceeded
    elseif e isa InvalidCurrencyError
        # 404 — unknown currency or no data
    elseif e isa InvalidDateError
        # 400 — bad parameters
    elseif e isa APIError
        # e.status / e.body — includes 403 (Pro-gated) and 503
    elseif e isa TransportError
        # network failure or unparseable response
    end
end

HTTP status	Error type
400	InvalidDateError
401	AuthenticationError
403	APIError (status = 403)
404	InvalidCurrencyError
429	RateLimitError
503	APIError (status = 503)
other	APIError
network / parse	TransportError

Rate limits

The free tier is generous but rate-limited; a 429 raises RateLimitError. See unirateapi.com for current limits and Pro plans.

Testing offline

The HTTP transport is injectable. Pass a callable (url, headers) -> (status, body) as transport to run without a network — this is exactly how the test suite works:

client = UniRateClient("test-key";
                       transport = (url, headers) -> (200, """{"rate": "0.92"}"""))
get_rate(client, "USD", "EUR")  # 0.92, no network call

Run the tests with julia --project=. -e 'using Pkg; Pkg.test()'. Mock tests run by default; setting UNIRATE_API_KEY additionally runs the free-tier live tests.

Related clients

UniRate ships official clients for many languages and frameworks — Python, Node/TypeScript, Go, Rust, Ruby, PHP, Java, Swift, .NET, Dart, and more. See github.com/UniRate-API.

License

MIT © 2026 Unirate Team. See LICENSE.