Skip to content
LoginRegister
DEENFRIT
Home
Open data platform mobility Switzerland
  2. Cookbook
  3. Open Journey Planner (OJP)

Open Journey Planner (OJP)

January 2024 version. You can find information on continuous adjustments in our changelog.

Background

What is OJP?

The abbreviation has three meanings:

  1. The interface standard CEN/TS 17118 «Open API for Distributed Journey Planning», which was declared binding for the member states of the European Union in the Delegated Regulation (EU 2017/1926).
  2. The “Open Journey Planner” routing backend system for calculating routes using public transport, footpaths and other mobility options.
  3. The OJP interface, i.e. the interface of the OJP system corresponding to the OJP standard. At its core, it is an XML standard with a request/response behaviour. As for all CEN standards, a profile will be developed for Switzerland (what is supported, and what is not). The profile is linked here.

On this open data platform, the abbreviation “OJP” is usually used for the “Open Journey Planner” system, unless otherwise stated.

On this page we differentiate between the OJP standard (CEN standard), the OJP system (routing system) and the OJP interface.

Who is behind it?

As described above, the OJP standard is being promoted by the Comité Européen de Normalisation (CEN). The System Tasks Customer Information Plus (SKI+) office is actively involved in the further development of the OJP standard on behalf of the Federal Office of Transport (FOT). The OJP standard is based on CEN’s Network Timetable Exchange (NeTEx) standard. The data models of both standards in turn implement the reference data model for public transport in Europe, known as the Transmodel.

The OJP system is developed by an external service provider of SKI+. The system is based on a proprietary product from the external service provider. The OJP system can be controlled using the OJP standard.

The OJP interface is based on the Travellers Realtime Information Advisory Standard (TRIAS), which follows Directive 431 of the Association of German Transport Companies (Verband Deutscher Verkehrsunternehmen, VDV).

A demo to try out the OJP system using the OJP standard can be found here: OJP Demo

You can find more information on the assessment of OJP as a standard in the FOT report (German only).

Why does the Open Data platform offer this?

The OJP standard allows an open and standardised interface for “distributed route planning”. Different systems can thus work together according to this standard developed at European level in order to offer cross-border or integrated travel planning or to enable new innovative information services.

The OJP system serves to fulfil the FOT’s mandate for a non-discriminatory and intermodal router that can be controlled via an interface that complies with the OJP standard. The OJP system is intended for its services to be used for the development of end customer applications. Direct contact with customers and their data remain with these end customer applications!

It is important to understand that despite their similar names, the router and the standard are two essentially independent things.

How do I access the data/interfaces?

Data

As described, OJP is a standard/system/interface, so there is no file download

However, we recommend the GitHub page link or our API interface to see a couple of practical examples.

Interfaces

Details on the OJP API: https://opentransportdata.swiss/en/dataset/ojp2020 (productive since 2020)

Details on the OJP API (2.0): https://opentransportdata.swiss/de/dataset/ojp2-0 (productive, still under construction)

Details on the OJP-Fare API: https://opentransportdata.swiss/en/dataset/ojpfare

Business description

Attention: The following description refers to OJP2020 (i.e. OJP-API v1.0). For working with OJP-API 2.0 see https://opentransportdata.swiss/de/cookbook/ojp2entwicklung/.

What services (interface endpoints) does the OJP standard offer?

The OJP standard defines various interface endpoints (hereinafter referred to as “services”). In version 1.0 there are 7 “core services” and in version 2.0 there are 9 “core services”. These services are served by the OJP system.

