directions

# Directions Guidelines ## Directions Template Response Skill ## Core Objective Extract structured parameters to populate the `DirectionsExtractorSchema` for rendering directions on a map. ## Multi-Step Route Resolution Policy If the user's query requests a scenic bypass or detour: 1. **Resolve Place Coordinates and IDs (Parallel Search)**: Concurrently search for the origin, destination, and any identified detour waypoints along the corridor. 2. **Compute Route Segments (Parallel Routing)**: Concurrently compute routes for all sequential legs connecting the resolved stops (Origin -> Waypoint, Waypoint -> Destination). 3. **Dispatch Response**: Call `render_directions_template` with the compiled routes and pins. ## Step-by-Step Workflow 1. **Analyze the Query & Constraints**: * Identify the origin and destination names. * **Identify the Requested Travel Mode (MANDATORY)**: Extract the explicit travel mode from the user's query: * `driving`: car, drive, driving, auto, or default if travel mode cannot be inferred. * `walking`: walk, walking, on foot, pedestrian, foot. * `bicycling`: bike, biking, bicycle, bicycling, cycling. * `transit`: bus, train, subway, metro, tube, public transit. 2. **Resolve Place Coordinates and IDs (Parallel Search)**: * Issue ALL `search_places` calls concurrently for the origin, destination, and all intermediate waypoints or scenic stops along the corridor. * **IDENTIFY SCENIC DETOURS & WAYPOINTS**: * If the user asks to "avoid [City X]" or take a "scenic bypass/detour", use your knowledge to identify 2-3 major scenic towns, highway junctions, or landmarks along the alternative bypass corridor (e.g., "Jemez Springs" to avoid Santa Fe between Albuquerque and Los Alamos, or "Winters, CA" and "Anderson Valley, CA" to take backroads between Sacramento and Mendocino). * Concurrently search for these detour waypoints along with the origin and destination. * **STABLE SEARCH QUERIES**: Use specific place or town names (e.g., search for "Anderson Valley, CA" or "Jemez Springs, NM") instead of generic road descriptors (e.g. do not search for "Highway 128 scenic route"), as generic queries are unstable and often return empty results (`{}`). * Do NOT execute independent tool calls sequentially across multiple turns. * Construct sequential route segments connecting the resolved detour waypoints in order: Origin -> Waypoint 1 -> Waypoint 2 -> Destination. 3. **Compute Routes and Dispatch Response (Parallel Routing)**: * Issue `compute_routes` calls concurrently for all route segment pairs. * **STRICT TOOL PARAMETERS**: When calling `compute_routes`, ensure that `origin` and `destination` objects conform to the maps tool contract. Specify **exactly one** identifier: * `placeId`: Use the resolved place ID (e.g., `{"placeId": "ChIJ-ZeD..."}`). This is highly preferred if available. * `address`: Use the address string. * `location`: Use latitude/longitude inside a location sub-object (e.g., `{"location": {"latLng": {"latitude": 37.7, "longitude": -122.4}}}`). Do **NOT** pass `latLng` directly as a root key inside `origin` or `destination` (e.g. do not call `compute_routes(origin={"placeId": "...", "latLng": ...})`). * **GROUNDED ROUTING CONSTRAINT**: NEVER use model knowledge to assume roads used or live traffic. Always rely only on data from `compute_routes`. * Verify route availability for requested `travel_mode`. * **CONSTRUCT THE ROUTES ARRAY**: You MUST compile the computed segments into the `routes` array of the final `render_directions_template` payload. The array must contain all segments sequentially (e.g. `[{"origin": Origin, "destination": Waypoint 1}, {"origin": Waypoint 1, "destination": Destination}]`). Do NOT omit the `routes` array or leave it empty if you successfully computed routes. * **MANDATORY TRAVEL MODE IN DISPATCH**: `travel_mode` is REQUIRED and must NEVER be omitted in `render_directions_template`. Always supply the normalized mode string (`driving`, `walking`, `transit`, or `bicycling`). * Call `render_directions_template` with `DirectionsExtractorSchema` parameters (`heading`, `summary`, `center_lat`, `center_lng`, `zoom`, `routes`, `travel_mode`). ## Handling Routing Failures & Regional Limitations (CRITICAL) Google Maps routing (driving, walking) is not supported in certain regions (such as South Korea). If a tool call to `compute_routes` returns empty results (`{}`) or fails: 1. **Do NOT retry** with alternative queries or locations. 2. Immediately exit the tool-calling loop. 3. Return a user-friendly summary explaining the regional limitation (e.g. "Google Maps directions are not supported in South Korea"), and set the routes list to empty `[]`. ## Output Fields You MUST populate all required fields in the output schema: - **`heading`**: (REQUIRED) A concise, constraint-confirming primary heading for the response. Plain text only (e.g., 'Walking route from Seattle Center to Pike Place Market', 'Driving directions to JFK Airport'). Use sentence case; do NOT include markdown hashtags or conversational filler. - **`summary`**: (REQUIRED) A natural, direct resolution of the route prompt (e.g. 'Driving from [Origin] to [Destination] takes about 19 minutes (14 miles).', 'Walking from Seattle Center to Pike Place Market takes about 20 minutes (1 mile).'). Describe distance using units appropriate to the location (miles vs. km). For driving and public transit modes, always round distance to a whole number. NEVER describe time in seconds or decimals. Always round seconds to the nearest minute. If it rounds to 0 minutes, describe it as "less than a minute". Always describe time as approximate (e.g. about, around, approximately). - **`center_lat`**: Latitude of the center of the route map. - **`center_lng`**: Longitude of the center of the route map. - **`zoom`**: Recommended map zoom level. Default to 12. - **`routes`**: A list of route segments connecting the origin, intermediate waypoints, and the destination in order. - **`travel_mode`**: (REQUIRED) The transit travel mode (`driving`, `walking`, `transit`, `bicycling`). Must match the user's requested travel mode and must never be omitted. ## Examples ### Example 1: Driving Route User Query: "Directions from San Francisco to San Jose by car" Tool Call: `render_directions_template(heading="Driving directions from San Francisco to San Jose", summary="Driving from San Francisco to San Jose takes about 50 minutes via US-101 S.", center_lat=37.55, center_lng=-122.15, zoom=10, routes=[{"origin": {"lat": 37.7749, "lng": -122.4194, "label": "San Francisco", "placeId": "ChIJIQBpAG2ahYAR_6128GcTUEo"}, "destination": {"lat": 37.3382, "lng": -121.8863, "label": "San Jose", "placeId": "ChIJ9T_nxcC1j4ARmMo7S4ABIdM"}}], travel_mode="driving")` ### Example 2: Walking Route User Query: "How do I walk from Central Park to Times Square?" Tool Call: `render_directions_template(heading="Walking route from Central Park to Times Square", summary="Walking from Central Park to Times Square takes about 18 minutes (0.9 miles) down 7th Ave.", center_lat=40.765, center_lng=-73.978, zoom=14, routes=[{"origin": {"lat": 40.768, "lng": -73.974, "label": "Central Park South", "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4"}, "destination": {"lat": 40.758, "lng": -73.985, "label": "Times Square", "placeId": "ChIJmQJItx6vwokRLxVi2JyuzRo"}}], travel_mode="walking")` ### Example 3: Bicycling Route User Query: "Bike directions from Venice Beach to Santa Monica Pier" Tool Call: `render_directions_template(heading="Biking route from Venice Beach to Santa Monica Pier", summary="Biking from Venice Beach to Santa Monica Pier takes around 15 minutes along the Marvin Braude Bike Trail.", center_lat=33.998, center_lng=-118.483, zoom=13, routes=[{"origin": {"lat": 33.985, "lng": -118.469, "label": "Venice Beach", "placeId": "ChIJ-wjh2I-6woARx3H-n9uVn4A"}, "destination": {"lat": 34.009, "lng": -118.497, "label": "Santa Monica Pier", "placeId": "ChIJw8g0Xbm7woARQY1Xq41qB2M"}}], travel_mode="bicycling")` ### Example 4: Transit Route User Query: "Take the subway from Grand Central to Brooklyn Bridge" Tool Call: `render_directions_template(heading="Transit directions from Grand Central to Brooklyn Bridge", summary="Take the 4 or 5 subway line south from Grand Central - 42 St to Brooklyn Bridge - City Hall (approx. 12 minutes).", center_lat=40.731, center_lng=-73.988, zoom=12, routes=[{"origin": {"lat": 40.7527, "lng": -73.9772, "label": "Grand Central Terminal", "placeId": "ChIJ4zBEaKZQwokREuE50bbCGYs"}, "destination": {"lat": 40.7126, "lng": -74.0049, "label": "Brooklyn Bridge - City Hall", "placeId": "ChIJ40i5iRZawokRHqGfF2b_3yI"}}], travel_mode="transit")` ### Example 5: Unspecified Travel Mode (Defaults to Driving) User Query: "Directions from Austin to San Antonio" Tool Call: `render_directions_template(heading="Driving directions from Austin to San Antonio", summary="Driving from Austin to San Antonio takes about 1 hour and 20 minutes via I-35 S.", center_lat=29.85, center_lng=-98.15, zoom=9, routes=[{"origin": {"lat": 30.2672, "lng": -97.7431, "label": "Austin", "placeId": "ChIJLwW05NsQW4YRtxm00DkzqlU"}, "destination": {"lat": 29.4241, "lng": -98.4936, "label": "San Antonio", "placeId": "ChIJrw7QBK9YXIYRowalignfdg4"}}], travel_mode="driving")`