Getting started overview

The Czech National Bank (CNB) provides public web services for accessing official foreign exchange rates. Unlike many commercial APIs, the CNB's service does not require account creation, API keys, or any form of authentication. This direct access model simplifies the integration process for developers and technical buyers looking to incorporate official Czech Koruna exchange rates into their applications, financial models, or research projects. The service offers both daily exchange rates and historical data, primarily in XML and JSON formats.

To begin, developers will identify the appropriate endpoint for their data requirements, such as the current daily exchange rate or a specific historical date. The API is designed for straightforward HTTP GET requests, returning the requested data directly. This guide outlines the steps to make your initial request and understand the structure of the returned data. The entire service is free to use, making it an accessible resource for a wide range of applications requiring accurate exchange rate information for the Czech Koruna.

Step What to do Where
1. Review Documentation Familiarize yourself with available endpoints and data formats. CNB Web Services documentation
2. Select Endpoint Choose the specific URL for daily or historical rates. CNB API Reference
3. Construct Request Formulate an HTTP GET request to the chosen endpoint. Your preferred HTTP client or programming language
4. Parse Response Process the XML or JSON data returned by the API. Your application's data parsing logic
5. Integrate Data Incorporate the exchange rate information into your application. Your application's business logic

Create an account and get keys

The Czech National Bank's exchange rate web services operate on a public access model, meaning there is no requirement for creating an account or obtaining API keys. This distinguishes it from many commercial API providers, which typically enforce authentication mechanisms to control access, manage usage limits, and track consumption. The absence of an authentication layer simplifies the initial setup process significantly, allowing developers to directly interact with the API endpoints without any preliminary registration steps.

Developers can proceed directly to making requests after reviewing the available endpoints and understanding the expected data formats. This approach is common among governmental and public institutions that aim to provide open access to certain datasets for transparency and public utility. For instance, the European Central Bank also provides direct access to its foreign exchange rates without requiring authentication, a model often adopted for official economic data dissemination (ECB reference exchange rates).

While the lack of authentication streamlines access, it also implies that developers do not have personalized usage dashboards, rate limit tracking, or direct support channels typically associated with API key-based services. Users are expected to adhere to fair usage principles, although specific rate limits are not explicitly published. For detailed information on the web services, consult the CNB's official web services documentation.

Your first request

To make your first request to the Czech National Bank's exchange rate web service, you will construct a simple HTTP GET request to one of the public endpoints. The most common use case is to retrieve the daily exchange rates, which are updated regularly. The CNB provides an endpoint for the current day's rates and another for historical rates.

Daily Exchange Rates (XML)

The daily exchange rates are typically available in XML format. You can access them via a URL that specifies the current date. For example, to get the rates for a specific date (e.g., 29.05.2026), you would use a URL similar to this:

GET https://www.cnb.cz/en/financial-markets/foreign-exchange-market/exchange-rate-fixing/daily.txt HTTP/1.1
Host: www.cnb.cz

Note: The daily.txt endpoint typically returns a text file that can be parsed as a simple table or CSV-like structure, containing the date, country, currency, amount, and code, followed by the rate. While named .txt, its structure is often tabular. For more structured XML, you might need to query specific historical endpoints or parse the text output.

Daily Exchange Rates (JSON)

For a JSON output, the CNB provides a more modern endpoint, often found in a structure similar to:

GET https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.json HTTP/1.1
Host: www.cnb.cz

This endpoint provides the daily exchange rates in a structured JSON format, which is often preferred for programmatic parsing. The exact URL structure may vary slightly, so always refer to the official CNB web services documentation for the most up-to-date endpoints.

Example using curl

You can test these endpoints using a command-line tool like curl:

curl https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.json

This command will output the JSON response directly to your terminal. The response will contain an array of currency objects, each with details such as the currency code, country, amount (units), and the exchange rate against the Czech Koruna (CZK).

Example JSON Response Structure (Illustrative)

[
  {
    "validFor": "29.05.2026",
    "order": 1,
    "country": "EMU",
    "currency": "euro",
    "amount": 1,
    "currencyCode": "EUR",
    "rate": 24.750
  },
  {
    "validFor": "29.05.2026",
    "order": 2,
    "country": "USA",
    "currency": "dollar",
    "amount": 1,
    "currencyCode": "USD",
    "rate": 22.800
  }
]

