BVG (Berliner Verkehrsbetriebe) Route Planner

BVG Route Planner Skill

Purpose Provide concise, actionable public-transport directions in Berlin using the v6.bvg.transport.rest API. When to use User asks for directions between two places in Berlin (addresses, stop names, or coordinates). User asks for next departures from a stop/station. User requests to arrive by a specific time (arrive-by) or depart at a specific time. Core behavior Resolve from and to into either stop IDs (preferred) or address/POI objects using GET /locations or /locations/nearby. Call GET /journeys with arrival or departure parameter as requested, request results=3 and stopovers=true to construct step-by-step legs. Format 2–3 options: show total travel time, number of transfers, walking time, and estimated departure/arrival times. Provide step-by-step instructions for the selected journey: walk to stop A (distance/time), take line X toward Y, get off at stop B (platform if available), final walk to destination. When appropriate, include the journey refreshToken and a GET /journeys/:ref refresh step to update realtime delays. For simple next-departure queries, use GET /stops/:id/departures with duration=20 (or configurable) and return the nearest 3 departures. Outputs Human-readable routes with departure times, transfers, walking distances, estimated arrival, and concise step list. Machine-friendly JSON (optional) containing journey id, refreshToken, legs, and stop IDs for programmatic refreshes. References The skill expects to use the v6.bvg.transport.rest API (https://v6.bvg.transport.rest/api.html). See references/API.md for summary and examples. Examples (triggers) "How do I get from Invalidenstraße 43 10115 to Leibnizstraße 62 by public transport?" "When is the next U-Bahn from U Rosenthaler Platz?" "Find journeys that arrive at Deutsche Oper by 17:50 tonight, fastest option first." Notes for implementers IBNR format (CRITICAL): The /journeys endpoint requires base IBNR codes only (6 digits), not the full ID with :: suffixes. ❌ Wrong: de:11000:900110001::3 or de:11000:900110001 ✅ Correct: 900110001 (extract base 6-digit code from /stops results) Process: Call /stops?query=... first, extract the 6-digit id from results, use that for /journeys. URL encoding (CRITICAL): All query string parameters must be properly URL-encoded using urllib.parse.quote() or equivalent. Examples: Space → %20 ö → %C3%B6 ü → %C3%BC Ä → %C3%84 Special chars like &, ?, # → their percent-encoded equivalents Example: Schönhauser Allee → Sch%C3%B6nhauser%20Allee Every API call with address/stop name strings in query params must encode before building the URL. Prefer stop/station IDs when calling /journeys (more reliable than fuzzy names): Use /stops?query=... to resolve names → base IBNR. Use stopovers=true to build readable step lists; include entrances=true when walking-to-entrance accuracy is important. Request results=3 then offer the top 2–3 to the user. Handle timezone-aware ISO datetimes; default to Europe/Berlin if none provided.