Transport for Belgium Getting Started: API Integration Guide (2026)

Getting started overview

Integrating with Transport for Belgium APIs involves a structured process designed to provide developers with access to a comprehensive dataset of Belgian public transport information. This includes real-time updates, journey planning capabilities, and static data for various operators such as iRail, De Lijn, NMBS/SNCB, and TEC. The developer experience is characterized by well-structured documentation and clear examples, facilitating straightforward integration for those familiar with RESTful API principles. The platform offers a generous free tier for non-commercial and academic use, with commercial pricing available upon direct contact with Transport for Belgium.

This guide outlines the critical steps to get started, from account registration and API key acquisition to making your first successful API call. Understanding the foundational concepts of RESTful APIs, including HTTP methods (GET, POST), request headers, and JSON response formats, will aid in a smoother integration process. For a complete understanding of REST principles, refer to the developer.mozilla.org REST glossary.

Quick Reference Steps

The following table provides a high-level overview of the getting started process:

Create an account and get keys

To begin using the Transport for Belgium APIs, you must first create a developer account. This registration process is straightforward and typically requires an email address, a strong password, and agreement to the terms of service. Upon successful registration, you will gain access to the developer dashboard, which serves as your central hub for managing API keys, monitoring usage, and accessing specific API documentation.

1. Navigate to the Signup Page: Go to the official Transport for Belgium signup page.
2. Complete Registration Form: Fill in the required details, including your email address and preferred password. Ensure your password meets any specified complexity requirements. You may also need to confirm your email address via a verification link sent to your inbox.
3. Access Developer Dashboard: Once registered and logged in, you will be directed to your developer dashboard.
4. Generate API Keys: Within the dashboard, locate the section dedicated to API Keys or Credentials. This section typically allows you to generate new API keys or view existing ones. Transport for Belgium provides unique API keys that authenticate your requests. It is crucial to treat these keys as sensitive information, similar to passwords, to prevent unauthorized access to your account and API usage. The API Keys section of the developer dashboard is where you will manage these credentials.
5. Store Your Key Securely: Copy your generated API key and store it in a secure location. Avoid hardcoding API keys directly into your application's source code, especially for production environments. Instead, use environment variables or a secure configuration management system. For information on best practices for API key security, consult resources like Google Cloud's API key security best practices documentation.

Each API key is typically associated with a specific project or application, allowing for granular control and monitoring of usage. If you plan to develop multiple applications, consider generating separate API keys for each to better track and manage their individual consumption.

Your first request

After obtaining your API key, you are ready to make your first API call. This section will guide you through constructing and executing a basic request using the iRail API, which provides real-time train information in Belgium. This example typically involves fetching information about live departures from a specific station.

Prerequisites:

• Your API Key (obtained in the previous step).
• A command-line tool like cURL or an HTTP client like Postman.

Example: Getting live departures from Brussels-Central

We'll use the iRail API to fetch real-time departure information. The iRail API is part of the broader Transport for Belgium offering and provides detailed train data. You can find the specific endpoint details in the iRail API Reference.

A common endpoint for live departures might look like https://api.irail.be/liveboard/?id={station_id}&format=json&key={YOUR_API_KEY}. You will need to replace {station_id} with the appropriate ID for Brussels-Central station and {YOUR_API_KEY} with your actual API key.

First, identify the station ID for Brussels-Central. The iRail stations list can provide this. For example, the ID for Brussels-Central might be BE.NMBS.008811001.

Using cURL:

Open your terminal or command prompt and execute the following cURL command. Replace YOUR_API_KEY with your actual key and confirm the station ID.

curl -X GET "https://api.irail.be/liveboard/?id=BE.NMBS.008811001&format=json&key=YOUR_API_KEY"

Expected Response (Structure):

A successful request will return a JSON object containing information about departures from the specified station. The exact structure may vary slightly based on the current API version, but it typically includes:

{
  "version": "1.0",
  "timestamp": "1678886400",
  "station": "Brussels-Central",
  "stationinfo": { ... },
  "departures": {
    "departure": [
      {
        "id": "1",
        "station": "Brussels-Central",
        "stationinfo": { ... },
        "time": "1678886520",
        "delay": "0",
        "platform": "3",
        "platforminfo": { ... },
        "vehicle": "IC 2307",
        "vehicleinfo": { ... },
        "direction": "Liège-Guillemins",
        "directioninfo": { ... },
        "cancelled": "0",
        "left": "0",
        "occupancy": "unknown"
      },
      // ... more departures
    ]
  }
}

