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

1. Resolve

   from

   and

   to

   into either stop IDs (preferred) or address/POI objects using GET /locations or /locations/nearby.
2. Call GET /journeys with arrival or departure parameter as requested, request results=3 and stopovers=true to construct step-by-step legs.
3. Format 2–3 options: show total travel time, number of transfers, walking time, and estimated departure/arrival times.
4. 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.
5. When appropriate, include the journey refreshToken and a GET /journeys/:ref refresh step to update realtime delays.
6. 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.