nbp-api-client

A modern TypeScript/JavaScript library for retrieving data from the public API of the National Bank of Poland (NBP). It provides a simple-to-use interface for managing currency exchange rates, historical data, and gold prices.

The library is fully typed, written in modern JavaScript (ES Modules), and production-ready with complete tree-shaking support.

📦 Installation

npm install nbp-api-client

yarn add nbp-api-client

pnpm add nbp-api-client

🚀 Quick Start

import { NBPApiClient } from "nbp-api-client";

const client = new NBPApiClient();

// Get current exchange rates
const currentRates = await client.getRates({ mode: 'current' });

// Get current gold price
const goldPrice = await client.getGoldPrice();

// Get exchange rate tables
const tables = await client.getTables({ table: 'A', mode: 'current' });

🛠️ Development

To run the full quality suite locally:

npm install
npm run build       # compile TypeScript to dist/
npm run lint        # static analysis
npm run test        # run unit tests
npm run coverage    # generate coverage report

The package also includes a prepare script so that if you install directly directly from the Git repository (e.g. npm install username/nbp-api-client), it will compile automatically.

🤝 Contributing

Please open issues for bugs or feature requests and send pull requests with clear descriptions. The library follows semantic versioning; bump the version in package.json and update the changelog when adding features or fixes.

⚙️ Configuration

import { 
  NBPApiClient, 
  OutputFormatEnum, 
  GoldMeasureUnitEnum,
  Iso4217CurrencyCodeEnum 
} from "nbp-api-client";

const client = new NBPApiClient({
  // Response format: 'json' or 'xml'
  outputFormat: OutputFormatEnum.JSON,
  
  // Enable debug logging to console
  debug: true,
  
  // Reference currency (default: USD)
  currency: Iso4217CurrencyCodeEnum.USD,
  
  // Unit of measure for gold prices: 'ounces' or 'grams'
  unit: GoldMeasureUnitEnum.OUNCES,
});

📊 Getting Exchange Rates (getRates)

The getRates() method allows you to retrieve currency exchange rates from NBP in various time-based variants. You need to specify the table (A, B or C) and currency code.

Current rates

// Get current exchange rate for USD from table A
const rates = await client.getRates({ 
  table: 'A',
  code: 'USD',
  mode: 'current' 
});

Top N rates

// Get the last 10 rate quotes for USD from table A
const topRates = await client.getRates({ 
  table: 'A',
  code: 'USD',
  mode: 'top-count',
  maxCount: 10 
});

Today's rates

// Get rates for today
const todayRates = await client.getRates({ 
  table: 'A',
  code: 'USD',
  mode: 'today' 
});

Rates for a specific date

// Get rates for a specific day
const dateRates = await client.getRates({ 
  table: 'A',
  code: 'USD',
  table: 'A',
  code: 'USD',
  mode: 'date',
  date: '2024-01-15'
  // or
  date: new Date('2024-01-15')
});

Rates for a date range

