NbpReq (NbpReq v0.1.0)

Copy Markdown View Source

HTTP client for the NBP Web API built on Req.

Provides access to exchange rate tables, single currency rates and gold prices published by Narodowy Bank Polski.

All functions accept the same query options (at most one of):

  • today: true - today's data (the API returns 404 if not published yet)
  • date: %Date{} - data for a specific day
  • last: n - the last n data points
  • from: %Date{}, to: %Date{} - an inclusive date range (max 367 days)

With no query option, the most recent data is returned.

Examples

NbpReq.tables(:a)
NbpReq.rates(:a, "USD", last: 10)
NbpReq.gold_prices(from: ~D[2026-01-01], to: ~D[2026-01-31])

Errors

Functions return {:error, reason} where reason is:

  • :not_found - no data for the requested day/range (HTTP 404)
  • {:bad_request, message} - invalid query, e.g. range over 367 days (HTTP 400)
  • {:http_error, status, body} - any other unexpected HTTP status
  • an exception struct (e.g. Req.TransportError) for connection errors

Summary

Types

query_opts()

Query options shared by all endpoints.

table()

Exchange rate table identifier.

Functions

gold_prices(opts \\ [])

Fetches gold prices (1g of 1000 fineness gold, in PLN).

rates(table, code, opts \\ [])

Fetches exchange rates for a single currency.

tables(table \\ :a, opts \\ [])

Fetches complete exchange rate tables.

Types

query_opts()

@type query_opts() :: [
  today: boolean(),
  date: Date.t(),
  last: pos_integer(),
  from: Date.t(),
  to: Date.t(),
  req_options: keyword()
]

Query options shared by all endpoints.

table()

@type table() :: :a | :b | :c

Exchange rate table identifier.

Functions

gold_prices(opts \\ [])

@spec gold_prices(query_opts()) :: {:ok, [NbpReq.GoldPrice.t()]} | {:error, term()}

Fetches gold prices (1g of 1000 fineness gold, in PLN).

Returns a list of NbpReq.GoldPrice structs.

Examples

{:ok, [price]} = NbpReq.gold_prices()
{:ok, prices} = NbpReq.gold_prices(last: 30)

rates(table, code, opts \\ [])

@spec rates(table(), String.t(), query_opts()) ::
  {:ok, NbpReq.CurrencyRates.t()} | {:error, term()}

Fetches exchange rates for a single currency.

code is a three-letter ISO 4217 currency code (case insensitive). Returns a NbpReq.CurrencyRates struct with one NbpReq.Rate per quoted day.

Examples

{:ok, currency} = NbpReq.rates(:a, "USD")
{:ok, currency} = NbpReq.rates(:c, "EUR", last: 10)

tables(table \\ :a, opts \\ [])

@spec tables(table(), query_opts()) :: {:ok, [NbpReq.Table.t()]} | {:error, term()}

Fetches complete exchange rate tables.

Returns a list of NbpReq.Table structs (the API always wraps tables in a list, even for a single day).

Examples

{:ok, [table]} = NbpReq.tables(:a)
{:ok, tables} = NbpReq.tables(:a, last: 5)