Transport for Spain Getting Started Guide (2026)

Getting started overview

Integrating with Transport for Spain involves a sequence of steps designed to get developers operational quickly. This guide focuses on the initial setup: account creation, API key acquisition, and executing a basic API call. The core products, such as the Real-time GTFS API, Historical Transit Data API, and Route Planning API, all utilize a consistent authentication mechanism. Developers can start with the free Developer Plan, which allows for up to 1,000 requests daily, providing sufficient capacity for initial testing and development before committing to a paid plan.

Before making any API calls, it is essential to understand the authentication requirements. Transport for Spain primarily uses API keys for access, which are generated through the developer dashboard. The platform also offers SDKs for common programming languages like JavaScript, Python, and Ruby, which can simplify the process of making authenticated requests and parsing responses. These SDKs handle details such as request formatting and error handling, reducing the boilerplate code needed for integration.

Create an account and get keys

To begin, navigate to the Transport for Spain homepage and locate the sign-up option. The registration process typically requires an email address and password. After successful registration, you will gain access to the developer dashboard, which serves as your central hub for managing API access.

Within the dashboard, there will be a section dedicated to API Keys or Credentials. This is where you generate and manage your unique API key. It is critical to treat your API key as sensitive information, similar to a password, as it grants access to your account's API usage and associated data. Do not embed it directly in client-side code or public repositories. For server-side applications, store it securely using environment variables or a secrets management service.

The developer dashboard also provides an overview of your current plan, API usage statistics, and options to upgrade your subscription if needed. The Transport for Spain pricing page outlines the various tiers, starting with the free Developer Plan and scaling up to enterprise options. Keep track of your usage to avoid unexpected service interruptions once you exceed the free tier's limits.

Your first request

With an API key in hand, you can now make your first request. This section outlines how to make a basic request using the Real-time GTFS API, which provides live public transport data. For this example, we will use a hypothetical endpoint that retrieves real-time bus locations in Madrid.

API Endpoint Example:

GET https://api.transportfor.com/v1/gtfs/realtime/madrid/vehicles
Headers: {
  "Authorization": "Bearer YOUR_API_KEY"
}

Replace YOUR_API_KEY with the actual key obtained from your dashboard. The API typically uses a Bearer token in the Authorization header for authentication, a common practice for RESTful APIs as described by the OAuth 2.0 Bearer Token Usage specification.

Using cURL

cURL is a command-line tool and library for transferring data with URLs, making it suitable for quick API tests:

curl -X GET \
  'https://api.transportfor.com/v1/gtfs/realtime/madrid/vehicles' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Using Python (with requests library)

import requests

api_key = "YOUR_API_KEY"
url = "https://api.transportfor.com/v1/gtfs/realtime/madrid/vehicles"
headers = {
    "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print("Successfully retrieved vehicle data:")
    print(data)
else:
    print(f"Error: {response.status_code} - {response.text}")

This Python example demonstrates constructing the request, including the necessary authorization header, and handling the JSON response. The requests library simplifies HTTP interactions in Python applications.

Expected Response Structure

A successful response (HTTP status code 200) will typically return a JSON object containing an array of vehicle entities. Each entity might include information such as vehicle ID, current latitude/longitude, route ID, and timestamp. The exact structure is detailed in the Transport for Spain API reference.

{
  "timestamp": 1678886400,
  "entity": [
    {
      "id": "vehicle-123",
      "vehicle": {
        "trip": {
          "trip_id": "trip-abc",
          "route_id": "route-X",
          "start_time": "08:00:00",
          "start_date": "20260101"
        },
        "position": {
          "latitude": 40.4168,
          "longitude": -3.7038,
          "bearing": 90
        },
        "current_status": "IN_TRANSIT_TO",
        "timestamp": 1678886390
      }
    },
    // ... more vehicles
  ]
}

Common next steps

After successfully making your first API call, consider these next steps to further integrate Transport for Spain's data into your application:

1. Explore Additional Endpoints: The API reference documentation details various endpoints for historical data, route planning, and specific transit modes. Experiment with these to understand the full range of available data.
2. Implement SDKs: For faster development and better error handling, consider using one of the official Transport for Spain SDKs available for JavaScript, Python, and Ruby. SDKs abstract away the complexities of HTTP requests and JSON parsing.
3. Handle Rate Limits: Be aware of the rate limits associated with your chosen plan. Implement retry logic with exponential backoff for transient errors, and monitor your API usage in the dashboard to avoid hitting limits.
4. Secure API Keys: For production applications, implement robust security practices for your API keys. Avoid hardcoding keys directly in your source code. Instead, use environment variables, secret management services, or a proxy server to protect them.
5. Process Data: Start processing the received JSON data to extract relevant information for your application. This might involve filtering vehicles by route, calculating distances, or displaying real-time positions on a map using a mapping library like the Google Maps JavaScript API.
6. Error Handling: Implement comprehensive error handling for various HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error). The Transport for Spain documentation provides details on specific error responses.
7. Upgrade Plan: If your application scales beyond the free tier, review the pricing plans and upgrade your subscription to ensure uninterrupted service and higher request limits.

Troubleshooting the first call

Encountering issues during the first API call is common. Here's a guide to common problems and their solutions:

• 401 Unauthorized: This status code indicates that your API key is either missing, invalid, or incorrectly formatted. Double-check the following:

  • Ensure YOUR_API_KEY is correctly replaced with the key from your dashboard.
  • Verify the Authorization header format: It should be Bearer YOUR_API_KEY, with a space between "Bearer" and your key.
  • Confirm your API key has not been revoked or expired in the Transport for Spain developer dashboard.

• 403 Forbidden: This usually means your account lacks the necessary permissions for the requested endpoint, or your plan does not cover the feature. If you are on the free Developer Plan, certain advanced endpoints might be restricted. Review your plan details on the Transport for Spain pricing page.

• 404 Not Found: The requested URL or resource does not exist. Verify the endpoint URL against the API reference documentation. Pay close attention to spelling, casing, and any versioning in the URL (e.g., /v1/).

• 429 Too Many Requests: You have exceeded the rate limits for your current plan. This can happen quickly during testing if you make many requests in a short period. Wait for a few minutes and try again. For production, implement rate limiting strategies and consider upgrading your plan if this becomes a recurring issue. The official documentation on rate limits provides specific thresholds.

• 5xx Server Error: These indicate a problem on the Transport for Spain server side. While rare, if you encounter a 5xx error, it's best to wait and retry. If the issue persists, check the Transport for Spain status page (if available) or contact their support team.

• Incorrect JSON Parsing: If your code executes without HTTP errors but you cannot parse the response, ensure the response is indeed JSON. Some error responses might return HTML or plain text. Always check the Content-Type header of the response. If the response is empty or malformed, consult the API reference for expected output formats.

Quick Reference Table