Updated Documentation for OMNY Needs

This document describes the addition features required for the OMNY trip planning application. These features are currently available on the demo site. Once these features have been thoroughly tested, they will be released to production and this documentation will be moved into the full production documentation found here:

Updated Fares Data

Multiple Fare Types

The MTA can have multiple fares for different users, e.g., users eligible for reduced fare or users that have a monthly pass will not pay full fare for a trip. In order to show these different fares in the OMNY app, OTP needs to return multiple fares types for each trip.

The current demo server shows fares in the following format.

<fare>
    <fare>
        <**FARETYPE1**>
            <currency>
                <symbol>**CURRENCY SYMBOL (e.g., $)**</symbol>
                <currency>**CURRENCY TYPE(e.g., USD)**</currency>
                <defaultFractionDigits>**Number of Decimals Points for Rounding**</defaultFractionDigits>
                <currencyCode>**CURRENCY CODE (e.g., USD)**</currencyCode>
            </currency>
            <cents>**COST IN CENTS**</cents>
        </**FARETYPE1**>
        <**FARETYPE2**> ETC.
        <**FARETYPE3**> ETC. 
    </fare>
</fare>

Currently, the demo server returns the regular fare as well as the reduced fare. The reduced fare is shown as 'special' in the example below.

Sample Call:

http://otp-mta-demo.camsys-apps.com/otp/routers/default/plan?fromPlace=40.80965166748853%2C-73.9541244506836&toPlace=40.71629785715124%2C-74.00768280029297&time=5%3A22pm&date=07-10-2019&mode=TRANSIT%2CWALK&maxWalkDistance=804.672&arriveBy=false&wheelchair=false&locale=en
&apikey=<your api key>

Sample Response:

Below is a detail of the fare portion of a Plan call response. The total fare for each itinerary will be shown at the top level of each itinerary object.

<fare>
    <fare>
        <special>
            <currency>
                <symbol>$</symbol>
                <currency>USD</currency>
                <defaultFractionDigits>2</defaultFractionDigits>
                <currencyCode>USD</currencyCode>
            </currency>
            <cents>135</cents>
        </special>
        <regular>
            <currency>
                <symbol>$</symbol>
                <currency>USD</currency>
                <defaultFractionDigits>2</defaultFractionDigits>
                <currencyCode>USD</currencyCode>
            </currency>
            <cents>275</cents>
        </regular>
    </fare>
</fare>

Fares within Legs

In order to handle transfers, OTP needs to return fares broken out by leg. For instance, if a traveler transfers from subway to a bus, then the transfer is free. The first transit leg of that trip will be $2.75, and the second transit leg of that trip will be $0. However, if a traveler transfers from subway to an Express Bus that normally costs $6.00, then the transfer is not free. The first transit leg of that trip will be $2.75 and the second transit leg of that trip will be $3.25 to make up the difference between the subway fare and the Express Bus fare.

<Response> # The full response of the Plan call
  <plan> # Details related to the itineraries.
   <itineraries> # A set of itineraries. By default, OTP returns up to three itinerary options for each plan call.
     <itineraries> # An individual itinerary, it includes the origin, destination, total fare, and the complete set of legs.
       <legs> # Legs are the building blocks of an itinerary. E.g., if you walk to a bus, take the bus for 10 blocks, and then walk to your destination, then your trip had three legs. 2 walking legs, and 1 transit leg.
         <legs> # Information about each leg, e.g., start time, end time, origin, destination, fare information if applicable.
           <fares> Here is where the fares object will be for each leg.  The fares object is identical to the fares object at the itinerary level.

OMNY-enabled Stops

In order for the UI to know which routes and stations are OMNY-enabled, the OTP plan call and the OTP nearby call need to return if a station and/or route is OMNY-enabled. This is done using the flag below:

<regionalFareCardAccepted>false</regionalFareCardAccepted>

This flag will appear 3 different places.

1. In the nearby api call, all upcoming arrivals that are OMNY supported will show under the element for train/bus scheduled to arrive at the station. Here is a sample nearby API call:

http://otp-mta-demo.camsys-apps.com/otp/routers/default/nearby?stops=MNR:74&apikey=<your api key>

2. In the Plan call at the leg level. Each leg of a trip that includes a transit route will include the <regionalFareCardAccepted> flag.

3. In the upcomingStopTimes flag. Each transit leg also includes a list of upcoming arrivals. Each of those stop times will include the <regionalFareCardAccepted> flag.