Examine the JSON response to verify that you are receiving valid data. Look for key fields like station, time, direction, and vehicle to confirm the API is functioning as expected. If you encounter errors, refer to the troubleshooting section below.

This initial request confirms your API key is valid and demonstrates the basic interaction pattern with Transport for Belgium's APIs.

Common next steps

Once you have successfully made your first API request, you can explore the full capabilities of the Transport for Belgium platform. Here are some common next steps:

1. Explore Other APIs: Transport for Belgium offers several APIs beyond iRail, including De Lijn, NMBS/SNCB, and TEC APIs. Each focuses on different transport operators or data types. Consult the main API documentation to understand the scope and specific endpoints for each.
2. Implement Advanced Queries: Experiment with more complex queries, such as journey planning (e.g., finding optimal routes between two locations), filtering results, or requesting historical data if available for your chosen API. The Journey Planner API Reference provides details on route optimization.
3. Integrate into Your Application: Begin integrating the API calls into your actual application. This might involve choosing an appropriate HTTP client library for your programming language (e.g., requests for Python, fetch for JavaScript).
4. Handle Rate Limits: Be aware of and implement strategies to manage API rate limits. These limits prevent abuse and ensure fair access for all users. The documentation will specify the rate limits for your chosen tier (e.g., free vs. commercial). Implement exponential backoff or token bucket algorithms to gracefully handle rate limit errors.
5. Error Handling: Implement robust error handling in your application. Anticipate various HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error) and provide informative feedback to your users or logs.
6. Webhooks (If Available): Some APIs offer webhooks for real-time notifications of events, rather than requiring constant polling. Check the documentation to see if webhooks are supported for the data you need, as this can improve efficiency and responsiveness.
7. Monitor Usage: Regularly check your API usage statistics in the developer dashboard to ensure you stay within your free tier limits or to monitor commercial usage.
8. Stay Updated: Subscribe to the Transport for Belgium developer newsletter or check their changelog for API updates, new features, or deprecations.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here's a guide to help you diagnose and resolve common problems:

• 401 Unauthorized / Invalid API Key:
  • Issue: This is often the most frequent error, indicating that your API key is either missing, incorrect, or expired.
  • Resolution: Double-check that you have included your API key in the request exactly as specified in the documentation (e.g., as a query parameter or in a header). Verify that the key copied from your developer dashboard is correct and has not been truncated or altered. Ensure your account is active and the key has not been revoked.
• 400 Bad Request / Invalid Parameters:
  • Issue: Your request contains invalid or malformed parameters.
  • Resolution: Review the specific API documentation for the endpoint you are calling. Pay close attention to required parameters, data types, and valid values (e.g., correct station IDs, date formats). Ensure your JSON or query string syntax is correct.
• 403 Forbidden / Access Denied:
  • Issue: Your API key might not have the necessary permissions for the requested resource, or you might be trying to access a commercial-only feature on a free tier.
  • Resolution: Check your API key's associated permissions in your developer dashboard. If you suspect it's a tier issue, review the pricing summary and consider contacting Transport for Belgium for commercial access if needed.
• 404 Not Found:
  • Issue: The API endpoint you are trying to reach does not exist or the resource you are requesting (e.g., a specific station or journey) cannot be found.
  • Resolution: Verify the URL of your API endpoint against the official API documentation. Ensure there are no typos in the path or resource identifiers.
• Network Issues / Connection Refused:
  • Issue: Your client cannot establish a connection with the API server.
  • Resolution: Check your internet connection. Ensure there are no firewalls or proxy settings blocking your outbound request. Try accessing other websites to confirm general connectivity. The API server might also be temporarily down, in which case checking the Transport for Belgium status page (if available) or support channels might provide information.
• Empty or Unexpected Response:
  • Issue: The API returns no data, or the data structure is not what you expected.
  • Resolution: Confirm your query parameters are not overly restrictive, leading to no results. Review the API documentation for the specific endpoint's response format to ensure your parsing logic aligns with the expected output. Sometimes, specific filters can result in an empty dataset.

If you've exhausted these common troubleshooting steps and are still facing issues, refer to the Transport for Belgium support documentation or their official developer forum (if available) for further assistance.