Getting started overview

The National Bank of Poland (NBP) offers an API that provides public access to its official economic data, including daily currency exchange rates for various currencies against the Polish Złoty (PLN), gold prices, and interest rates. This API is designed for developers and researchers who require up-to-date and historical financial information directly from Poland's central bank. Unlike many commercial APIs, the NBP API does not require an API key or account registration for access to its public datasets, simplifying the initial setup process. Data is typically available in JSON and XML formats, accessible via standard HTTP GET requests.

The NBP API is particularly useful for:

  • Financial Applications: Integrating official exchange rates for conversions or reporting.
  • Academic Research: Accessing historical data for economic studies.
  • Business Intelligence: Monitoring currency fluctuations relevant to operations in Poland.

This guide outlines the steps to make your initial request to the NBP API, covering the basic structure of API calls and how to interpret the responses. For a comprehensive overview of available endpoints and data structures, refer to the National Bank of Poland API reference.

Create an account and get keys

The National Bank of Poland API operates on a public access model for its core datasets, meaning that no account creation or API key is required to retrieve official exchange rates, gold prices, or interest rates. This differs from many commercial APIs, such as Adyen's API explorer or Stripe's API documentation, which typically mandate a developer account and API key for authentication. The NBP's approach simplifies the onboarding process, allowing developers to begin making requests immediately after understanding the API's structure.

To access the data, you will directly construct HTTP GET requests to the NBP's API endpoints. There is no dashboard for managing API keys, no rate limit tiers to select, and no application registration process involved for standard data access. This open access facilitates quick integration for public data consumption. Developers should consult the National Bank of Poland's official economic data page for any updates to access policies or new data offerings.

Your first request

To make your first request to the National Bank of Poland API, you will use a standard HTTP GET method to one of the available endpoints. The API provides different tables for exchange rates (Table A, Table B, Table C), as well as dedicated endpoints for gold prices and interest rates. For this example, we will retrieve the current average exchange rate for a specific currency from Table A, which lists average exchange rates of foreign currencies against the Polish Złoty.

API Endpoint Structure

The base URL for the NBP API is https://api.nbp.pl/api/. Specific data is accessed by appending resource paths.

Example: Get Current Average Exchange Rate for USD (Table A)

To get the current average exchange rate for the US Dollar (USD), you would use an endpoint similar to https://api.nbp.pl/api/exchangerates/rates/{table}/{code}/?format={format}. Here, {table} would be 'A', {code} would be 'USD', and {format} can be 'json' or 'xml'.

Request URL

GET https://api.nbp.pl/api/exchangerates/rates/A/USD/?format=json

Using Python

This Python example uses the requests library to make the API call and print the JSON response.

import requests

url = "https://api.nbp.pl/api/exchangerates/rates/A/USD/?format=json"
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print("Current USD exchange rate (Table A):")
    print(data)
else:
    print(f"Error: {response.status_code} - {response.text}")

Using JavaScript (Node.js with node-fetch)

This JavaScript example demonstrates fetching the data in a Node.js environment.

import fetch from 'node-fetch';

const url = "https://api.nbp.pl/api/exchangerates/rates/A/USD/?format=json";

async function getUsdExchangeRate() {
  try {
    const response = await fetch(url);
    if (response.ok) {
      const data = await response.json();
      console.log("Current USD exchange rate (Table A):");
      console.log(data);
    } else {
      console.error(`Error: ${response.status} - ${response.statusText}`);
    }
  } catch (error) {
    console.error("Fetch error:", error);
  }
}

getUsdExchangeRate();

Interpreting the Response

A successful response (HTTP status 200 OK) will return a JSON object containing details about the exchange rate. For the USD example, the response structure will similar to:

{
  "table": "A",
  "currency": "dolar amerykański",
  "code": "USD",
  "rates": [
    {
      "no": "099/A/NBP/2026",
      "effectiveDate": "2026-05-29",
      "mid": 3.9876
    }
  ]
}

The "mid" field represents the average exchange rate for the specified currency against the Polish Złoty as of the "effectiveDate". For more details on response structures and available data points, consult the NBP API documentation.

Quick Reference: First Call Steps

Use this table as a quick guide to making your initial API call.

Step What to Do Where to Find Info
1. Understand Endpoints Identify the specific NBP API endpoint for the data you need (e.g., current exchange rates, historical rates, gold prices). NBP API documentation
2. Construct URL Build the full API request URL, including table type, currency code, and desired format (JSON/XML). NBP API documentation
3. Choose Method Select a programming language or tool (e.g., Python requests, JavaScript fetch, cURL) to send an HTTP GET request. Language-specific documentation (e.g., MDN Fetch API guide)
4. Send Request Execute the HTTP GET request to the constructed URL. Your chosen language's HTTP client library
5. Parse Response Receive and parse the JSON or XML response to extract the desired data. NBP API documentation for response structure

