Table of contents

Search on the page

Open Journey Planner (OJP)

#AutoTranslate

Brief Description

What is OJP?

The abbreviation has three meanings:

  1. The interface standard CEN/TS 17118 «Open API for Distributed Journey Planning», referred to in the Delegated Regulation (EU 2017/1926) for the Member States of the European Union.
  2. The routing backend system «Open Journey Planner» to calculate routes by public transport (PT), walking routes and other mobility offers.
  3. The OJP interface, i.e. the interface to the OJP system that corresponds 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 secure here.

Unless otherwise stated, the abbreviation ‘OJP’ is usually used on this Open Data platform to refer to the ‘Open Journey Planner’ system.

On this page, we distinguish 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 advanced by the Comité Européen de Normalisation (CEN). The Customer Information Plus System Tasks 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 Transmodel.

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

The OJP interface is based on the Travellors Realtime Information Advisory Standard (TRIAS), which complies with Directive 431 of the Verband Deutscher Verkehrsunternehmen (VDV) will follow.

A demo for trying out the OJP system using the OJP standard can be found here: OJP demo

More information about assessing OJP as a standard can be found in Report the FOT.

Why does the Open data platform that?

The OJP standard allows an open and standardised interface for ‘distributed routing’. This standard, developed at European level, allows different systems to work together to offer cross-border travel planning or travel planning that integrates different transport modalities, or to enable new innovative information services.

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

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

Note: A description of how to access the APIs can be found here: Howto: Accessing our APIs with API Keys.

Access the API

Note: We recommend the GitHub page or our API interface to see some practical examples.

Functional Description

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

