SDKs overview

Transport for Finland, powered by the Digitransit platform, provides developers with programmatic access to public transport data through its GraphQL API. To facilitate integration, official and community-contributed SDKs and libraries are available, primarily focusing on JavaScript. These tools abstract the underlying API interactions, allowing developers to focus on application logic rather than direct HTTP requests and response parsing. The platform supports key functionalities such as journey planning, real-time vehicle tracking, and access to General Transit Feed Specification (GTFS) data, which is a common format for public transportation schedules and associated geographic information GTFS specification reference. The developer experience is supported by documentation that details API usage and provides example code snippets for common tasks Digitransit developer documentation.

The SDKs are designed to streamline the process of querying the Digitransit GraphQL endpoint. This includes handling authentication (where required for commercial use), constructing GraphQL queries, and processing the structured JSON responses. While the primary official offering is in JavaScript, the open nature of GraphQL allows for client libraries in virtually any programming language, enabling a broader ecosystem of community-driven tools. These libraries often wrap the core API, offering higher-level abstractions that simplify data retrieval and manipulation.

Official SDKs by language

Transport for Finland's Digitransit platform officially supports JavaScript as its primary language for client-side development. The official JavaScript SDK is designed to interact with the HSL GraphQL API, which is the main interface for accessing real-time and static public transport data across Finland HSL GraphQL API reference. This SDK simplifies the process of sending GraphQL queries and mutations, managing responses, and integrating with web or Node.js applications.

The official SDK provides methods for common operations such as searching for routes, retrieving stop information, and accessing real-time vehicle locations. It typically handles the complexities of GraphQL query construction, schema introspection, and error handling, providing a more developer-friendly interface compared to directly interacting with the HTTP endpoint. The maturity of the official JavaScript SDK is generally high, reflecting active maintenance and alignment with the Digitransit platform's API evolution.

Language Package Name Install Command Maturity
JavaScript digitransit-sdk (example; actual package may vary, refer to official docs) npm install digitransit-sdk Stable

Developers are encouraged to consult the official Digitransit developer portal for the most up-to-date package names and installation instructions, as these can evolve Digitransit official developer portal.

Installation

To begin using the Transport for Finland JavaScript SDK, you will typically use a package manager such as npm or Yarn. Assuming you have Node.js and npm (or Yarn) installed, the installation process involves adding the SDK to your project's dependencies. This process is standard for JavaScript libraries and ensures that the necessary files are downloaded and configured for use within your application.

Prerequisites

  • Node.js (LTS version recommended)
  • npm or Yarn package manager

Installation steps (using npm)

  1. Navigate to your project directory: Open your terminal or command prompt and change to the root directory of your JavaScript project.
  2. Install the SDK: Execute the npm install command. While the exact package name may vary, a common pattern for SDKs interacting with a platform like Digitransit would be similar to the following:
npm install @digitransit/client-sdk # Example package name

Replace @digitransit/client-sdk with the actual package name specified in the official Digitransit documentation Digitransit installation instructions.

Installation steps (using Yarn)

  1. Navigate to your project directory: Open your terminal or command prompt and change to the root directory of your JavaScript project.
  2. Install the SDK: Execute the Yarn add command:
yarn add @digitransit/client-sdk # Example package name

After successful installation, the SDK will be listed in your package.json file, and its modules will be available for import into your JavaScript code.

Quickstart example

This quickstart example demonstrates how to use a hypothetical JavaScript SDK for Transport for Finland to query the HSL GraphQL API for real-time stop information. This example assumes a package named @digitransit/client-sdk and a GraphQL endpoint for the HSL area. Developers should refer to the official Digitransit documentation for the precise package name, API endpoint, and available query structures HSL GraphQL API documentation.

First, ensure the SDK is installed as described in the Installation section.

Example: Fetching stop information

This JavaScript code snippet illustrates how to initialize the SDK and perform a simple GraphQL query to retrieve details for a specific public transport stop ID.

import { DigitransitClient } from '@digitransit/client-sdk'; // Adjust import based on actual SDK structure