Common next steps

After successfully making your first request to the National Bank of Poland API and understanding its public access model, you can explore several common next steps to integrate this data more deeply into your applications or research:

  1. Explore Other Endpoints: The NBP API offers more than just current average exchange rates. You can fetch:

    • Historical exchange rates: Retrieve rates for specific dates or date ranges for historical analysis.
    • Table B/C rates: Access different types of exchange rates, such as buying and selling rates for specific currencies (Table C is for currency exchange offices).
    • Gold prices: Obtain daily gold prices in PLN.
    • Interest rates: Although less frequently updated, interest rate data is also available.

    Detailed information on these endpoints can be found in the official National Bank of Poland API documentation.

  2. Handle Data Formats: While JSON is often preferred for programmatic access, the NBP API also supports XML. Ensure your application can parse the chosen format efficiently. Libraries like Python's json module or JavaScript's JSON.parse() are standard for JSON, while XML parsing may require dedicated libraries depending on your language.

  3. Error Handling and Robustness: Implement robust error handling in your code. Check for HTTP status codes (e.g., 404 for not found, 400 for bad request) and handle potential network issues. The NBP API documentation specifies typical error responses.

  4. Data Caching and Rate Limits: Although the NBP API does not explicitly state restrictive rate limits for public data, it's good practice to implement client-side caching mechanisms, especially for historical data that doesn't change frequently. This reduces the load on the NBP's servers and improves your application's performance. For further guidance on web API best practices, consult resources such as the IETF RFC 7234 on HTTP caching.

  5. Build a User Interface: For applications targeting end-users, integrate the retrieved data into a user-friendly interface. This could involve displaying current exchange rates, plotting historical trends, or building a currency converter.

  6. Automation and Scheduling: For applications requiring regular updates, set up automated scripts or scheduled tasks to fetch the latest data at appropriate intervals (e.g., daily for new exchange rates). Be mindful of the data's update frequency; NBP exchange rates are typically published once per business day.

Troubleshooting the first call

When making your first call to the National Bank of Poland API, you might encounter common issues. Here’s a guide to diagnosing and resolving them:

1. Incorrect URL or Endpoint

  • Symptom: HTTP 404 Not Found or an unexpected empty response.
  • Diagnosis: Double-check the URL for typos. Ensure the table type (A, B, C), currency code (e.g., USD, EUR), and format (json, xml) are correctly specified in the path.
  • Solution: Refer to the NBP API documentation to verify the exact endpoint structure. For example, to get rates for a specific date, the path changes from /rates/{table}/{code}/ to /rates/{table}/{code}/{date}/.

2. Invalid Currency Code

  • Symptom: HTTP 400 Bad Request or a response indicating an invalid code.
  • Diagnosis: The currency code might be misspelled or not supported by the specific NBP exchange rate table you are querying.
  • Solution: Consult the NBP's official list of currencies and their codes. The NBP typically uses ISO 4217 currency codes, but it's essential to confirm against their specific listings. You can also try querying a list of all available currencies for a given table, if an endpoint for that is provided in the documentation.

3. Network or Connection Issues

  • Symptom: Connection timeout, DNS resolution failure, or similar network errors.
  • Diagnosis: Your development environment or network might be preventing the request from reaching the NBP server. This can be due to proxy settings, firewalls, or general internet connectivity problems.
  • Solution:
    • Verify your internet connection.
    • Test with a simple tool like curl from your terminal (e.g., curl https://api.nbp.pl/api/exchangerates/rates/A/USD/?format=json) to rule out application-specific issues.
    • Check corporate firewall or proxy settings if you are in an enterprise environment.

4. Date Format Issues for Historical Data

  • Symptom: HTTP 400 Bad Request when requesting historical data.
  • Diagnosis: Dates are not in the expected YYYY-MM-DD format, or the requested date is outside the available historical range (e.g., too far in the past or a future date).
  • Solution: Ensure dates are correctly formatted. Review the NBP API documentation for specific date constraints or earliest available historical data points.

5. Unexpected Response Format

  • Symptom: Your code fails to parse the response, even if the status code is 200.
  • Diagnosis: You might be expecting JSON but receiving XML (or vice-versa), or the JSON/XML structure differs from your expectation.
  • Solution: Explicitly specify ?format=json or ?format=xml in your request URL. Print the raw response body to inspect its structure and confirm it matches your parsing logic.

General Debugging Tips

  • Use a REST Client: Tools like Postman, Insomnia, or even your web browser's developer console can help you test API endpoints independently of your code.
  • Inspect Full Response: Always log the full HTTP status code, headers, and body of the API response during development to understand exactly what the server is sending back.