- Key concepts
- OJP Trip Service
- Geographical information used
- OJP-TripRequest with Sharing Services
- General Notes
- Parameters for Configuration of the TripRequest
- 1. Monomodal Trips by Bicyle
- 2. Monomodal Trips by eScooter, Bicycle Rental or Car Sharing
- 3. Intermodal Trips with Public Transport and Bicycle at the Beginning and/or End
- 4. Intermodal Trips with Public Transport and eScooter, Bicycle Rental or Car Sharing at the Beginning and/or End
- Overview of Possible Combinations
- Search for car tunnel trains
Key concepts
- Stops: Use DiDok or stop datasets from other sources.
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
<?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-31T12:30:00Z</RequestTimestamp> <RequestorRef>3CC3C04A-20A0-4B12-AC46-5A7843E328A7</RequestorRef> <ojp:OJPTripRequest> <RequestTimestamp>2020-01-31T12:30:00Z</RequestTimestamp> <ojp:Origin> <ojp:PlaceRef> <ojp:StopPlaceRef>8503000</ojp:StopPlaceRef> <ojp:LocationName> <ojp:Text>Bern</ojp:Text> </ojp:LocationName> </ojp:PlaceRef> </ojp:Origin> <ojp:Destination> <ojp:PlaceRef> <ojp:StopPlaceRef>8505000</ojp:StopPlaceRef> <ojp:LocationName> <ojp:Text>Luzern</ojp:Text> </ojp:LocationName> </ojp:PlaceRef> </ojp:Destination> <ojp:Params> <ojp:NumberOfResults>10</ojp:NumberOfResults> <ojp:OptimisationMethod>fastest</ojp:OptimisationMethod> </ojp:Params> </ojp:OJPTripRequest> </ServiceRequest> </OJPRequest> </OJP> |
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
Elemente | 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:
|
|
||
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<ojp:Location> <ojp:StopPlace> <ojp:StopPlaceRef>8591252</ojp:StopPlaceRef> <ojp:StopPlaceName> <ojp:Text>Zürich, Letzigrund</ojp:Text> </ojp:StopPlaceName> <ojp:TopographicPlaceRef>23026261:27</ojp:TopographicPlaceRef> </ojp:StopPlace> <ojp:LocationName> <ojp:Text xml:lang="de">Zürich, Letzigrund</ojp:Text> </ojp:LocationName> <ojp:GeoPosition> <siri:Longitude>8.50373</siri:Longitude> <siri:Latitude>47.38124</siri:Latitude> </ojp:GeoPosition> </ojp:Location> |
In future the context may also include the situations (faults).
This is followed by 0:* TripResult. The header is followed by
1 2 3 4 5 6 7 8 9 |
<ojp:TripResult> <ojp:ResultId>ID-153A06C3-1F00-4048-9141-A217840479A6</ojp:ResultId> <ojp:Trip> <ojp:TripId>ID-153A06C3-1F00-4048-9141-A217840479A6</ojp:TripId> <ojp:Duration>PT29M</ojp:Duration> <ojp:StartTime>2020-01-20T11:57:00Z</ojp:StartTime> <ojp:EndTime>2020-01-20T12:26:00Z</ojp:EndTime> <ojp:Transfers>1</ojp:Transfers> <!-- ... --> |
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 |
<ojp:TripLeg> <ojp:LegId>1</ojp:LegId> <ojp:TimedLeg> <ojp:LegBoard> <siri:StopPointRef>8591252</siri:StopPointRef> <ojp:StopPointName> <ojp:Text>Zürich, Letzigrund</ojp:Text> </ojp:StopPointName> <ojp:ServiceDeparture> <ojp:TimetabledTime>2020-01-20T11:57:00Z</ojp:TimetabledTime> </ojp:ServiceDeparture> <ojp:Order>1</ojp:Order> </ojp:LegBoard> <ojp:LegIntermediates> <siri:StopPointRef>8591038</siri:StopPointRef> <ojp:StopPointName> <ojp:Text>Zürich, Albisriederplatz</ojp:Text> </ojp:StopPointName> <ojp:ServiceArrival> <ojp:TimetabledTime>2020-01-20T11:59:00Z</ojp:TimetabledTime> </ojp:ServiceArrival> <ojp:ServiceDeparture> <ojp:TimetabledTime>2020-01-20T11:59:00Z</ojp:TimetabledTime> </ojp:ServiceDeparture> <ojp:Order>2</ojp:Order> </ojp:LegIntermediates> <!-- weitere LegIntermediate ---> <ojp:LegAlight> <siri:StopPointRef>8591105</siri:StopPointRef> <ojp:StopPointName> <ojp:Text>Zürich, Bürkliplatz</ojp:Text> </ojp:StopPointName> <ojp:ServiceArrival> <ojp:TimetabledTime>2020-01-20T12:13:00Z</ojp:TimetabledTime> </ojp:ServiceArrival> <ojp:Order>11</ojp:Order> </ojp:LegAlight> <ojp:Service> <ojp:OperatingDayRef>2020-01-20</ojp:OperatingDayRef> <ojp:JourneyRef>sbb:91002::H:j20:1253</ojp:JourneyRef> <siri:LineRef>sbb:91002:</siri:LineRef> <siri:DirectionRef>H</siri:DirectionRef> <ojp:Mode> <ojp:PtMode>tram</ojp:PtMode> <siri:TramSubmode>cityTram</siri:TramSubmode> <ojp:Name> <ojp:Text xml:lang="de">Tram</ojp:Text> </ojp:Name> </ojp:Mode> <ojp:PublishedLineName> <ojp:Text>2</ojp:Text> </ojp:PublishedLineName> <ojp:OperatorRef>sbb:3849</ojp:OperatorRef> <ojp:Attribute> <ojp:Text> <ojp:Text xml:lang="de">Niederflureinstieg</ojp:Text> </ojp:Text> <ojp:Code>A__NF</ojp:Code> </ojp:Attribute> <ojp:DestinationStopPointRef>de:00000:-1</ojp:DestinationStopPointRef> <ojp:DestinationText> <ojp:Text xml:lang="de">Zürich Tiefenbrunnen, Bahnhof</ojp:Text> </ojp:DestinationText> </ojp:Service> </ojp:TimedLeg> </ojp:TripLeg> |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<ojp:TransferLeg> <ojp:TransferMode>walk</ojp:TransferMode> <ojp:LegStart> <siri:StopPointRef>8591105</siri:StopPointRef> <ojp:LocationName> <ojp:Text xml:lang="de">Zürich, Bürkliplatz</ojp:Text> </ojp:LocationName> </ojp:LegStart> <ojp:LegEnd> <siri:StopPointRef>8591105</siri:StopPointRef> <ojp:LocationName> <ojp:Text xml:lang="de">Zürich, Bürkliplatz</ojp:Text> </ojp:LocationName> </ojp:LegEnd> <ojp:TimeWindowStart>2020-01-20T12:13:00Z</ojp:TimeWindowStart> <ojp:TimeWindowEnd>2020-01-20T12:15:00Z</ojp:TimeWindowEnd> <ojp:Duration>PT2M</ojp:Duration> <ojp:WalkDuration>PT2M</ojp:WalkDuration> <ojp:BufferTime>PT0M</ojp:BufferTime> </ojp:TransferLeg> |
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”:
1 |
<ojp:ItModesToCover>cycle</ojp:ItModesToCover> |
2. Monomodal Trips by eScooter, Bicycle Rental or Car Sharing
<ojp:Params> is supplemented with an extension:
1 2 3 |
<ojp:Extension> ... <ojp:ItModesToCover>escooter_rental</ojp:ItModesToCover> ... </ojp: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.
1 2 3 4 5 6 7 |
<ojp:IndividualTransportOptions> <ojp:Mode>cycle</ojp:Mode> <!--Fahrrad am Anfang --> <ojp:MaxDuration>PT30M</ojp:MaxDuration> <!--Optional: maximum duration--> <ojp:MinDuration>PT2M</ojp:MinDuration> <!--Optional: minimum duration--> <ojp:MaxDistance>20000</ojp:MaxDistance> <!--Optional: maximum distance--> <ojp:MinDistance>100</ojp:MinDistance> <!--Optional: minimum distance--> </ojp:IndividualTransportOptions> |
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:
1 2 3 4 5 6 7 8 9 |
<ojp:Extension> <ojp:Origin> <ojp:Mode>escooter_rental</ojp:Mode> <!--eScooter at beginning--> <ojp:MaxDuration>PT30M</ojp:MaxDuration> <!--Optional: maximum duration--> <ojp:MinDuration>PT2M</ojp:MinDuration> <!--Optional: minimum duration--> <ojp:MaxDistance>20000</ojp:MaxDistance> <!--Optional: maximum distance--> <ojp:MinDistance>100</ojp:MinDistance> <!--Optional: minimum distance--> </ojp:Origin> </ojp:Extension> |
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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
<siri:OJP xmlns="http://www.vdv.de/ojp" xmlns:siri="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:schemaLocation="http://www.vdv.de/ojp" version="1.0"> <siri:OJPRequest> <siri:ServiceRequest> <siri:RequestTimestamp>2024-03-21T16:22:30.112Z</siri:RequestTimestamp> <siri:RequestorRef>OJP_JS_SDK_v0.9.31</siri:RequestorRef> <OJPTripRequest> <siri:RequestTimestamp>2024-03-21T16:22:30.112Z</siri:RequestTimestamp> <Origin> <PlaceRef> <StopPlaceRef>8511171</StopPlaceRef> <LocationName> <Text>Kandersteg Autoverlad</Text> </LocationName> </PlaceRef> </Origin> <Destination> <PlaceRef> <StopPlaceRef>8519655</StopPlaceRef> <LocationName> <Text>Goppenstein Autoverlad</Text> </LocationName> </PlaceRef> </Destination> <ojp:Params> <ojp:PrivateModeFilter> <ojp:Exclude>false</ojp:Exclude> </ojp:PrivateModeFilter> <ojp:NumberOfResults>3</ojp:NumberOfResults> <ojp:IncludeTrackSections>false</ojp:IncludeTrackSections> <ojp:IncludeLegProjection>false</ojp:IncludeLegProjection> <ojp:IncludeTurnDescription>false</ojp:IncludeTurnDescription> <ojp:IncludeIntermediateStops>true</ojp:IncludeIntermediateStops> </ojp:Params> </OJPTripRequest> </siri:ServiceRequest> </siri:OJPRequest> </siri:OJP> |