tper-hellobus-skill（tper 哈罗布斯技能）

TPER Hellobus: Bologna & Ferrara Bus Times

This skill provides real-time and scheduled arrival information for TPER buses in Bologna and Ferrara by querying the official Hellobus API.

When to Use This Skill

Use this skill when the user:

• Asks about bus arrivals at a specific stop in Bologna or Ferrara
• Mentions TPER, bus line numbers, or stop codes
• Wants to know when the next bus is coming
• Requests scheduled arrival times for a specific time
• Asks about real-time bus tracking

How It Works

The skill queries the TPER Hellobus API with three parameters:

1. fermata (required): Numeric stop code (e.g., "4476", "8001")
2. linea (required): Bus line number (e.g., "11", "27", "101")
3. oraHHMM (optional): Time in HHmm format (e.g., "1830" for 6:30 PM)

Critical Logic:

• If oraHHMM is omitted or empty, the API returns real-time GPS tracking data
• If oraHHMM is provided, the API returns scheduled arrivals for that time

API Endpoint

GET https://hellobuswsweb.tper.it/web-services/hellobus.asmx/QueryHellobus

Parameters:

• fermata: Stop code (string, numeric)
• linea: Line number (string, numeric)
• oraHHMM: Time in HHmm format (string, optional - leave empty for real-time)

Example API Calls:

Real-time tracking (GPS):

https://hellobuswsweb.tper.it/web-services/hellobus.asmx/QueryHellobus?fermata=4476&linea=11&oraHHMM=

Scheduled times:

https://hellobuswsweb.tper.it/web-services/hellobus.asmx/QueryHellobus?fermata=4476&linea=11&oraHHMM=1830

Response Format

The API returns a response like:

TperHellobus: 11B DaSatellite 18:02 (Bus1634 CON PEDANA), 11B DaSatellite 18:18 (Bus5504 CON PEDANA)

Components:

• 11B: Line number with variant
• DaSatellite: Real-time GPS data indicator (or scheduled time indicator)
• 18:02: Arrival time
• Bus1634: Bus identifier
• CON PEDANA: Wheelchair accessible platform indicator

Implementation Steps

1. Parse User Input

Extract from the user's query:

• Stop code: Numeric identifier (e.g., 4476)
• Line number: Numeric line (e.g., 11)
• Time (optional): If user mentions a specific time like "6:30 PM", "18:30", "at 3pm"

2. Convert Time Format

If the user provides a time:

• Parse the time from natural language (e.g., "6:30 PM", "18:30", "3pm")
• Convert to HHmm format (e.g., "1830", "1500")
• Use Europe/Rome timezone for any timezone-related conversions

Time conversion examples:

• "6:30 PM" → "1830"
• "3:00 PM" → "1500"
• "9:15 AM" → "0915"
• "18:30" → "1830"

3. Make API Request

Use the bash_tool with curl to call the API (web_fetch has URL restrictions):

# For real-time (no time specified):
curl "https://hellobuswsweb.tper.it/web-services/hellobus.asmx/QueryHellobus?fermata={stop_code}&linea={line_number}&oraHHMM="

# For scheduled time:
curl "https://hellobuswsweb.tper.it/web-services/hellobus.asmx/QueryHellobus?fermata={stop_code}&linea={line_number}&oraHHMM={time_hhmm}"

Important: Ensure proper URL encoding and handle the XML/text response from the API.

4. Parse and Format Response

The API response is plain text. Parse it and format as a bullet list:

Input: TperHellobus: 11B DaSatellite 18:02 (Bus1634 CON PEDANA), 11B DaSatellite 18:18 (Bus5504 CON PEDANA)

Output format:

Bus arrivals for line 11 at stop 4476:
• 11B DaSatellite 18:02 (Bus1634 CON PEDANA)
• 11B DaSatellite 18:18 (Bus5504 CON PEDANA)

Split on commas and present each arrival as a bullet point.

5. Error Handling

If the API returns an error or unexpected response:

• Report the error clearly to the user
• Include the original API response if helpful for debugging
• Suggest checking the stop code and line number

Common errors might include:

• Invalid stop code
• Line doesn't serve that stop
• No buses found for the specified time
• API connection issues

User Interaction Examples

Example 1: Real-time tracking

User: "When is the next bus 11 arriving at stop 4476?"
Claude: [Queries API with oraHHMM empty]
Response: 
Bus arrivals for line 11 at stop 4476 (real-time):
• 11B DaSatellite 18:02 (Bus1634 CON PEDANA)
• 11B DaSatellite 18:18 (Bus5504 CON PEDANA)

Example 2: Scheduled time

User: "Check the schedule for bus 27 at stop 8001 for 6:30 PM"
Claude: [Queries API with oraHHMM=1830]
Response:
Bus arrivals for line 27 at stop 8001 at 18:30:
• 27 Orario 18:35 (Bus2045)
• 27 Orario 18:50 (Bus3012)

Example 3: Error handling

User: "Bus 99 at stop 1234"
Claude: [Queries API, receives error]
Response: "I couldn't find bus 99 at stop 1234. Please verify the stop code and line number are correct for the TPER network."

Important Notes

• Stop codes are numeric only (not stop names)
• Line numbers are numeric only (e.g., "11", not "11B" - the API adds variants)
• Empty oraHHMM = real-time GPS tracking
• Provided oraHHMM = scheduled arrivals
• Always use Europe/Rome timezone for time conversions
• Format times as HHmm (24-hour format, no colon)

Testing

Test cases to verify the skill works:

• Line 11, Stop 4476 (real-time)
• Line 11, Stop 4476, Time 18:30 (scheduled)
• Invalid stop code (error handling)
• Time format conversion (various user inputs)