Getting started overview

Integrating with Transport for Czech Republic's (PID) data involves a straightforward process to obtain an API key and begin consuming public transport information. The system offers access to both static and real-time data feeds, primarily through the official PID integration and digitalization page. Developers can utilize standard General Transit Feed Specification (GTFS) feeds for static schedule data and GTFS-Realtime (GTFS-RT) for dynamic updates, such as vehicle positions and service alerts. Additionally, a dedicated HTTP API provides queryable endpoints for departures, stops, and connections.

The initial steps focus on understanding the available data, requesting necessary credentials, and executing a basic API call to confirm connectivity and data retrieval. This guide will walk through the essential actions required to move from initial interest to a successful first data request.

Step What to do Where to go
1. Review Documentation Understand data types and access methods PID Data & API page
2. Request API Key Complete the API key request form PID Data & API page (contact form)
3. Make First Request Construct and execute a test API call Your preferred HTTP client (e.g., cURL, Postman)
4. Parse Response Interpret the JSON or GTFS data received Your application code

Create an account and get keys

Access to Transport for Czech Republic's data feeds requires an API key, which is obtained by contacting the PID administration directly. There is no automated self-service portal for instant key generation; instead, developers must submit a request outlining their intended use case.

  1. Navigate to the PID Data & API Page: Begin by visiting the official PID integration and digitalization page. This page serves as the central hub for all developer-related information regarding data access.
  2. Locate the Contact Information/Request Form: On the PID Data & API page, look for a section related to API access or data integration. There will typically be a contact form or an email address provided for requesting an API key.
  3. Submit Your Request: When submitting your request, provide the following details:
    • Your Name/Organization: Clearly identify who is making the request.
    • Intended Use Case: Describe how you plan to use the data (e.g., developing a mobile app for real-time departures, creating a research project on public transport efficiency, integrating into a wayfinding system). Be specific, as this helps the PID team understand your needs and grant appropriate access.
    • Estimated Data Volume (if known): While not always strictly required for initial access, providing an estimate of how frequently you expect to call the API or download feeds can be helpful for high-volume commercial applications.
    • Technical Contact Information: Include an email address for communication regarding your API key and any technical support.
  4. Await Key Provisioning: After submitting your request, the PID team will review it. Upon approval, you will receive an API key, typically via email. This process may take a few business days. The API key is a unique string that you will include with your API requests to authenticate your application.

It is important to review any terms of service or usage policies provided alongside your API key to ensure compliance with data usage guidelines. The PID documentation emphasizes appropriate use for public benefit and non-commercial applications, with specific agreements for commercial or high-volume scenarios.

Your first request

Once you have obtained your API key, you can make your first request to verify access and retrieve data. The HTTP API is often the simplest starting point for a quick test, as it returns data in a human-readable JSON format. For this example, we'll demonstrate a simple request to retrieve information about a specific stop or departures.

Prerequisites:

  • Your API Key (e.g., YOUR_API_KEY)
  • An HTTP client (e.g., cURL, Postman, or a programming language's HTTP library)

Example Request (Conceptual): Retrieving Departures for a Stop

The exact endpoint structure and parameters can be found in the PID API documentation. A common pattern for real-time departure information might look like this:

curl -X GET "https://api.pid.example.com/v1/departures?stopId=U324Z101&limit=5&apiKey=YOUR_API_KEY"

Explanation of Components:

  • https://api.pid.example.com/v1/departures: This is a hypothetical base URL and endpoint for fetching departures. You must replace this with the actual base URL and endpoint provided in your PID API documentation.
  • stopId=U324Z101: A query parameter specifying the ID of the public transport stop. You will need to find valid stop IDs from the PID GTFS static data or other provided resources.
  • limit=5: A query parameter to limit the number of upcoming departures returned.
  • apiKey=YOUR_API_KEY: The crucial query parameter where you insert the API key you received.

Expected Successful Response (JSON):

A successful response will typically return a JSON object containing an array of departure objects. Each departure object would include details such as the line number, destination, scheduled time, and real-time estimated time.

{
  "departures": [
    {
      "line": "119",
      "destination": "Letiště Václava Havla",
      "scheduled": "2026-05-29T10:30:00Z",
      "realtime": "2026-05-29T10:32:00Z"
    },
    {
      "line": "107",
      "destination": "Suchdol",
      "scheduled": "2026-05-29T10:35:00Z",
      "realtime": "2026-05-29T10:35:00Z"
    }
  ]
}

This JSON structure is illustrative; the actual fields and their names will be defined in the official Transport for Czech Republic API reference. The presence of a JSON response with relevant data indicates successful authentication and a working connection to the API.

Common next steps

After successfully making your first API call, you can proceed with more advanced integration and data utilization:

  1. Explore GTFS and GTFS-RT Feeds: For comprehensive static schedule data (routes, stops, timetables) and real-time updates (vehicle positions, service alerts), download and parse the General Transit Feed Specification (GTFS) and GTFS-Realtime feeds. These are often provided as protocol buffer messages, which require specific libraries for parsing (Google Protocol Buffers documentation).
  2. Deep Dive into API Endpoints: Consult the full Transport for Czech Republic API documentation to understand all available endpoints, parameters, and response structures. This will allow you to query for specific information such as stop details, line information, or complex connection searches.
  3. Error Handling and Rate Limits: Implement robust error handling in your application to gracefully manage network issues, invalid requests, or API errors. Pay attention to any stated rate limits in the documentation to avoid being temporarily blocked.
  4. Data Storage and Caching: For applications requiring frequent access to static data or to reduce API calls, consider implementing local caching mechanisms for GTFS data. Real-time data should be fetched as needed, but judiciously, to stay within usage policies.
  5. Build a User Interface: Begin developing the front-end or user-facing components of your application, integrating the data retrieved from the Transport for Czech Republic APIs to display schedules, maps, or real-time updates.
  6. Monitor for Updates: Regularly check the official PID website or developer portal for announcements regarding API changes, new features, or data updates to ensure your integration remains compatible and leverages the latest information.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting steps:

  • Invalid API Key: Double-check that you have copied your API key correctly and that it is included in the request as specified in the documentation (e.g., as a query parameter apiKey=YOUR_KEY). An incorrect key will typically result in a 401 Unauthorized or 403 Forbidden HTTP status code.
  • Incorrect Endpoint or Parameters: Verify that the base URL and specific endpoint path are accurate. Ensure all required query parameters (like stopId or limit) are present and correctly formatted according to the PID API documentation. A 404 Not Found or 400 Bad Request often indicates an issue here.
  • Network Connectivity: Confirm that your machine has an active internet connection and can reach the API's host. Test with a simple request to a known working URL (e.g., curl https://www.google.com).
  • Rate Limiting: While less likely on a very first call, if you've made multiple rapid attempts, you might hit a temporary rate limit, resulting in a 429 Too Many Requests status. Wait a few minutes and try again.
  • SSL/TLS Issues: Ensure your HTTP client is configured to handle HTTPS connections correctly. Most modern clients do this by default, but older environments or specific configurations might require attention.
  • Firewall Restrictions: Check if any local firewalls or network proxies are blocking outbound connections to the API's domain.
  • Review Error Messages: The API often returns descriptive error messages in the response body (even with an error status code). Read these messages carefully as they usually pinpoint the exact problem.
  • Consult Documentation and Support: If problems persist, refer back to the Transport for Czech Republic API documentation for specific error codes or contact their support channel as outlined on their developer page.