Skip to content
LoginRegister
DEENFRIT
Home
Open data platform mobility Switzerland
  2. Cookbook
  3. OJPTripRequest

OJPTripRequest

Key concepts

  • Stops: Use DiDok or stop datasets from other sources like service points.
  • Journeys: A journey involves transporting customers along a particular route, according to a particular timetable connection, by a particular means of transport, at a particular time, in a particular direction.
  • Timetable: A timetable determines the progress of a means of transport in public short- and long-distance passenger traffic and in railway freight traffic. The information required for this includes train numbers, days of operation, routes, arrival, departure and passing times at the stops, as well as permissible speeds in individual sections of the route.
  • Forecasts: Forecasts concern a train’s running times in the future, which are calculated based on the train’s current location. This also takes into account conflicts and their currently intended settlements in the next x minutes. A less elaborate method is used to calculate future values of the forecast.
  • Means of transport (VM): Either used synonymously with vehicles (train, boat, tram, bus) from different carriers or in the sense of a “transport system” (public transport etc.).
  • DateTime in Response: It is always based on Zulu time (i.e. UTC). That means, you have to add two hours in summer and one hour in winter.

OJP Trip Service

TripRequest is the main service. A trip can be planned by specifying origin and destination.

A trip has multiple legs (sections).

API Explorer

You can try your own requests – direct link to the API explorer.

Request

Element Cardinality Description Example
RequestTimestamp 1:1 The timestamp of the request. Preferably in UTC.
MessageIdentifier 0:1 The identifier of the message. Preferably issued in strictly monotonously increasing order.
ojp:Origin 1:* The starting point of the search. OJP offers quite a lot of ways to model this.

More information can be found in the relevant section.

ojp:Destination 1:* The destination point of the search. OJP offers quite a lot of ways to model this.

More information can be found in the relevant section.

ojp:Via 0:1 The system supports one “via”. If the user wishes to include multiple vias or to calculate a round trip, the requesting system must divide it up into individual trips and conduct a separate search for each of them.

ojp:Params 0:1 Other parameters. See relevant section

Origin/Destination structure

Element Cardinality Description Example
ojp:PlaceRef/siri:StopPointRef 0:1 Reference to StopPoint

ojp:PlaceRef/ojp:StopPlaceRef 0:1 Reference to a stop

ojp:PlaceRef/ojp:GeoPosition 0:1 WGS84 coordinates

ojp:PlaceRef/ojp:TopographicPlaceRef 0:1 Reference to a location. Difficult because the values cannot be guessed

 

ojp:PlaceRef/ojp:PointOfInterestRef 0:1 Reference to a Point of Interest. The Location Name is ignored.

T

ojp:PlaceRef/ojp:AddressRef 0:1 Reference to an address

ojp:PlaceRef/ojp:LocationName 1:1 Public name of the location

Please note: The name is ignored. First perform a LocationRequest which will return a reference or coordinate.

ojp:DepArrTime 0:1 Time to be used

“Z” is Zulu time (i.e. independent of time zones). With Z, it is essential that the seconds are also specified. If the format is not correct or there is no Z, the machine tries to interpret the time as local time.

ojp:TimeAllowance 0:1 Instead of DepArrTime. Additional time required to reach or leave the location.

IndividualTransportOptions 0:* Options for travel to and from the stops

See separate table

 

IndividualTransportOptions

Element Cardinality Description Example
 ojp:Mode 1:1 The mode to be used to reach the origin. Only “walk” is currently supported.

Other values:

  • walk
  • cycle
  • taxi
  • self-drive-car
  • others-drive-car
  • motorcycle
  • truck
ojp:MaxDistance 0:1 Maximum distance in metres. This is used to narrow down the routes.
ojp:MaxDuration 0:1 Maximum duration. Indicates the maximum duration of the route. Please note the format. It is xs:duration.
ojp:MinDistance 0:1 Minimum distance in metres. This is used to narrow down the routes.

This feature is not supported.

ojp:MinDuration 0:1 Minimum duration. Indicates the minimum duration of the route. Please note the format. It is xs:duration.

This feature is not supported.

ojp:Speed 0:1 Relative speed in percent. Normal is 100%.

Params

Element Cardinality Description Example
ojp:PtModeFilter  0:1 The filter indicates the modes to take into consideration.

The lists of modes and submodes come from SIRI. They are listed in the XSD.