// Get rates for a time period
const rangeRates = await client.getRates({ 
  table: 'A',
  code: 'USD',
  mode: 'date-range',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Rates from N days ago

// Get rates from the last 7 days before a date
const pastRates = await client.getRates({ 
  table: 'A',
  code: 'USD',
  mode: 'days-before',
  days: 7,
  date: '2024-01-15'
});

Rates for the next N days

// Get rates for the next 5 days from a date
const futureRates = await client.getRates({ 
  table: 'A',
  code: 'USD',
  mode: 'days-after',
  days: 5,
  date: '2024-01-15'
});

💰 Getting Gold Price Data (getGoldPrice)

The getGoldPrice() method provides access to current and historical gold prices in various currencies and units of measure.

Current gold price

// Get the current gold price
const currentGold = await client.getGoldPrice();

// Equivalent to:
const currentGold = await client.getGoldPrice({ 
  mode: 'current' 
});

const todayGold = await client.getGoldPrice({ 
  mode: 'today' 
});

Gold price from a specific date

// Get the gold price from a specific day onwards
const fromDateGold = await client.getGoldPrice({ 
  mode: 'from-date',
  date: '2024-01-01'
});

Gold price for a time range

// Get gold prices for a time period
const rangeGold = await client.getGoldPrice({ 
  mode: 'between-dates',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Gold price from N days ago

// Get gold prices from the last 30 days
const pastGold = await client.getGoldPrice({ 
  mode: 'days-before',
  days: 30,
  date: '2024-01-31'
});

Gold price for the next N days

// Get gold prices for the next 10 days
const futureGold = await client.getGoldPrice({ 
  mode: 'days-after',
  days: 10,
  date: '2024-01-01'
});

Changing currency and unit of measure

const goldPrice = await client.getGoldPrice({
  mode: 'current',
  // Get in EUR instead of USD
  currency: Iso4217CurrencyCodeEnum.EUR,
});

// Change unit to grams
const goldInGrams = await client.getGoldPrice({
  mode: 'current',
  // The global configuration won't change
  // Set the unit in the constructor
});

📈 Getting Exchange Rate Tables (getTables)

The getTables() method allows you to retrieve complete exchange rate tables published by NBP.

NBP publishes three main tables: A, B, and C, containing rates for various currencies.

Current table

// Get current Table A
const tableA = await client.getTables({ 
  table: 'A',
  mode: 'current' 
});

// Available tables: 'A', 'B', 'C'
const tableB = await client.getTables({ table: 'B', mode: 'current' });
const tableC = await client.getTables({ table: 'C', mode: 'current' });

Last N tables

// Get the last 5 Table A publications
const lastTables = await client.getTables({ 
  table: 'A',
  mode: 'top-count',
  maxCount: 5 
});

Table from today

const todayTable = await client.getTables({ 
  table: 'A',
  mode: 'today' 
});

Table for a specific date

const specificTable = await client.getTables({ 
  table: 'A',
  mode: 'specified-date',
  date: '2024-01-15' 
});

Tables for a date range

const rangeTable = await client.getTables({ 
  table: 'A',
  mode: 'between-dates',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Tables from the last N days

// Get tables from the last 7 days
const pastTables = await client.getTables({ 
  table: 'A',
  mode: 'days-before',
  days: 7,
  date: '2024-01-31'
});

Tables for the next N days

// Get tables for the next 5 days
const futureTables = await client.getTables({ 
  table: 'A',
  mode: 'days-after',
  days: 5,
  date: '2024-01-01'
});

🔧 Advanced Configuration

Debugging

const client = new NBPApiClient({
  debug: true
});

// Logs with sent requests will appear in the console
// 2024-03-12 14:30:45 | NBPApiClient | Sending request to url: ...

Output Format

The library supports both JSON (default) and XML:

import { OutputFormatEnum } from "nbp-api-client";

// JSON (default)
const jsonClient = new NBPApiClient({
  outputFormat: OutputFormatEnum.JSON
});

// XML
const xmlClient = new NBPApiClient({
  outputFormat: OutputFormatEnum.XML
});

📋 Supported Currencies

The library supports all currencies according to the ISO 4217 standard, including:

• USD - US Dollar
• EUR - Euro
• GBP - British Pound
• JPY - Japanese Yen
• CHF - Swiss Franc
• CAD - Canadian Dollar
• AUD - Australian Dollar
• CNY - Chinese Yuan
• INR - Indian Rupee
• And many more...

import { Iso4217CurrencyCodeEnum } from "nbp-api-client";

const client = new NBPApiClient({
  currency: Iso4217CurrencyCodeEnum.EUR
});

📝 Types and Enums

Enums

import {
  OutputFormatEnum,
  GoldMeasureUnitEnum,
  TableCodeEnum,
  GetGoldPriceEnum,
  GetTableDataEnum,
  Iso4217CurrencyCodeEnum
} from "nbp-api-client";

// Output format
OutputFormatEnum.JSON | OutputFormatEnum.XML

// Unit of measure for gold
GoldMeasureUnitEnum.OUNCES | GoldMeasureUnitEnum.GRAMS

// Table codes
TableCodeEnum.A | TableCodeEnum.B | TableCodeEnum.C

// Modes for retrieving gold data
GetGoldPriceEnum.CURRENT | GetGoldPriceEnum.TODAY | GetGoldPriceEnum.FROM_DATE | GetGoldPriceEnum.BETWEEN_DATES | GetGoldPriceEnum.DAYS_BEFORE | GetGoldPriceEnum.DAYS_AFTER

// Modes for retrieving table data
GetTableDataEnum.CURRENT | GetTableDataEnum.TOP_COUNT | GetTableDataEnum.TODAY | GetTableDataEnum.SPECIFIED_DATE | GetTableDataEnum.BETWEEN_DATES | GetTableDataEnum.DAYS_BEFORE | GetTableDataEnum.DAYS_AFTER

Types

import type {
  GetRatesParams,
  GetGoldPriceParams,
  GetTablesParams,
  GetRatesResponse,
  GetGoldPriceResponse,
  GetTableResponse
} from "nbp-api-client";

🧪 Testing

npm run test

🔍 Linting

npm run lint

🏗️ Building

npm run build

The compiled code is located in the dist/ directory.

📚 Resources

• Official NBP API
• NBP API Documentation - Details about endpoints, formats, and limitations
• ISO 4217 - Currency codes standard

📄 License

MIT © 2026 miqel-dll

🤝 Support

If you encounter a problem or have a suggestion, please open an issue on GitHub.

Author: miqel-dll
Version: 1.1.1