Introduction

What is Journey Planner?

Journey Planner v3 is Entur's core service for journey planning. It uses OpenTripPlanner software to provide departure boards for individual stops, and point-to-point journey planning for all public transport in Norway, including real-time information, regardless of transport mode or operator. All data is presented as a Transmodel-based GraphQL API.

Base URL: https://api.entur.io/journey-planner/v3/graphql

GraphQL IDE: https://api.entur.io/graphql-explorer/journey-planner-v3

Are you new to GraphQL? You can read more about it here: https://graphql.org/

Authentication

Journey Planner is an Open Service licensed under NLOD and requires the ET-Client-Name header for all requests.

Use a value that uniquely identifies your company and application, in the form <company>-<application> (lowercase, no spaces).

For detailed authentication instructions and requirements, see Authentication.

API

There is only one endpoint:

POST https://api.entur.io/journey-planner/v3/graphql

Headers

• Content-Type: application/json
• ET-Client-Name: <company>-<application>

Body

A JSON body with a query field and optionally variables.

Code
{
    "query": "string",
    "variables": {
        "myVariable": "value"
    }
}

How does Journey Planner actually work?

Journey Planner serves as a backend service for most journey planning apps within the public transport sector in Norway today. This section provides an overview of how the service works and what makes it return travel options for your search.

Using data from multiple sources

To enable multi-modal travel options several datasets are fed into the search engine.

Static dataset:

• OpenStreetMap dataset for all of Norway (geofabrik.de)
• Elevation data for all of Norway (kartverket.no)
• All Norwegian Stop Places for public transport (entur.no)
• All Timetable data for all Norwegian public transport services (entur.no)

Dynamic dataset:

• All real-time feeds for Norwegian public transport service (entur.no)
• All available feeds of shared mobility (entur.no)

All datasets and feeds are fed into the search engine which continuously holds an instant representation of the entire public transport network.

The algorithm for finding the optimal path

Any query for a journey between A and B will run the full search algorithm on the current representation. The search algorithm uses the RAPTOR algorithm to find relevant journeys. Broken down, this means the algorithm checks for each minute from the requested search time and looks for Pareto-optimal results. The current implementation checks for pareto-optimality on the following factors:

• Arrival time - earliest possible arrival is optimal
• Departure time - latest possible departure is optimal
• Transfers - fewer is optimal
• Cost - accumulated value for all elements of a journey; walk paths, transfers, waiting time, time on public transit vehicle, and boarding/alighting a vehicle. Lowest value is optimal

Given the above factors, a journey is returned as an option only if the journey is optimal with respect to one of these factors. Additionally, some journeys are filtered out of the returned sets of journeys to avoid obviously undesirable alternatives.

Neutrality

The nature of journey planning is complex and what is considered the "best" option is subjective to the preferences of the end user. The system is designed to try to find a sweet spot for representing travel options as neutral as possible while still providing relevant options to the user. Basing this on calculation of finding pareto optimal paths, given the factors described above, is not perfect, however provides the best collection of travel options in most cases within a reasonable response time. Additionally, the API is rich with parameters to tune your query to achieve desired results, however this is not the default behavior of the service.

Further reading

This document provides a high level description of how the service works. If you want the full details of exactly how the algorithm works, the search engine is open source and you can find the full source code at github.com/opentripplanner. There are multiple deployments of this search engine around the world and additional information can be found on the project webpage - opentripplanner.org.