ojp:LineFilter  0:1 Lines that are to be included or excluded.

ojp:OperatorFilter 0:1 Operators that are to be included or excluded.

ojp:PrivateModeFilter 0:1 Include private modes or not.

This feature is not available.

 n/a
ojp:NoSingleStep 0:1 The user cannot navigate a level change.

This feature is not available.

  n/a
ojp:NoStairs 0:1 The user cannot navigate stairs.

This feature is planned for a future release.

 n/a
ojp:NoEscalator 0:1 The user cannot navigate an escalator.

This feature is planned for a future release.

 n/a
ojp:NoElevator 0:1 The user cannot navigate an elevator.

This feature is planned for a future release.

 n/a
ojp:NoRamp 0:1 The user cannot navigate a ramp

This feature is not available.

 n/a
ojp:LevelEntrance 0:1 The user requires entrances/crossings at ground level

This feature is planned for a future release.

 n/a
ojp:BikeTransport 0:1 The user wants to bring along a bicycle

This feature is planned for a future release.

 n/a
ojp:WalkSpeed 0: Deviation from normal walking speed. 100% normal.

This feature is planned for a future release.

 n/a
ojp:NumberOfResults 0:1 Quantity of results

This feature is planned for a future release.

ojp:NumberOfResultsBefore 0:1 NumberOfResultsBefore=n and Destination.

DepArrTime = earliest found EndTime in the last response minus 1 minute if an OJP client wants to receive the next earlier response to the rides already received.

ojp:NumberOfResultsAfter 0:1 Number of results after a given time (at the finish or at the start)

If an OJP client wants to receive next to the already received trips later, it must send a new request with NumberOfResultsAfter=n and Origin.DepArrTime = latest found StartTime in the last response plus 1 minute.

ojp:IgnoreRealtimeData 0:1 Include real-time data?

ojp:ImmediateTripStart 0:1 Assume that the user is already on the way?

This element is not supported.

 n/a
ojp:TransferLimit 0:1 Maximum number of changes

ojp:OptimisationMethod 0:1 Use which optimisation method?

fastest, least walking, etc

This feature is planned for a future release.

 n/a
ojp:ItModesToCover 0:* Find a separate monomodal trip for each mode in the list, in addition to the intermodal ones.

New, since August 2022, this is supported for sharing-offers.

 See the chapter on sharing below.
ojp:IncludeTrackSection 0:1 Include TrackSection information that permits the geographical projection of a leg. It returns TrackStart, TrackEnd and Duration.

Of course, the information has to be available (currently not really the case).

ojp:IncludeLegProjection 0:1 Include the geographical presentation of a leg in the result? This is currently suppressed for public transport legs because the route is not known. This will still be done for the “walk” legs.

ojp:IncludeTurnDescription 0:1 A detailed description of the route of each leg is provided in the PathGuidance.

ojp:IncludeAccessibility 0:1 Include disability information?

This feature is planned.

ojp:IncludeIntermediateStops 0:1 Show stops along the individual trip, i.e. all the intermediate stops?

ojp:IncludeFare 0:1 Include price details?

This feature is currently not supported.

ojp:Extension 0:1 Is used for certain sharing modes. See the chapter on sharing below.

 

Response

An example of a complete response: tripresponse

First ojp:TripResponseContext is returned. It contains information on all the places used (stops, locations, addresses, etc.) in the ojp:Places: element

In future the context may also include the situations (faults).

This is followed by 0:* TripResult. The header is followed by

the individual trips.

If not calculating from and to a stop, the legs leading up to the stop are shown first.

Otherwise a TimedLeg follows.

Comments:

  • Real-time data is unfortunately not yet available. Otherwise, the respective details would already have been integrated.
  • The XXXRef will gradually be adapted with the new Swiss Identifiers.
  • The DestinationStopPointRefs are not ideal yet.
  • The attributes are formed from the known attributes from HRDF with A__ . The names are derived from the traffic information. In some cases, these also correspond to a combination of SIRI facilities. The mapping is done according to Notes2FacilitiesMappingFile. In OJP 1.0 not all of them are available. In such cases, no mapping takes place.