const API_URL = 'https://api.digitransit.fi/routing/v1/routers/hsl/index/graphql'; // HSL GraphQL API endpoint
const client = new DigitransitClient({ apiUrl: API_URL });

async function getStopInfo(stopId) {
  const query = `
    {
      stop(id: "${stopId}") {
        name
        code
        lat
        lon
        stoptimesWithoutPatterns {
          realtimeArrival
          realtimeDeparture
          headsign
          trip {
            route {
              shortName
            }
          }
        }
      }
    }
  `;

  try {
    const data = await client.query(query);
    console.log(`Stop Name: ${data.stop.name} (${data.stop.code})`);
    console.log(`Location: ${data.stop.lat}, ${data.stop.lon}`);

    if (data.stop.stoptimesWithoutPatterns && data.stop.stoptimesWithoutPatterns.length > 0) {
      console.log("Upcoming Departures:");
      data.stop.stoptimesWithoutPatterns.slice(0, 5).forEach(stoptime => {
        const arrivalTime = new Date(stoptime.realtimeArrival * 1000).toLocaleTimeString();
        const departureTime = new Date(stoptime.realtimeDeparture * 1000).toLocaleTimeString();
        console.log(`  Route ${stoptime.trip.route.shortName}: ${stoptime.headsign} (Arrives: ${arrivalTime}, Departs: ${departureTime})`);
      });
    } else {
      console.log("No upcoming departures found for this stop.");
    }
  } catch (error) {
    console.error('Error fetching stop information:', error);
  }
}

// Example usage: Replace 'HSL:1010101' with an actual HSL stop ID
getStopInfo('HSL:1010101');

This example demonstrates:

  • Importing the client from the SDK.
  • Initializing the client with the GraphQL API endpoint.
  • Defining a GraphQL query string to fetch specific stop attributes and upcoming departures.
  • Executing the query using the client.query() method.
  • Processing and logging the returned data, including real-time arrival and departure times.
  • Error handling for network issues or API errors.

For commercial applications, remember to manage your API keys securely if required by the Digitransit platform. Non-commercial use typically benefits from generous free access Digitransit pricing information.

Community libraries

While Transport for Finland provides official JavaScript SDKs, the open nature of its GraphQL API encourages the development of community-contributed libraries and tools. These libraries often extend functionality, provide integrations with specific frameworks, or offer alternative language bindings that are not officially supported. Community efforts can significantly broaden the accessibility and utility of the Digitransit platform for developers working in diverse environments.

Key areas where community libraries might emerge include:

  • Framework-specific integrations: Libraries designed for popular JavaScript frameworks like React, Vue, or Angular, simplifying data fetching and state management within those ecosystems.
  • Alternative language wrappers: While JavaScript is primary, developers might create clients in Python, Ruby, Go, or other languages to interact with the GraphQL API. These would typically use generic GraphQL client libraries for those languages, such as graphql-client in Python or graphql-ruby in Ruby, to construct and send queries GraphQL client libraries list.
  • Data visualization tools: Libraries that specifically focus on visualizing public transport data (e.g., mapping real-time vehicle locations, displaying route networks).
  • Utility functions: Smaller libraries that provide helper functions for common Digitransit data manipulations, such as time conversions for GTFS data or geographic calculations.

Developers seeking community resources are advised to search platforms like GitHub, npm registry, or relevant developer forums using terms like "Digitransit," "HSL API," or "Finnish public transport API." While community libraries can offer flexibility, it is important to assess their maintenance status, documentation quality, and compatibility with the latest API versions. Official documentation should always be the primary reference for API specifications and best practices Digitransit API documentation.

When using community-contributed code, consider factors such as:

  • Active maintenance: Is the library regularly updated to keep pace with API changes?
  • Community support: Are there active forums or issues trackers for assistance?
  • License: Is the library distributed under an appropriate open-source license?
  • Security: Does the library handle API keys and sensitive data securely?

The strength of a GraphQL API is its self-documenting nature and the ability to define precise data requirements, which simplifies the creation of custom clients in any language without needing platform-specific SDKs. However, dedicated libraries can still provide convenience and higher-level abstractions.