Plan a multi-stop itinerary using the Google Routes (Directions) API

Verified steps

1. Use the Routes API (preferred over the legacy Directions API): POST to https://routes.googleapis.com/directions/v2:computeRoutes with origin, destination, and intermediates[] for waypoints; set X-Goog-FieldMask to routes.duration,routes.distanceMeters,routes.legs.
2. For ordered multi-stop routes, set optimizeWaypointOrder: false and list intermediates in the desired order; set it to true to let Google optimize the waypoint order (TSP optimization), then read back the optimizedIntermediateWaypointIndex array to know the computed order.
3. Specify travelMode: DRIVE, WALK, BICYCLE, or TRANSIT; for transit, add transitPreferences with allowedTravelModes and routingPreference.
4. Set departureTime (RFC 3339 UTC) or arrivalTime for traffic-aware routing; omitting both returns duration without real-time traffic, which underestimates travel time in congested cities.
5. Parse the response: routes[0].legs[] maps to each segment between stops; each leg has duration (seconds), distanceMeters, and steps[] with navigation instructions; sum leg durations for total trip time.
6. For itinerary planning across days, batch waypoints into per-day sub-routes — the API supports up to 25 waypoints per request on standard plans, but large batches increase latency and cost.