The OJP system supports all 7 of version 1.0 of the services that can be called up and linked (LinkedServices, described in the technical section below). Sorted by importance:

  1. Your situation: Would you like to calculate a route with your family using different means of transport?
    • Then you need the TripRequest
    • What the service does: With this service, the operating system (in our case the OJP system) carries out routing.
    • What the service needs: When you enter a starting point and a destination (coordinate, address, POI or stop), the OJP system calculates connections from the starting point to the destination. Different modes can be additionally requested with ModesToCover. The following modes are currently available: public transport; footpath; bicycle; self-driven car; sharing services (bicycle, e-scooter, car sharing).
    • What the back service provides: The routing includes both public transport routing (taking into account current journey times and disruptions) and map-based individual transport routing (e.g. with your own car) based on OpenStreetMap (OSM). If desired, you can use the Link-Projection output parameter to request the actual geographical routes, and a TurnDescription is usually also available for footpaths (verbally described navigation).
    • More details on this service can be found at the following link: OJPTripRequest
  2. Your situation: Would you like to show your guests the stops and points of interest in your neighbourhood?
    • Then you need the LocationInformationRequest
    • What the service does: This service determines the nearest locations.
    • What the service needs: When you enter a coordinate or an address, the OJP system uses a radius search to determine the matching locations.
    • What the service provides: The stops and points of interest near the specified location.
    • More details on this service can be found at the following link: OJPLocationInformationRequest
  3. Your situation: You want a departure monitor for the bus stop in front of your shop?
    • Then you need the StopEventRequest
    • What the service does: The service determines the departure and arrival times of a stop.
    • What the service needs: A specific stop must be entered.
    • What the service provides: The next departures / arrivals at a specific stop.
    • More details on this service can be found at the following link: OJPStopEventRequest
  4. Your situation: You need all stops along the previously calculated journey?
    • Then you need the TripInfoRequest
    • What the service does: This service determines further details about a journey that has already been calculated (see TripRequest).
    • What the service needs: The previously determined journey must be provided.
    • What the service provides: Details of a journey that has already been calculated.
    • More details on this service can be found at the following link: OJPTripInfoRequest
  5. Your situation: Would you like to know how much the journey you have requested is likely to cost?
    • Then you need the FareRequest
    • What the service does: Determines the estimated cost of a transferred journey using Switzerland’s public transport cost calculation infrastructure.
    • What the service needs: The previously determined “journey” must be provided.
    • What the service provides: The price calculation of trips, including discount journeys and consideration of Half Fare Travelcard (“HTA”). Price enquiries are only possible in Switzerland. IMPORTANT: The price information is not binding. The actual price is not defined until the order is placed. The number of requests is also limited.
    • More details on this service can be found at the following link: Beta: OJP Fares
  6. Your situation: Would you like to plan a trip to Austria and find suitable transfer points?
    • Then you need the ExchangePointRequest
    • What the service does: Provides a list of stops that can be used as transition points between two regions. The query is part of the distributed route calculation of the OJP standard. Regions are those that are served by other, distributed systems.
    • What the service needs: A specific location for which transition stops to neighbouring systems are to be searched for, as well as corresponding parameters, e.g. about the type of location (POI, stop, etc.).
    • What the service provides: Either the transition stops for the requested location, or all transition stops that can be used for the route calculation.
    • No further details on this service yet.
  7. Your situation: Would you like to calculate a route from Bern to your aunt in Zurich and make a stopover in Olten beforehand?
    • Then you need the MultiPointTripRequest
    • What the service does: With this service, the operating system (in our case the OJP system) carries out a routing, just like the TripRequest.
    • What the service needs: In addition to the start point and a destination point (coordinate, address, POI or stop) (as with the TripRequest), you need intermediate points that must be explicitly included or excluded.
    • What the service provides: The same as in TripRequest and The routing includes both a public transport routing (taking into account current journey times and disruptions) and a map-based individual transport routing (e.g. with your own car) based on OpenStreetMap (OSM). If desired, you can use the Link-Projection output parameter to request the actual geographical routes, and a TurnDescription is usually also available for footpaths (verbally described navigation).
    • No further details on this service yet.
  8. Your situation: You had a route calculated a few days ago. Now the day of your trip has arrived and you want to call up the latest information?
    • Then you need the (from version 2.0) TripRefinementRequest
    • What the service does: Update a trip that has already been calculated. It is important to note that the enquiry is not a recalculation!
    • What the service needs: An existing trip with context and parameters. The parameters can act as a filter, e.g. only the partial results that do not contain steps are delivered.
    • What the service provides: The service updates the trip with the desired additions, if available. Important:
      • It may be that the service delivers several trips and not (only) the one requested.
      • It can happen that the previous trip “breaks” with this enquiry. The trip must then be recalculated.
      • The response of the TripRefinementRequest must therefore always be checked!
    • No further details on this service yet.
  9. Your situation: You need to extend your planned stopover in Olten?
    • Then you need the (from version 2.0) TripChangeRequest
    • What the service does: Allows you to extend the dwell time at a stopover along a trip and either get the section before or after. The other parts could therefore be recalculated.
    • What the service needs: An existing leg and the desired adjustments to it.
    • What the service provides: A trip customised according to your wishes.
    • No further details on this service yet.
  10. SysRequest:
    1. In addition to the 7 or 9 basic services, it is also possible to query the status of the OJP (version/date format/etc.).
    2. More details on this service can be found at the following link: OJP Sysrequest

