Transport for Finland Getting Started: API Integration (2026)

Getting started overview

Integrating with Transport for Finland's Digitransit platform enables access to public transport data across Finland, including the Helsinki Region Transport (HSL). This guide focuses on the practical steps to begin using the API, from initial access to a successful first request. The primary interface for real-time and journey planning data is a GraphQL API, complemented by static General Transit Feed Specification (GTFS) data access. The platform is designed to support various applications, from simple journey planners to complex mobility-as-a-service (MaaS) platforms. Non-commercial use typically does not require an API key, providing a low barrier to entry for development and testing, while commercial applications generally require registration and an API key for access control and usage monitoring.

Before making requests, developers should familiarize themselves with the available API endpoints and data models described in the HSL GraphQL API reference. The platform encourages the use of GraphQL for dynamic queries, which allows clients to request exactly the data they need, reducing over-fetching and under-fetching issues common with REST APIs. For those new to GraphQL, resources such as GraphQL's official 'Learn' section can provide foundational knowledge.

Quick Reference Table

Create an account and get keys

For non-commercial use, Transport for Finland's Digitransit platform generally allows access to its GraphQL API without requiring an API key. This open access facilitates rapid prototyping and development for personal projects or academic research. You can typically begin sending requests to the public GraphQL endpoint immediately, as outlined in the Digitransit developer documentation.

However, for commercial applications or projects requiring higher rate limits and dedicated support, registration is necessary. The process for obtaining an API key for commercial use typically involves contacting Digitransit directly. While specific signup pages for API keys are not publicly listed for direct self-service, the general approach is to initiate contact through the primary Digitransit website, explaining your commercial use case. They will then guide you through the registration process, which may include agreeing to specific terms of service and usage policies. Commercial API keys help manage usage limits and ensure compliance with their service agreements.

Once you have obtained an API key, it will need to be included with your requests, typically in an HTTP header. The exact header name (e.g., Authorization, X-API-Key) and value format will be provided upon successful registration, so it is important to refer to the specific instructions provided by Digitransit for your commercial API key.

Your first request

To make your first request to the Transport for Finland GraphQL API, you will send an HTTP POST request to the designated GraphQL endpoint. For HSL data, the endpoint is typically https://api.digitransit.fi/routing/v1/routers/hsl/index/graphql. This example demonstrates a basic query to retrieve information about a specific stop.

Example GraphQL Query (JavaScript)

const endpoint = 'https://api.digitransit.fi/routing/v1/routers/hsl/index/graphql';
const query = `
  {
    stop(id: "HSL:1020210") {
      name
      lat
      lon
      stoptimesWithoutPatterns {
        realtimeArrival
        headsign
      }
    }
  }
`;

fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/graphql',
    'Accept': 'application/json',
    // 'digitransit-subscription-key': 'YOUR_COMMERCIAL_API_KEY' // Uncomment for commercial use
  },
  body: query
})
.then(response => response.json())
.then(data => {
  console.log('Stop Information:', data.data.stop);
})
.catch(error => {
  console.error('Error fetching data:', error);
});

In this example:

• endpoint: The URL for the HSL GraphQL API.
• query: A GraphQL string requesting the name, latitude, longitude, and upcoming stop times for a stop with the ID HSL:1020210 (Kamppi metro station in Helsinki).
• headers: Sets the Content-Type to application/graphql or application/json if sending a JSON object with a query field, and Accept to application/json. For commercial use, you would include your API key in a custom header, often named digitransit-subscription-key, as specified during your commercial registration.
• fetch: A standard JavaScript API for making network requests.

The response will be a JSON object containing the requested data under the data field. Errors, if any, will be present in an errors field at the root level of the JSON response.

Common next steps

After successfully making your first request, several common next steps can deepen your integration with Transport for Finland's APIs:

1. Explore More GraphQL Queries: The HSL GraphQL API reference details numerous other queryable fields and objects, such as routes, trips, and real-time vehicle positions. Experimenting with different queries will help you understand the full range of data available.
2. Integrate with a JavaScript SDK: While direct HTTP requests are feasible, using the provided JavaScript SDKs can simplify interaction with the API, abstracting away some of the HTTP request complexities and potentially offering utility functions for data processing.
3. Access GTFS Data: For applications requiring static timetable data, route geometries, and stop locations, explore downloading and processing the General Transit Feed Specification (GTFS) data feeds. These are often available as zipped files containing several CSV or text files that describe the transit system.
4. Implement Error Handling: Develop robust error handling for your application. The GraphQL API returns errors in a structured JSON format, allowing you to parse and respond to issues like invalid queries, rate limits, or server-side problems programmatically.
5. Optimize Performance: For applications with high traffic, consider strategies like caching API responses for frequently requested data to reduce the number of direct API calls and improve user experience.
6. Monitor Usage (Commercial Users): If you are using a commercial API key, regularly monitor your API usage against your allocated limits to prevent service interruptions. Details on monitoring are typically provided with your commercial account.

Troubleshooting the first call

When making your initial API call to Transport for Finland, you might encounter issues. Here are common problems and their solutions:

• Incorrect Endpoint: Ensure you are using the correct GraphQL endpoint. The HSL endpoint for real-time and routing queries is https://api.digitransit.fi/routing/v1/routers/hsl/index/graphql. Verify this against the official API documentation.
• Invalid GraphQL Query: GraphQL queries must adhere to strict syntax. Common errors include missing braces, misspellings of field names, or requesting fields that do not exist for a given object. Tools like GraphQL Playground (if available for the endpoint) can help validate queries before sending them. Ensure your query matches the schema provided in the HSL GraphQL API reference.
• Content-Type Header: For GraphQL POST requests, the Content-Type header is typically application/graphql if the body is the raw query string, or application/json if the body is a JSON object with a query field. Using the wrong header can result in a 400 Bad Request error.
• Missing or Incorrect API Key (Commercial Use): If you are a commercial user, verify that your digitransit-subscription-key header is correctly set with the API key provided during your registration. An invalid or missing key will likely result in a 401 Unauthorized or 403 Forbidden error.
• Network Issues: Check your internet connection and ensure no firewalls or proxies are blocking your outgoing request to the Digitransit API endpoint.
• Rate Limiting: While non-commercial use has generous limits, frequent or large requests might trigger rate limiting, resulting in 429 Too Many Requests errors. If you encounter this, slow down your request rate or consider applying for a commercial key if your usage consistently exceeds limits.
• Server-side Errors: Occasionally, the API server itself might experience issues, returning 5xx status codes. These are typically temporary. You can check the Digitransit developer portal for any service status updates.