Expose station entrance/exits in routing and directly

[cedarbaum]

Is your feature request related to a problem? Please describe.

Currently, there is no way to get station entrances/exits from the API either when planning a trip or directly as part of dedicated queries/subqueries. Adding this information can enable more detailed itineraries with station ingress/egress explicitly called out as well as better glanceable information via map annotations.

Several popular routing solutions use such information to enhance their UIs currently. Below are examples from Google Maps, Apple Maps, and the Transit app, respectively:

Goal / high level use-case

There are 3 key scenarios I think this information would be useful:

1. For routing directions, being able to explicitly direct a user to an entrance/exit with an annotation on the map if desired.
2. For routing directions, being able to break up walking directions with explicit entrance/exit steps.
3. Showing the user a nearby station and all of its entrance/exit points without requiring them to plan a trip. Consider for example an arrival time board that shows nearby stations, departure times, etc. at a glance.

Describe the solution you'd like

There are 2 types of station entrances/exits that can be exposed by OTP:

1. Those explicitly defined in GTFS data in stops.txt.
2. Those present in OSM data that are correctly associated with tagged boarding locations (see: https://docs.opentripplanner.org/en/latest/BoardingLocations/).

I believe exposing the GTFS data will be significantly easier, since its structure is well defined and it is already explicitly associated with parent stations.

However, OSM data could be exposed through the same API, where the main differences would be (1) the object identifier would be an OSM ID instead of a GTFS ID and (2) the metadata would potentially be less rich depending on the OSM region. Below are example queries focusing on the GTFS case for now, but their structure could potentially be reused for OSM data as well.

Entrances/exits as part of a plan query

By splitting itinerary legs on stop entrances/exits, it becomes possible for API consumers to demarcate the act of entering/exiting a station from other steps by inspecting the stop in the to/from subqueries.

As this breaks compatibility with the existing query structure, adding a query variable splitStopEntrancesAndExits could be used to explicitly opt-in to this new behavior.

I believe this is approximately the approach that @flaktack used for implanting stop entrance/exit steps for the Budapest GO Trip Planner, as described in a recent dev meeting.

Another addition to this structure could be to add new stopEntrance and stopExit subqueries which provide the entrance/exit points in such cases. The advantage of doing this would be a more flexible object structure for entrances/exits which could also incorporate OSM entities in addition to GTFS stops.

plan(splitStopEntrancesAndExits: true) {
  ...
  itineraries {
    ...
    legs {
      ...
      from {
        stop[Entrance/Exit] {
          id
          gtfsId
          name
          lat
          lon
          locationType
          wheelchairBoarding
        }
      }
      to {
        stop[Entrance/Exit] {
          id
          gtfsId
          name
          lat
          lon
          locationType
          wheelchairBoarding
        }
      }
      ...
    }
  }
}

Entrances/exits as part of the stations query and new a top-level entrances query

Entrances and exits could also be directly returned from a top-level entrances query as well as an entrances subquery of the existing stations query:

stations subquery

stations {
  gtfsId
  lat
  lon
  name
  stops {
    ...
  }
  entrances {
    gtfsId
    lat
    lon
    name
    vehicleMode
    locationType
  }
}

Top-level entrances query

entrances() {
  gtfsId
  lat
  lon
  name
  vehicleMode
  locationType
}

Describe alternatives you've considered

The best alternative is probably using vector tile layers (as suggested on Gitter and in a recent dev meeting). However, I believe this approach has a few shortcomings:

1. This will require the usage of a map SDK where custom vector tiling is supported. Such systems may be significantly different in their implementation, requiring custom solutions per vendor.
2. Depending on the tiling implementation, interactivity and custom sizing of iconography may be limited. For example:
   a. Having a larger icon for the relevant entrance of a trip.
   b. Tapping on an entrance to get more information about for a specific entrance (accessibility, etc.).
3. This does not provide a solution to the more granular routing instructions made possible by leg splitting or other comparable query modifications.

Additional context

1. As mentioned previously, @flaktack has done some work on this for the Budapest GO Trip Planner. It is possible this work could be upstreamed as part of this issue. Below is an example itinerary that calls out when to exit/enter stations:

2. I've opened a PR for exposing station entrances via the GraphQL API: Expose station entrances in GraphQL API #6082

3. There is a recent draft PR that attaches station entrances to walk steps: Add subway station entrances to walk steps #6076