Upon receiving a successful response (HTTP status code 200 OK), you can then parse the JSON or XML data within your application to extract the necessary exchange rates. For example, in Python, you might use the requests library and json module:

import requests
import json

url = "https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.json"
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    for item in data:
        if item["currencyCode"] == "EUR":
            print(f"EUR to CZK: {item["rate"]}")
        if item["currencyCode"] == "USD":
            print(f"USD to CZK: {item["rate"]}")
else:
    print(f"Error fetching data: {response.status_code}")

Common next steps

Once you have successfully made your first request and parsed the exchange rate data, several common next steps can enhance your integration with the Czech National Bank's web services:

  1. Implement Error Handling: While the CNB API is generally reliable, implement robust error handling for network issues, HTTP status codes other than 200 OK, and unexpected data formats. This ensures your application remains stable even if the API responds with an error or an unparsable body.
  2. Explore Historical Data: Beyond daily rates, the CNB provides access to historical exchange rates. Investigate the endpoints for specific dates or date ranges to build features like trend analysis or historical conversions. The CNB web services documentation specifies the formats for historical queries.
  3. Automate Data Retrieval: For applications requiring up-to-date rates, schedule automated tasks (e.g., cron jobs, cloud functions) to fetch the latest daily rates. Consider caching mechanisms to reduce redundant requests and improve application performance.
  4. Integrate into Financial Models: Incorporate the retrieved exchange rates into financial calculations, currency conversion tools, or reporting systems. Ensure that the precision and format of the rates meet the requirements of your specific financial models.
  5. Monitor for Changes: Periodically check the official CNB documentation for any updates to API endpoints, data formats, or usage policies. While the API is stable, changes can occur over time.
  6. Consider Rate Limits (Implicit): Although no explicit rate limits are published, it is good practice to implement a reasonable delay between requests, especially for automated processes, to avoid overwhelming the server. This aligns with general best practices for consuming public APIs, as detailed in resources like Google Maps Platform API usage limits or similar API guidelines.
  7. Explore International Standards: For broader financial applications, consider how the CNB's data aligns with international standards for currency codes (ISO 4217) and exchange rate reporting. This can help in integrating with other financial data sources.

Troubleshooting the first call

When making your first call to the Czech National Bank's exchange rate web services, you might encounter issues. Here are common problems and their solutions:

  • 404 Not Found Error:

    • Cause: The URL used is incorrect or outdated.
    • Solution: Double-check the endpoint URL against the official CNB web services documentation. Endpoints for daily or historical data can sometimes change. Ensure proper capitalization and path structure.

  • Empty or Unexpected Response Body:

    • Cause: The request was successful, but the data for the specified date might not be available yet, or the format is different than expected.
    • Solution: Verify the date in your request, especially for daily rates that are typically updated once per banking day. If requesting historical data, ensure the date falls within the available range. Also, confirm whether the endpoint returns XML or JSON and parse accordingly.

  • Network Connection Issues:

    • Cause: Local network problems, firewall restrictions, or issues with the CNB server.
    • Solution: Test connectivity to www.cnb.cz from your environment (e.g., using ping or by accessing the URL in a web browser). If you can access the URL in a browser but not programmatically, check your application's network configuration or proxy settings.

  • Incorrect Date Format for Historical Data:

    • Cause: When requesting historical data, the date parameter in the URL might not match the format expected by the API.
    • Solution: The CNB typically uses a DD.MM.YYYY format for dates. For example, /cnb.cz/cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.json?date=29.05.2026. Always refer to the documentation for the precise date parameter format for historical queries.

  • Parsing Errors (XML/JSON):

    • Cause: Your application's parser is expecting XML but receives JSON, or vice versa, or the structure of the response has subtly changed.
    • Solution: Inspect the Content-Type header of the API response to confirm the data format (e.g., application/json, application/xml). Ensure your parsing logic correctly handles the received format. Tools like curl can help you view raw response headers and body.

  • Rate Limiting (Implicit):

    • Cause: Although not explicitly documented, excessive requests in a short period might lead to temporary blocking or slow responses.
    • Solution: Implement a delay between requests, especially for bulk data retrieval, and consider caching results for a reasonable period (e.g., daily rates for 24 hours). If you suspect rate limiting, wait for a few minutes and retry.