What are the most important terms and concepts to know?

To be able to use the OJP interface, you need to internalise the following terms and concepts.

  • StopPoint
    • Description: A StopPoint is a stop along a timetable. It may be a stop, a platform, a sector, a boarding area or even a dynamic element. The StopPoint is assigned to the StopPlace via a StopAssignment.
  • StopPlace
    • Description: The StopPlace is the physical representation of a stop. A StopPlace can vary in size. Very large stops such as Bern or Zurich railway stations consist of several StopPlaces.
  • Journey, the “ride”
    • Description: A journey is the transport of customers on a specific route, a specific timetable connection, with a specific means of transport, at a specific time, in a specific direction. There are different journey types, e.g.: DatedJourney for a journey of a means of transport on a specific day.
  • Trip, the “travel”
    • Description: A “journey” and thus an unspecific form of a more concrete journey. A trip consists of legs (see below).
  • Leg, the “travelling section”
    • Description: A section of a trip. The following leg types exist:
      • ContinuousLeg: A leg that is not tied to a timetable.
      • TimedLeg: Leg according to a timetable.
      • TransferLeg: A leg for a location where a transfer takes place.
  • Direction
    • Description: All lines and journeys have one direction. This primarily helps the transport companies in their planning and, if necessary, to display an “end/destination station”. This is therefore an “artificial attribute” and the meaning of the direction cannot be derived.
  • Facility
    • Description: A facility is an element that is available at a “location” (e.g. bus stop) or on a “service” (e.g. vehicle). One example is the toilet at the railway station or the dining car. They are currently taken from the offers in HRDF (see transport information). The mapping is carried out according to Notes2FacilitiesMappingFile.
  • Mode
    • Description: Modes are possible means of transport. Permitted modes are:
      • ContinuousMode: Mode that does not depend on a schedule.
      • IndividualModes: Individual transport.
      • PtMode: PtMode is a mode in public transport.
      • TransferModes: Mode in connection with transfer.
      • XXXRef: These elements are references. They are essentially generic IDs that apply throughout Switzerland. However, they are still being established so they will still evolve.

Technical description

Access to the API

A token is required to be able to use the API/interface. This token can be obtained via the Developer Portal.

All services for version 1.0 are available via POST with the URL https://api.opentransportdata.swiss/ojp2020.

All services for version 2.0 are available via POST with the URL https://api.opentransportdata.swiss/ojp20.

You can try out the interface here https://opentransportdata.swiss/en/cookbook/open-journey-planner-ojp-api-explorer/ or https://opentdatach.github.io/api-explorer2/

Basic functionality API

Simple requests

The OJP interface is more like a classic SOAP XML interface than a REST interface. All accesses are made via the specified endpoint.

Two headers must be set:

The current working key is:

The services described above are differentiated via the corresponding requests in the ServiceRequest element. In this example, we are executing a LocationInformationRequest.

Please note that you must make a unique entry as RequestorRef. The aim here is to identify who is making the enquiry. The specification should include the suffix “_test”, “_int” or “_prod” so that we know which environment was accessed in the event of subsequent analyses and support queries.

Multiple requests in one message

It is possible to include any number of OJPXXXRequests in a ServiceRequest. They do not have to be of the same type.

Attention: The answers are not sorted along the order of the requests made, but according to the sequence in the standard XSD. It is therefore extremely important for such requests that the message identifiers are set for each request and can then be read from the response. The standard sequence is (version 1.0):

  • ExchangePointsRequest
  • FareRequest
  • LocationInformationRequest
  • MultiPointRequest
  • StopEventRequest
  • TripInfoRequest
  • TripRequest

Restrictions and further information

Restrictions

  • Some modes are not yet available.
  • Real-time information is only available where we have received this information and can retrieve it via CUS.

Further information