Some points are stored in extensions:

  • Name/text (e.g. “Train“) Train Transport mode (transport mode category, download from https://opentransportdata.swiss/de/dataset/verkehrsmittellisten)
  • ShortName/Text (e.g. “IC“) Transport submode abbr. (Offer category short description, download from https://opentransportdata.swiss/de/dataset/verkehrsmittellisten
  • PublishedLineName/Text (e.g. “IC8” or “S1”) passenger relevant route text
  • TimedLeg.Extension.TransportTypeName/Text (e.g. “InterCity“) Transport submode name (offer category name, download from https://opentransportdata.swiss/de/dataset/verkehrsmittellisten)
  • TimedLeg.Extension.PublishedJourneyNumber/Text (e.g. “829”) Train number (train number)
  • TimedLeg.Extension.OperatorName/Text (e.g. “Swiss Federal Railways SBB“) OperatorName

TransferLegs are used for changes:

Improvements will be necessary particularly for transfers in terms of BehiG (disability equality legislation).

Geographical information used

The walking routes are based on OSM.

The following parts are currently based exclusively on OSM:

  • in ContinuousLeg and TransferLeg (TransferMode=walk):
  • TrackSection (without coordinates because the LegProjection can only be configured for all leg types together due to missing trip routes)
  • TurnAction
  • in TimedLeg
  • LegIntermediates

Important:

  • IncludeAccessibility will only be supported once BehiG enters into force

OJP-TripRequest with Sharing Services

New since August 2022, OJP TripRequest can compute trips which include sharing vehicles (bycicle, eScooter, rental bike or carsharer) at the beginning and/or end (first and/or last mile).

General Notes

The functionality has an experimental character for the time being. Unexpected or less practical travel chains may result. The SKI+ team is happy to receive feedback on this.

As far as possible, elements of the OJP 1.0 standard were used. However, some enhancements had to be implemented by means of extensions. Adjustments are to be expected with regard to the planned new major version OJP 2.0.

The calculations are based on this data source.

As an alternative to the TripRequest, the locations of the sharing vehicles can now be retrieved via the OJPLocationInformationRequest.

Parameters for Configuration of the TripRequest

The query in the TripRequest is controlled via parameters (additional XML elements) in four possible places:

1. Monomodal Trips by Bicyle

Based on the OJP 1.0 standard, <ojp:Params> is supplemented with the element <ojp:ItModesToCover>, having a value “cycle”:

2. Monomodal Trips by eScooter, Bicycle Rental or Car Sharing

<ojp:Params> is supplemented with an extension:

with the value “escooter_rental”, “bicycle_rental” or “car_sharing”, respectively.

3. Intermodal Trips with Public Transport and Bicycle at the Beginning and/or End

Based on the OJP 1.0 standard, <ojp:Origin> and/or <ojp:Destination> are supplemented with the <ojp:IndividualTransportOptions> element. This defines the mode (cycle), duration min/max in minutes and distance min/max in meters, as shown in the following example.

4. Intermodal Trips with Public Transport and eScooter, Bicycle Rental or Car Sharing at the Beginning and/or End

<ojp:Params> is extended with an extension, with <ojp:Origin> and/or <ojp:Destination> and with mode escooter_rental, bicycle_rental or car_sharing, respectively, as shown in the following example:

Overview of Possible Combinations

The following table shows which combinations make sense for monomodal and multimodal trips. (Note: public transport is considered here as one mode, even if including different modes of transport and interchanges):

combination monomodal trip multimodal —
mode at beginning		 multimodal —
mode at end		 mode beginning & end
public transport default — — —
on foot ItModesToCover=walk  or
IndividualTransportOptions=walk (hikes, s. above)		 default default default
by bike (your own) ItModesToCover=
cycle		 IndividualTransportOptions
… Mode=cycle		 — —
by car (your own) ItModesToCover=
self-drive-car		 — — —
bike sharing Ext./ItModesToCover=
bicycle_rental		 Ext./Origin/Mode=
bicycle_rental		 Ext./Destin./Mode=
bicycle_rental		 possible if origin und destin. modes are equal
e-scooter sharing Ext./ItModesToCover=
escooter_rental		 Ext./Origin/Mode=
escooter_rental		 Ext./Destin./Mode=
escooter_rental		 possible if origin und destin. modes are equal
car sharing Ext./ItModesToCover=
car_sharing		 — Ext./Destin./Mode=
car_sharing		 —

 

 

Search for car tunnel trains

Example of a request for a car tunnel train (ATZ):