UniRate R Client

Official R client for the UniRate API — free, real-time and historical currency exchange rates plus VAT rates.

• 🔄 Real-time exchange rates between 170+ currencies (fiat + crypto)
• 📈 Historical rates back to 1999
• ⏰ Time-series ranges up to 5 years
• 💰 Currency conversion (current and historical)
• 🏛️ VAT rates for countries worldwide
• 🆓 Free tier, no credit card required
• 📦 Minimal footprint — only curl and jsonlite (no other third-party dependencies)

Installation

From the UniRate r-universe:

install.packages("unirateapi", repos = "https://unirate-api.r-universe.dev")

Or install the development version straight from GitHub:

# install.packages("remotes")
remotes::install_github("UniRate-API/unirate-api-r")

Quick start

library(unirateapi)

client <- unirate_client("your-api-key")

# Current rate
rate <- client$get_rate(from = "USD", to = "EUR")
cat("USD -> EUR:", rate, "\n")

# Convert
euros <- client$convert(to = "EUR", amount = 100, from = "USD")
cat("100 USD =", euros, "EUR\n")

# All supported currencies
currencies <- client$get_supported_currencies()
cat(length(currencies), "currencies supported\n")

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

API

Current rates

# Single pair -> numeric
rate <- client$get_rate(from = "USD", to = "EUR")

# All rates for a base -> named numeric vector
rates <- client$get_rate(from = "USD")

# Convert an amount -> numeric
result <- client$convert(to = "EUR", amount = 100, from = "USD")

# Supported currency list -> character vector
codes <- client$get_supported_currencies()

Historical data (Pro tier)

# Rate on a specific date
rate <- client$get_historical_rate(date = "2024-01-01", from = "USD", to = "EUR")

# All rates on a date
rates <- client$get_historical_rates(date = "2024-01-01", base = "USD")

# Convert using a historical rate
amount <- client$convert_historical(amount = 100, from = "USD", to = "EUR",
                                    date = "2024-01-01")

# Time series
series <- client$get_time_series(
  start_date = "2024-01-01",
  end_date   = "2024-01-07",
  base       = "USD",
  currencies = c("EUR", "GBP")
)

# Available historical coverage per currency
limits <- client$get_historical_limits()

Historical, time-series, and limits endpoints require a Pro subscription and return a unirate_api_error (HTTP 403) on the free tier.

VAT rates

# All countries
vat_rates <- client$get_vat_rates()

# Single country (ISO-3166 alpha-2 code)
germany <- client$get_vat_rate(country = "DE")
cat("Germany VAT:", germany$vat_rate, "%\n")

Error handling

All methods raise a condition that inherits from unirate_error. Catch the base class or a specific subclass:

tryCatch(
  client$get_rate(from = "USD", to = "ZZZ"),
  unirate_authentication_error = function(e) message("invalid API key"),
  unirate_invalid_currency_error = function(e) message("unknown currency code"),
  unirate_rate_limit_error = function(e) message("back off and retry"),
  unirate_invalid_date_error = function(e) message("bad date format"),
  unirate_api_error = function(e) message("API error ", e$status),
  unirate_error = function(e) message("other UniRate error: ", conditionMessage(e))
)

Condition class	Meaning
unirate_invalid_date_error	400 — invalid request parameters
unirate_authentication_error	401 — missing or invalid API key
unirate_api_error	403 / 503 / other HTTP error (see e$status)
unirate_invalid_currency_error	404 — currency not found
unirate_rate_limit_error	429 — rate limit exceeded
unirate_base_error	network/transport or unexpected response

Dependency injection / testing

The client accepts an http_fetch function so you can stub the network in tests. A fetcher takes a URL and returns list(status = <int>, body = <chr>):

fake <- function(url) list(status = 200L, body = '{"rate": "0.9"}')
client <- unirate_client("test", http_fetch = fake)
client$get_rate("USD", "EUR")  # 0.9, no network call

Rate limits

• Currency endpoints: standard rate limits apply
• Historical endpoints: 50 requests/hour on the free tier
• VAT endpoints: 1800 requests/hour on the free tier

Related clients

• unirate-api-python — Python (PyPI: unirate-api)
• unirate-api-nodejs — Node.js / TypeScript (npm: unirate-api)
• unirate-api-go — Go
• unirate-api-rust — Rust (crates.io: unirate-api)
• unirate-api-ruby — Ruby (gem: unirate-api)
• unirate-api-php — PHP (Composer: unirate-api/unirate-api)
• unirate-api-swift — Swift (SPM)
• unirate-api-dotnet — .NET / C# (NuGet: UniRateApi)

License

MIT — see LICENSE.md.