skanetrafiken

# Skånetrafiken Trip Planner Plan public transport journeys in Skåne, Sweden with real-time departure information. ## Commands ### 1. Search Location Search for stations, addresses, or points of interest. ```bash ./search-location.sh <query> [limit] ``` | Argument | Description | |----------|-------------| | `query` | Location name to search for | | `limit` | Number of results to show (default: 3, max: 10) | **Output includes:** - `ID` - The location identifier (use this in journey search) - `Name` - Official name of the location - `Type` - STOP_AREA (station), ADDRESS, or POI (point of interest) - `Area` - Region/municipality - `Coordinates` - Latitude, longitude **When to increase limit:** - First result doesn't match user's intent - User's query is ambiguous (e.g., "station", "centrum") - Need to show user multiple options to choose from ### 2. Journey Search Plan a journey between two locations using their IDs. ```bash ./journey.sh <from-id> <from-type> <to-id> <to-type> [datetime] [mode] ``` | Argument | Description | |----------|-------------| | `from-id` | Origin location ID (from search) or coordinates (`lat#lon`) | | `from-type` | `STOP_AREA`, `ADDRESS`, `POI`, or `LOCATION` (for coordinates) | | `to-id` | Destination location ID or coordinates | | `to-type` | Type of destination | | `datetime` | Optional: `"18:30"`, `"tomorrow 09:00"`, `"2026-01-15 09:00"` | | `mode` | Optional: `"depart"` (default) or `"arrive"` | **Important:** The Journey API only accepts `STOP_AREA` and `LOCATION` types. For `ADDRESS` or `POI` results, use the coordinates as `lat#lon` with type `LOCATION`. --- ## Understanding User Time Intent Before searching, understand what the user wants: ### Intent Types | User Says | Intent | How to Query | |-----------|--------|--------------| | "now", "next bus", "how do I get to" | **Travel Now** | No datetime parameter | | "in 30 minutes", "in 1 hour", "after lunch" | **Depart Later** | Calculate time, use `depart` mode | | "around 15:00", "sometime afternoon" | **Around Time** | Query with offset (see below) | | "arrive by 18:00", "need to be there at 9" | **Arrive By** | Use `arrive` mode | | "tomorrow morning", "on Friday at 10" | **Future Time** | Use specific datetime | ### Handling "Around Time" Queries When user wants options "around" a time, query 15-30 minutes earlier to show options before and after: ```bash # User: "I want to travel around 15:00" # Query at 14:30 to get options spanning 14:30-16:00+ ./journey.sh ... "14:30" depart ``` ### Relative Time Calculations Convert relative times to absolute: | User Says | Current: 14:00 | Query Time | |-----------|----------------|------------| | "in 30m" | → | "14:30" | | "in 1h" | → | "15:00" | | "in 2 hours" | → | "16:00" | --- ## LLM Response Formatting When presenting journey results to users, use these emojis and formatting guidelines. ### Emoji Reference | Emoji | Use For | |-------|---------| | 🚂 | Train (Pågatåg, Öresundståg) | | 🚌 | Bus | | 🚇 | Metro (Copenhagen) | | 🚋 | Tram | | ⛴️ | Ferry | | 🚶 | Walking segment | | ⏱️ | Time/duration | | 🕐 | Departure time | | 🏁 | Arrival time | | 📍 | Stop/station | | 🏠 | Origin (home/start) | | 🎯 | Destination | | ⚠️ | Delay or disruption | | ✅ | On time | | 🔄 | Transfer/change | | 🛤️ | Platform/track | ### Response Structure **Always include these key elements from the tool output:** 1. **When to leave** - The actual time user needs to start (including walking) 2. **Walking segments** - Distance and time for any walking 3. **Transport departure** - When the bus/train actually leaves 4. **Arrival time** - When user reaches destination 5. **Any delays** - Show deviation from schedule ### Example Response Format **For a simple direct journey:** ``` 🏠 **Leave home at 09:00** 🚶 Walk 450m to Möllevångstorget (5 min) 📍 **Möllevångstorget** → 🎯 **Malmö C** 🚌 Bus 5 departs 09:07 from Möllevångstorget 🏁 Arrives 09:18 at Malmö C ⏱️ Total: 18 min ``` **For a journey with transfer:** ``` 🏠 **Leave at 08:45** 🚶 Walk 300m to Västra Hamnen (4 min) 📍 **Västra Hamnen** → 🔄 **Malmö C** → 🎯 **Lund C** **Leg 1:** 🚌 Bus 2 departs 08:51 [🛤️ Läge A] 🏁 Arrives Malmö C 09:05 🔄 Transfer at Malmö C (6 min) **Leg 2:** 🚂 Pågatåg departs 09:11 [🛤️ Spår 4] 🏁 Arrives Lund C 09:23 ⏱️ Total: 38 min | 🔄 1 change ``` **With delays:** ``` 🕐 **Depart 14:30** from Triangeln 🚂 Öresundståg 1042 → København H ⚠️ +8 min delay (expected 14:38 instead of 14:30) 🏁 Arrives ~15:25 (normally 15:17) ``` ### Walking Segment Details **CRITICAL: Always show walking details from the tool output:** - Distance in meters (from `line.distance`) - Include walking in the "leave time" calculation - Show walking at start AND end of journey Example tool output: ``` → WALK 450m from Kalendegatan to Möllevångstorget ``` Format as: ``` 🚶 Walk 450m to Möllevångstorget (~5 min) ``` Walk time estimate: ~100m per minute (normal walking speed) ### Presenting Multiple Options When showing journey options, make timing crystal clear: ``` I found 3 options for you: **Option 1 - Leave now (09:00)** ✅ Recommended 🚶 5 min walk → 🚌 Bus 5 at 09:07 → arrives 09:25 ⏱️ Total: 25 min **Option 2 - Leave in 15m (09:15)** 🚶 5 min walk → 🚌 Bus 5 at 09:22 → arrives 09:40 ⏱️ Total: 25 min **Option 3 - Leave in 30m (09:30)** 🚶 5 min walk → 🚂 Train at 09:37 → arrives 09:48 ⏱️ Total: 18 min | Faster but later departure ``` ### Time Offset Notation Use clear notation for departure times: | Notation | Meaning | |----------|---------| | "now" | Immediately | | "in 15m" | 15 minutes from now | | "in 1h" | 1 hour from now | | "at 14:30" | Specific time | --- ## LLM Workflow: How to Plan a Trip Follow this workflow when a user asks for a trip: ### Step 1: Understand Time Intent Parse what the user wants: - **"How do I get to..."** → Travel now - **"I need to be there at 18:00"** → Arrive mode - **"Sometime around 3pm"** → Query 14:30, show range - **"In about an hour"** → Calculate from current time ### Step 2: Search for Both Locations Search for origin and destination separately: ```bash ./search-location.sh "Malmö C" ./search-location.sh "Emporia" ``` ### Step 3: Validate Search Results **Check each result carefully:** 1. **Exact or close match?** - If the name matches what the user asked for, proceed. 2. **Multiple results returned?** - The script shows up to 10 matches. If the first result isn't clearly correct, ask the user to confirm. 3. **Name significantly different?** - If user asked for "the mall near Hyllie" and result shows "Emporia", confirm with user: "I found Emporia shopping center near Hyllie. Is this correct?" 4. **No results found?** - Try alternative strategies (see below). ### Step 4: Handle Ambiguous or Failed Searches **When results don't match or are ambiguous, ask clarifying questions:** ``` I searched for "centrum" and found multiple locations: 1. Malmö Centrum (bus stop) 2. Lund Centrum (bus stop) 3. Helsingborg Centrum (bus stop) Which one did you mean? ``` **When no results are found, try these strategies:** 1. **Try with city name for addresses:** ```bash # If "Storgatan 10" fails, try: ./search-location.sh "Storgatan 10, Malmö" ``` 2. **Try official station names:** ```bash # If "Malmö station" fails, try: ./search-location.sh "Malmö C" ``` 3. **Try landmark name only (without city):** ```bash # If "Emporia, Malmö" fails, try: ./search-location.sh "Emporia" ``` 4. **Use coordinates as last resort:** - If you know the approximate location, use `lat#lon` format directly - Ask user: "I couldn't find that location. Can you provide the address or coordinates?" ### Step 5: Convert Types for Journey API The Journey API only accepts: - `STOP_AREA` - Bus/train stations (use ID directly) - `LOCATION` - GPS coordinates as `lat#lon` **If search returns ADDRESS or POI:** - Use the coordinates from search result - Format as `lat#lon` with type `LOCATION` Example: ```bash # Search returns: ID: 123, Type: ADDRESS, Coordinates: 55.605, 13.003 # Use in journey as: ./journey.sh "55.605#13.003" LOCATION 9021012080000000 STOP_AREA ``` ### Step 6: Execute Journey Search Once you have confirmed IDs/coordinates for both locations: ```bash ./journey.sh <from-id> <from-type> <to-id> <to-type> [datetime] [mode] ``` ### Step 7: Format Response with Emojis Use the emoji guide above to present results clearly. **Always use actual numbers from the tool output - never speculate or estimate.** --- ## Query Formatting Rules **The search API is sensitive to formatting. Follow these rules:** ### Landmarks and POIs: Name Only Use the landmark name WITHOUT city name. ```bash # CORRECT ./search-location.sh "Emporia" ./search-location.sh "Triangeln" ./search-location.sh "Turning Torso" # WRONG - city name breaks POI search ./search-location.sh "Emporia, Malmö" # May return wrong location! ./search-location.sh "Triangeln, Malmö" # Unnecessary, may fail ``` ### Street Addresses: Include City Include city name for better accuracy. ```bash # CORRECT ./search-location.sh "Kalendegatan 12, Malmö" ./search-location.sh "Storgatan 25, Lund" ./search-location.sh "Drottninggatan 5, Helsingborg" # RISKY - may be ambiguous ./search-location.sh "Kalendegatan 12" # Works if unambiguous ``` ### Train Stations: Use Official Names Use "C" suffix for central stations. ```bash # CORRECT ./search-location.sh "Malmö C" ./search-location.sh "Lund C" ./search-location.sh "Helsingborg C" ./search-location.sh "Malmö Hyllie" ./search-location.sh "Malmö Triangeln" # WRONG ./search-location.sh "Malmö" # Ambiguous! ./search-location.sh "Malmö Central" # Not official name ./search-location.sh "Lund station" # Not official name ``` ### Copenhagen (Cross-border) Use Danish names or common alternatives. ```bash # All work ./search-location.sh "København H" ./search-location.sh "Nørreport" ./search-location.sh "Copenhagen Airport" ./search-location.sh "Köpenhamn" ``` --- ## Examples ### Example 1: Travel Now User: "How do I get from Malmö C to Lund C?" ```bash ./search-location.sh "Malmö C" ./search-location.sh "Lund C" ./journey.sh 9021012080000000 STOP_AREA 9021012080040000 STOP_AREA ``` **Response:** ``` 🏠 **Leave now** from Malmö C 📍 **Malmö C** → 🎯 **Lund C** 🚂 Öresundståg 1324 departs 09:04 [🛤️ Spår 2b] 🏁 Arrives 09:16 at Lund C [🛤️ Spår 1] ⏱️ Total: 12 min | ✅ Direct, no changes ``` ### Example 2: Address with Walking User: "I need to go from Kalendegatan 12 in Malmö to Emporia" ```bash ./search-location.sh "Kalendegatan 12, Malmö" ./search-location.sh "Emporia" ./journey.sh "55.595#13.001" LOCATION "55.563#12.973" LOCATION ``` **Response:** ``` 🏠 **Leave at 10:05** 🚶 Walk 320m to Möllevångstorget (~3 min) 📍 **Möllevångstorget** → 🎯 **Emporia** 🚌 Bus 32 departs 10:10 🏁 Arrives 10:28 at Emporia 🚶 Walk 150m to destination (~2 min) ⏱️ Total: 25 min ``` ### Example 3: Arrive By Time User: "I need to be at Copenhagen central by 18:00 tomorrow" ```bash ./search-location.sh "Malmö C" ./search-location.sh "København H" ./journey.sh 9021012080000000 STOP_AREA 9921000008600626 STOP_AREA "tomorrow 18:00" arrive ``` **Response:** ``` 🎯 **Arrive by 18:00** at København H 📍 **Malmö C** → 🎯 **København H** 🚂 Öresundståg departs **17:21** [🛤️ Spår 1] 🏁 Arrives **17:56** ✅ 4 min buffer ⏱️ Journey: 35 min 💡 Leave Malmö C by 17:21 to arrive on time! ``` ### Example 4: Around Time Query User: "I want to travel to Lund around 15:00" ```bash # Query 30 min earlier to show options around 15:00 ./journey.sh 9021012080000000 STOP_AREA 9021012080040000 STOP_AREA "14:30" ``` **Response:** ``` Options around 15:00 for Malmö C → Lund C: **Option 1 - Depart 14:34** (in 25m) 🚂 Pågatåg → arrives 14:52 ⏱️ 18 min **Option 2 - Depart 14:49** (in 40m) 🚂 Öresundståg → arrives 15:01 ⏱️ 12 min **Option 3 - Depart 15:04** (in 55m) ✅ Closest to 15:00 🚂 Pågatåg → arrives 15:22 ⏱️ 18 min Which works best for you? ``` ### Example 5: Relative Time User: "I want to leave in about an hour" ```bash # Current time: 13:00, so query for 14:00 ./journey.sh ... "14:00" ``` **Response:** ``` Options departing around 14:00 (in ~1h): **Leave at 13:55** (in 55m) 🚶 5 min walk → 🚌 Bus 5 at 14:02 → arrives 14:25 **Leave at 14:10** (in 1h 10m) 🚶 5 min walk → 🚂 Train at 14:17 → arrives 14:35 Let me know which one works! ``` ### Example 6: Journey with Delays When tool output shows delays: ``` From: 14:30 Malmö C [+8 min late] ``` **Response:** ``` 📍 **Malmö C** → 🎯 **Lund C** 🚂 Öresundståg 1042 ⚠️ **Running 8 min late** 🕐 Scheduled: 14:30 → Expected: ~14:38 🏁 Arrives ~14:50 (normally 14:42) ``` --- ## When to Ask Clarifying Questions **Always ask when:** 1. **Search returns no results:** - "I couldn't find [location]. Could you provide more details like the full address or nearby landmarks?" 2. **Multiple plausible matches:** - "I found several locations matching '[query]': [list]. Which one did you mean?" 3. **Result name very different from query:** - "You asked for '[user query]' but the closest match I found is '[result name]'. Is this correct?" 4. **User request is vague:** - "From Malmö" - "Which location in Malmö? The central station (Malmö C), or a specific address?" 5. **Cross-border ambiguity:** - "Copenhagen" could mean different stations - confirm if they want København H (central), Airport, or another station. 6. **Time is unclear:** - "When do you want to travel? Now, or at a specific time?" --- ## DateTime Formats All times are Swedish local time (CET/CEST). | Format | Example | Meaning | |--------|---------|---------| | _(empty)_ | | Travel now | | `HH:MM` | `"18:30"` | Today at 18:30 | | `tomorrow HH:MM` | `"tomorrow 09:00"` | Tomorrow at 09:00 | | `YYYY-MM-DD HH:MM` | `"2026-01-15 09:00"` | Specific date | --- ## Output Format ### Journey Option (Raw Tool Output) ``` ══════════════════════════════════════════════════════════════ OPTION 1: Malmö C → Lund C ══════════════════════════════════════════════════════════════ Date: 2026-01-14 Depart: 09:04 Arrive: 09:16 Changes: 0 LEGS: → ORESUND Öresundståg 1324 From: 09:04 Malmö C [Spår 2b] To: 09:16 Lund C [Spår 1] Direction: mot Helsingborg C ``` ### Transport Types | Type | Emoji | Description | |------|-------|-------------| | `TRAIN` | 🚂 | Pågatåg (regional train) | | `ORESUND` | 🚂 | Öresundståg (cross-border train) | | `BUS` | 🚌 | City or regional bus | | `WALK` | 🚶 | Walking segment | | `TRAM` | 🚋 | Tram/light rail | | `METRO` | 🚇 | Copenhagen Metro | | `FERRY` | ⛴️ | Ferry | ### Status Indicators | Indicator | Emoji | Meaning | |-----------|-------|---------| | _(none)_ | ✅ | On time | | `[+X min late]` | ⚠️ | Delayed | | `[-X min early]` | ℹ️ | Running early | | `[PASSED]` | ❌ | Already departed | | `AVVIKELSE` | 🚨 | Service disruption | --- ## Error Handling ### "No locations found" The search returned no results. **Strategies:** 1. Check spelling (Swedish: å, ä, ö) 2. Try official station names with "C" for central 3. For landmarks, remove city suffix 4. For addresses, add city name 5. Ask user for clarification ### "No journeys found" No routes available. **Strategies:** 1. Check if service operates at that hour (late night/early morning limited) 2. Try different departure time 3. Suggest alternative nearby stops --- ## Quick Reference | Location Type | Search Format | Journey Type | |--------------|---------------|--------------| | Train station | `"Malmö C"` | STOP_AREA | | Bus stop | `"Möllevångstorget"` | STOP_AREA | | Address | `"Street 12, City"` | Use coords → LOCATION | | Landmark/POI | `"Emporia"` (no city!) | Use coords → LOCATION | | Coordinates | `55.605#13.003` | LOCATION |