The OJP standard defines various interface endpoints (hereinafter referred to only 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 services that can be retrieved and linked to (LinkedServices, we will describe in the technical section below). Sorted by importance:

  1. Your situation: Would you like to work out a route with your family using different means of transport?
    • Then you need the TripRequest
    • What the service does: With this service, the system serving it (in our case, the OJP system) routes.
    • What the service requires: When a start point and destination are entered (coordinates, addresses, POI or stops), the OJP system computes connections between the start point and destination. Different modes can also be requested with ModesToCover. The following modes are currently available: public transport; walking; cycling; driving a car yourself; sharing services (bicycles, e-scooters, car sharing).
    • What the return service does: Routing includes both public transport routing (taking into account current journey times and disruptions) and map-based individual traffic routing (e.g. by using 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 (verbal navigation) is usually also available for walking routes.
    • More Details to this service at the following link: OJPTripRequest v1.0 or OJPTripRequest v2.0
  2. Your situation: Would you like to show your guests the stops and points of interest in your area?
    • Then you need the LocationInformationRequest
    • What the service does: This service determines the nearest locations.
    • What the service needs: When a coordinate or address is entered, the OJP system uses a radius search to determine the appropriate locations.
    • What the service provides: The stops and points of interest close to the specified location.
    • More details about this service can be found at the following link: OJPLocationInformationRequest v1.0 or OJPLocationInformationRequest v2.0
  3. Your situation: You want a departure monitor for the stop in front of your store?
    • Then you need the StopEventRequest
    • What the service does: The service determines the departure and arrival times at a stop.
    • What the service requires: A specific stop must be specified.
    • What the service provides: The next departures / arrivals at a specific stop.
    • More details about this service can be found at the following link: OJPStopEventRequest v1.0 or OJPStopEventRequest v2.0
  4. Your situation: Do you need all the stops along the previously calculated journey?
    • Then you need the TripInfoRequest
    • What the service does: This service determines further details of an already calculated ‘Journey’ to request (see TripRequest).
    • What the service needs: The previously determined journey must be enclosed.
    • What the service provides: Details of an already calculated ‘Journey’.
    • More details about this service can be found at the following link: OJPTripInfoRequest v1.0 or OJPTripInfoRequest v2.0
  5. Your situation:Would you like to know how much the journey you have requested will cost?
    • Then you need the FareRequest
    • What the service does: Use Switzerland’s public transport cost calculation infrastructure to determine the expected costs of a verified journey.
    • What the service requires: The previously recorded ‘journey’ must be enclosed.
    • What the service offers: The price calculation of trips, including discount journeys and taking into account Half Fare Travelcards (‘Half Fare Travelcards’). It is only possible to query prices in Switzerland. N.B.: The price information is non-binding. The actual price is only set when the order is placed. The number of enquiries is also limited.
    • More details about 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: Returns a list of stops that can be used as transition points between two regions. The query is part of the OJP standard’s distributed route calculation. Regions are those served by other distributed systems.
    • What the service needs: A specific location for the transition stops to adjacent systems is to be searched, as well as corresponding parameters, e.g. the type of location (POI, stops, etc.).
    • What the service provides: Either the transition stops for the requested location or all the transition stops that can be used to calculate the route.
    • Please contact us to use this service.
  7. Your situation: You want to calculate the route from Bern to your aunt in Zurich and make a stop in Olten beforehand?
    • Then you need the MultiPointTripRequest
    • What the service does: With this service, the system serving it (in our case, the OJP system) routes in the same way as the TripRequest.
    • What the service needs: In addition to a starting point and a destination point (coordinates, an address, POI or stop) (as for the TripRequest) you need intermediate points that have to be explicitly included or excluded.
    • What the service offers: The same as in TripRequest and Routing includes both public transport routing (taking into account current journey times and disruptions) and map-based individual traffic routing (e.g. by using 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 (verbal navigation) is usually also available for walking routes.
    • Please contact us to use this service.
  8. Your situation: You had a route calculated a few days ago. Now it’s your day of travel and you want to check up-to-date information?
    • Then you need the (from version 2.0) TripRefineRequest
    • What the service does: Update a trip that has already been calculated. It is important that the request is not a recalculation!
    • What the service needs: An existing trip with context and parameters. The parameters can act as a filter, e.g. that only partial results that do not contain any steps are returned.
    • What the service does: The service updates the trip with the requested additions, if available. Important:
      • The service may deliver several trips and not (only) the requested one.
      • The previous trip may be ‘broken’ for this request. The trip must then be recalculated.
      • The response provided by TripRefineRequest must therefore always be checked!
    • More details about this service can be found at the following link: OJPTripRefineRequest
  9. Your situation: Do you need to extend your planned stopover in Olten?
    • Then you need the (from version 2.0) TripChangeRequest
    • What the service does: Allows the dwell time at a stopover along a trip to be extended and either the section before or after is preserved. 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 that has been modified as you wish.
    • No further details about this service yet.
  10. SysRequest:
    1. In addition to the 7 or 9 basic services, it is possible to query the status of the OJP (Version/DateFormat/etc.).
    2. More details about this service can be found at the following link: OJP Sysrequest

What are the most important terms and concepts you should know?

The following terms and concepts must be internalised in order to be able to use the OJP interface.

  • StopPoint
    • Description: A StopPoint is a stop along a timetable. It can 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. The size of the StopPlace can vary. Very large stops such as Bern or Zurich stations consist of multiple StopPlaces.
  • Journey, the ‘journey’
    • Description: A journey is the transport of customers on a specific route, a specific timetable connection, with a specific mode of transport journey, at a specific time, in a specific direction. There are different journey types, e.g.: DatedJourney for a journey with one mode of transport on a specific day.
  • Trip, the ‘journey’
    • Description: A ‘journey’ and thus a non-specific form of the journey. A trip consists of legs (see below).
  • Leg, the ‘journey section’
    • Description: A section of a trip. The following leg types exist:
      • ContinuousLeg: A leg that is not bound to a timetable.
      • TimedLeg: A leg according to a timetable.
      • TransferLeg: A leg at a location at which the person changes between trains or trains.
  • Direction
    • Description: All lines and journeys have a direction. This primarily helps transport companies with their planning and, if necessary, to indicate an ‘end/destination station’. This is therefore an ‘artificial attribute’ and the meaning of the direction cannot be inferred.
  • Facility
    • Description: A facility is an element that is available at a ‘location’ (e.g. stop) or on a service (e.g. vehicle). An example is the toilet at the station or in the dining car. They are currently taken from offers in HRDF (see Traffic notices). Mapping is carried out as per Notes2FacilitiesMappingFile.
  • Mode
    • Description: Modes are the possible means of transport. The permissible modes are:
      • ContinuousMode: A mode that is not timetable-dependent.
      • IndividualModes: Individual transport.
      • PtMode: PtMode is a public transport mode.
      • TransferModes: Mode related to changing trains
      • XXXRef: These elements are references. They will ultimately be generic IDs that apply throughout Switzerland. However, they are still being developed. They will evolve here.

Technical Description

Access to the API

A token is required in order to be able to use the API/interface. This token can be accessed via the API Manager can be acquired.

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

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

You can use the OJP 2.0 interface try it here https://opentdatach.github.io/api-explorer/ojp2.0/

Basic functionality API

Simple requests

The OJP interface is more like a classic SOAP XML interface than a REST interface. All access is via the endpoint mentioned.

Two headers must be set:

Content-Type: application/xml
Authorization: Bearer <Key>

The services described above are differentiated by sending the corresponding requests in the (line text) element ServiceRequest. Here in the example we run a LocationInformationRequest off.

Please note that the RequestorRef is a unique statement. The purpose of this is to identify who is making the request. The statement should contain the suffix ‘_test‘, ‘_int” or ‘_prod‘ so that we know from which environment was accessed during subsequent analysis and support requests.

<?xml version="1.0" encoding="UTF-8"?>
<OJP xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.siri.org.uk/siri" version="1.0" xmlns:ojp="http://www.vdv.de/ojp" xsi:schemaLocation="http://www.siri.org.uk/siri ../ojp-xsd-v1.0/OJP.xsd">
	<OJPRequest>
		<ServiceRequest>
			<RequestTimestamp>2020-01-09T08:00:00Z</RequestTimestamp>
			<RequestorRef>SomeAptlyNamedTransportCompany_int</RequestorRef>
			<ojp:OJPLocationInformationRequest>
				<!-- eigentlicher Request -->
			</ojp:OJPLocationInformationRequest>
		</ServiceRequest>
	</OJPRequest>
</OJP>

Multiple requests in one message

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

Please note: The responses will not be sorted in the order in which the requests are sent, but in the order in the standard XSD. For these types of request, it is therefore extremely important that the MessageIdentifier are set for each request and that they can then be read from the response. The standard order is (version 1.0):

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

If there are problems using the interfaces, please use this page: OJP Best Practices

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