Suggest transit routes
POST /api/transit/suggest Get transit route suggestions between two locations using Google Maps Directions API.
Request Authentication: None required (internal API)Headers:
Content-Type: application/json
Body parameters: Origin location (place name, address, or coordinates)
Destination location (place name, address, or coordinates)
Desired departure time in ISO 8601 format
Desired arrival time in ISO 8601 format
Day index for itinerary planning
Use either departure_time or arrival_time, not both.
Response Indicates if the request was successful
Array of transit route options (up to 3, sorted by duration) Show TransitOption object
Route summary (e.g., “M1 + L train”)
Total journey duration in minutes
Currency code (e.g., “USD”)
Number of transfers required
Total walking time in minutes
Local departure time (ISO 8601 format, truncated to minutes)
Local arrival time (ISO 8601 format, truncated to minutes)
Route reference (encoded polyline or identifier)
Primary transit mode: subway, bus, tram, rail, ferry, walk_mix, or other
Error message if ok is false
Example request curl -X POST http://localhost:8080/api/transit/suggest \ -H "Content-Type: application/json" \ -d '{ "origin": "Times Square, New York", "destination": "Brooklyn Bridge, New York", "departure_time": "2026-03-15T09:00:00" }'
Example response { "ok" : true , "data" : [ { "summaryLabel" : "Subway 1 + Walk" , "durationMinutes" : 28 , "estimatedCost" : 2.75 , "currency" : "USD" , "transfers" : 0 , "walkingMinutes" : 8 , "departureTimeLocal" : "2026-03-15T09:00" , "arrivalTimeLocal" : "2026-03-15T09:28" , "providerRouteRef" : "mx~fFppvbMjAv@..." , "mode" : "walk_mix" }, { "summaryLabel" : "Subway N + R" , "durationMinutes" : 32 , "estimatedCost" : 2.75 , "currency" : "USD" , "transfers" : 1 , "walkingMinutes" : 5 , "departureTimeLocal" : "2026-03-15T09:00" , "arrivalTimeLocal" : "2026-03-15T09:32" , "providerRouteRef" : "route-2" , "mode" : "subway" } ] }
Error responses Status codes:
400 - Missing origin/destination or invalid time parameters503 - Google Maps API key not configured502 - Google Maps API error or denied request500 - Internal server error
Special cases:
Returns empty data array when no transit routes found (ZERO_RESULTS)
Search transit places
GET /api/transit/places/search Autocomplete search for transit locations using Google Places API.
Request Authentication: None required (internal API)Query parameters: Search query (minimum 2 characters)
Response Array of place suggestions (up to 8, excluding airports) Show TransitPlaceSuggestion object
Place ID (same as placeId)
Full formatted address/description
Secondary text (e.g., city, country)
Array of place type strings
Example request curl "http://localhost:8080/api/transit/places/search?q=central%20park"
Example response { "ok" : true , "data" : [ { "id" : "ChIJ4zGFAZpYwokRGUGph3Mf37k" , "name" : "Central Park" , "displayName" : "Central Park, New York, NY, USA" , "placeId" : "ChIJ4zGFAZpYwokRGUGph3Mf37k" , "mainText" : "Central Park" , "secondaryText" : "New York, NY, USA" , "types" : [ "park" , "tourist_attraction" , "point_of_interest" , "establishment" ] }, { "id" : "ChIJOwg_06VPwokRYv534QaPC8g" , "name" : "Grand Central Terminal" , "displayName" : "Grand Central Terminal, New York, NY, USA" , "placeId" : "ChIJOwg_06VPwokRYv534QaPC8g" , "mainText" : "Grand Central Terminal" , "secondaryText" : "New York, NY, USA" , "types" : [ "transit_station" , "point_of_interest" , "establishment" ] } ] }
Error responses Status codes:
503 - Google Maps API key not configured502 - Google Places API error500 - Internal server error
Special cases:
Returns empty data array for queries shorter than 2 characters