nbp_rates
A modular Python library for providing NBP (Narodowy Bank Polski) exchange rates with both offline and online support.
Features
- Offline Support: Includes historical exchange rates from 2012 to 10-July-2026
- Online Fallback: Automatically fetches from NBP API for dates after 10-July-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 100+ currencies supported
- Precise and exact output: Results provided as string to avoid floating-point rounding issues
- Flexible Date Input: Accepts
datetime.date,datetime.datetime, or ISO format strings (YYYY-MM-DD) - No external dependencies: Pure Python with standard library
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 100+ 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
Data Sources
- Offline Data: Embedded exchange rate data from 2012 to 2026-07-07
- 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
Version 1.1.20260711
- Initial release with offline and online exchange rate support
1 maintainer
Release files for nbp-rates 1.1.20260711
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.1.20260711.tar.gz | 1.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nbp_rates-1.1.20260711-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.0 MB
Release files / nbp_rates-1.1.20260711.tar.gz
| Download URL | nbp_rates-1.1.20260711.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
592d2a6dd6e26bcf2ea7a0182dde2ce60cf774835f3bd06730efc213fd498c8b
|
|
BLAKE2b-256 checksum How to use checksums |
3be567e97786f1dd24be57387c1a5b184a244808c9269b66d9b6d311394411e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jul 11, 2026.
Transparency logRelease files / nbp_rates-1.1.20260711-py3-none-any.whl
| Download URL | nbp_rates-1.1.20260711-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
24e5176d3776c5b20ae98793e1ed56c14f81594737ef051212a1fa550b5894e2
|
|
BLAKE2b-256 checksum How to use checksums |
0abcd0a69a1f802a0f3e4a96d0f92c723841fcef375dec9730abe143e0ae5a8c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jul 11, 2026.
Transparency log
