Route

The path a ride takes from its origin to its destination, including any breakpoints along the way.

Overview

A route is made up of one or more legs — each leg is a segment between two consecutive locations (e.g., origin → first breakpoint → destination). Each leg contains the distance, estimated duration, and turn-by-turn navigation steps for that segment.

Routes come in two directions:

  • Outgoing (to) — from origin to destination, including any breakpoints.
  • Return (from) — the reverse journey, from destination back to origin.

The user sees available routes displayed visually on the map, similar to Google Maps. If multiple route alternatives are available for a direction, the user picks one. If only one route exists for the given locations, no choice is presented.

General Rules

  • A route is always associated with a ride — it cannot exist independently.
  • Routes are computed on demand via the API and stored in Firestore. Both outgoing (to) and return (from) directions can be computed.
  • All route alternatives returned by the Google Maps Routes API are stored at indices 0, 1, 2, etc. to avoid redundant API calls.
  • The selected route alternative can be changed by the ride creator or any admin while the ride is in draft or upcoming status. Once the first participant taps Start or the ride becomes on-going automatically, the selected route is locked and cannot be changed.
  • Routes are archived as part of the ride archival process at midnight after the ride's end time. See Ride Archival.

Actions

Route selection and changes are handled within the Ride flows:

  • Create a Ride — route is selected during ride creation
  • Edit a Ride — selected route can be changed before the ride starts

Return Route

The return (from) direction is computed and stored alongside the outgoing route. At launch, the return route is not shown to users — it is stored for future use but not surfaced in the UI.

Wishlist — post-launch: Return route navigation and display are not scoped for launch.

Failure Cases

  • No route available: no drivable route can be computed between the chosen locations (e.g. across water or unreachable roads). The creator must change the locations before the ride can be created or the route alternative changed.
  • Zero alternatives on route change: if the Routes API returns no alternatives for the existing breakpoints when changing the selected route, the current selection remains unchanged and the user is prompted to retry.

Schema Reference

See Route Schema for the Firestore subcollection structure.