nbp_rates
A modular Python library for providing NBP (Narodowy Bank Polski) exchange rates with both offline and online support. Very fast and easy to use.
Features
- Offline Support: Includes historical exchange rates data from 1984 to 02-September-2026
- Online Fallback: Automatically fetches from NBP API for dates after 02-September-2026
- Dual Table Support: Supports both Table A (major currencies) and Table B (minor currencies)
- Smart Fallback: Optionally searches last available rate before given date (handles holidays, weekends and missing data)
- Super Fast: Optimized for speed with most queries served from local data with minimal API calls
- Easy and Powerful: Simple to use with 200+ currencies supported
- Precise and exact output: No rounding within library. Results provided as string to avoid floating-point rounding issues
- Reliable: As most of data is served offline, it is not affected by NBP API downtime, responsiveness or rate limits
- Flexible Date Input: Accepts
datetime.date,datetime.datetime, or ISO format strings (YYYY-MM-DD) - No external dependencies: Pure Python with standard library
- Daily Updates: new version of library released daily with the latest exchange rates available offline
Installation
Install from PyPI:
pip install nbp_rates
Or install in development mode from the repository:
git clone https://github.com/varciasz/nbp_rates.git
cd nbp_rates
pip install -e .
Requirements
- Python 3.6 or higher
- No external dependencies (uses only Python standard library)
Usage
Basic Usage
Get the exchange rate for a specific date and currency:
from nbp_rates import ProvideCurrencyRate
from datetime import date
# Get USD rate for a specific date
rate = ProvideCurrencyRate(date(2024, 1, 15), 'USD')
print(f"USD rate on 2024-01-15: {rate}")
# Using a string date (ISO format)
rate = ProvideCurrencyRate('2024-01-15', 'EUR')
print(f"EUR rate on 2024-01-15: {rate}")
# Using datetime object
from datetime import datetime
rate = ProvideCurrencyRate(datetime(2024, 1, 15, 10, 30), 'GBP')
print(f"GBP rate on 2024-01-15: {rate}")
Using Fallback
Enable fallback to search up to 31 days back for an available rate (useful for holidays, weekends and missing data):
# Get rate for a holiday, falling back to previous business day if needed
rate = ProvideCurrencyRate(date(2024, 1, 1), 'USD', fallback=True)
print(f"USD rate: {rate}")
Return Values
- Successfully fetched rate: String representation of the exchange rate (e.g.,
"4.25") - Currency not found:
"Error - wrong currency" - Module loading error:
"Error - unable to load currency module" - Fallback limit exceeded or rate not found:
"-1"
Supported Currencies
The library supports 200+ currencies including:
Major currencies (Table A): USD, EUR, GBP, JPY, CHF, CAD, AUD, and many more
Minor currencies (Table B): INR, CNY, MXN, BRL, ZAR, SGD, and many more
See the source code for the complete list of TABLE_A_CURRENCIES and TABLE_B_CURRENCIES.
API Reference
ProvideCurrencyRate(date_given, currency, fallback=False, _depth=0)
Fetches the FX rate for a given date and currency.
Parameters:
date_given(datetime.date, datetime.datetime, or str): The date for which to fetch the ratecurrency(str): ISO 4217 currency code (e.g., 'USD', 'EUR')fallback(bool, optional): If True, searches up to 31 days back for available rates. Default: False_depth(int, optional): Internal parameter for recursion tracking. Default: 0
Returns:
- str: Exchange rate as a string, or error message
Raises:
- ValueError: If the date format is invalid or currency is not recognized
SupportedCurrencies
A sorted list of all supported currency codes exposed by the package.
from nbp_rates import SupportedCurrencies
print("EUR" in SupportedCurrencies)
# True
Type: list[str]
Notes:
- The list is alphabetically sorted for easy discovery and iteration.
- It contains the union of currencies available in both NBP tables (A and B).
Data Sources
- Offline Data: Embedded exchange rate data from 1984 to 02-September-2026
- Online Data: NBP API (
https://api.nbp.pl/) for dates after the offline data cutoff
License
This project is licensed under the MIT License - see the LICENSE file for details.
Author
Sebastian Kowalik
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Changelog
Current Version 1.7.20260903
- Library is updated daily with the latest exchange rates included offline. Last 8 digits of version number represent the date when the version was generated (YYYYMMDD).
Version 1.7
- Added
SupportedCurrencies, a sorted list of all supported currencies.
Version 1.6
- Added support for easy version checking
import nbp_rates
print(nbp_rates.__version__)
Version 1.5
- First official stable version with automated daily updates and support for 200+ currencies.
1 maintainer
Release files for nbp-rates 1.7.20260903
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nbp_rates-1.7.20260903.tar.gz | 1.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nbp_rates-1.7.20260903-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.0 MB
Release files / nbp_rates-1.7.20260903.tar.gz
| Download URL | nbp_rates-1.7.20260903.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
829567313ee610e3326585bf734ca0e6031dee6ffef7d9c40c2929a0e366fbaf
|
|
BLAKE2b-256 checksum How to use checksums |
9574ff54eba99cbcb8993a10cc7d98db144f1eab223500d38e3aa627e5e0f8cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / nbp_rates-1.7.20260903-py3-none-any.whl
| Download URL | nbp_rates-1.7.20260903-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6a2544e68523aa8f976b535d38286a95ea87709c1f2cbb595cd2632368967e28
|
|
BLAKE2b-256 checksum How to use checksums |
98d10082411606aac9fe3ae404725a23ac4879dc915d27e02e1a926f848c4984
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency log
