Commute Traffic Checker (TomTom)
Purpose
Query real-time traffic data from TomTom for any route and provide the user with actionable travel advice. The script handles geocoding (resolving place names to coordinates) and routing (calculating travel time with live traffic) — all via the same TomTom API key.
Determining Origin and Destination
The origin and destination are not static — you must determine them from what the user tells you. Examples:
- "How's traffic from the office to home?" → You must know (or ask) where their office and home are.
- "Check traffic Basel to Zurich" → origin=Basel, destination=Zurich.
- "Should I leave now?" → Use previously discussed or known origin/destination. If unknown, ask.
- "What's the commute like?" → If you know the user's regular commute, use that. Otherwise, ask.
Rules:
- If both origin and destination are clear from context, proceed immediately.
- If only one is clear, ask for the missing one.
- If neither is clear and you have no prior context, ask the user for both.
- Accept any format: addresses, city names, landmarks, coordinates — the script geocodes automatically.
Running the Traffic Check
Execute the script with origin and destination as arguments:
python3 {baseDir}/scripts/check_traffic.py --origin "<ORIGIN>" --destination "<DESTINATION>"
Examples:
python3 {baseDir}/scripts/check_traffic.py --origin "Basel, Switzerland" --destination "Zurich, Switzerland"
python3 {baseDir}/scripts/check_traffic.py --origin "Basel SBB" --destination "Paradeplatz, Zürich"
python3 {baseDir}/scripts/check_traffic.py --origin "Aeschenplatz, Basel" --destination "ETH Zürich"
Interpreting the Output
The script returns JSON with one or more route alternatives. For each route:
| Field |
Meaning |
travel_time_min |
Total travel time with current live traffic |
no_traffic_time_min |
Travel time with zero traffic (free-flow) |
historic_traffic_time_min |
Typical travel time based on historical patterns |
live_traffic_time_min |
Time including live incident data |
traffic_delay_min |
Extra delay caused by current traffic |
traffic_delay_pct |
Delay as percentage of free-flow time |
congestion |
Derived level: light, moderate, or heavy |
distance_km |
Route distance in kilometers |
departure_time / arrival_time |
Departure and estimated arrival timestamps |
Congestion classification:
- Light: traffic delay adds less than 20% to free-flow time
- Moderate: 20–50% above free-flow
- Heavy: more than 50% above free-flow
Presenting Results to the User
When presenting traffic data, always include:
- The fastest route and its estimated travel time.
- Traffic delay in plain language (e.g., "Currently 8 minutes delay due to traffic on the A2, adding about 15% to the normal drive time").
- Comparison of alternatives if multiple routes are returned.
- A recommendation: whether to leave now or wait, based on congestion level.
Keep it concise and practical. The user wants to know: "How long will it take and should I go now?"
Error Handling
- If the script returns
{"status": "error"}, relay the error message to the user.
- If
TOMTOM_API_KEY is not configured, tell the user to set it up in ~/.openclaw/openclaw.json.
- If geocoding fails (no coordinates found), the location may be too vague — ask the user to be more specific.
- If no routes are returned, suggest trying different location descriptions.
1---2name: commute-traffic3description: Check real-time traffic conditions for a route between two locations using TomTom. Use when the user asks about traffic, commute time, best time to leave, driving conditions, or road congestion. The user provides origin and destination conversationally — extract them from context.4---5
6# Commute Traffic Checker (TomTom)
7
8## Purpose
9
10Query real-time traffic data from TomTom for any route and provide the user with actionable travel advice. The script handles geocoding (resolving place names to coordinates) and routing (calculating travel time with live traffic) — all via the same TomTom API key.
11
12## Determining Origin and Destination
13
14The origin and destination are **not static** — you must determine them from what the user tells you. Examples:
15
16- "How's traffic from the office to home?" → You must know (or ask) where their office and home are.
17- "Check traffic Basel to Zurich" → origin=Basel, destination=Zurich.
18- "Should I leave now?" → Use previously discussed or known origin/destination. If unknown, ask.
19- "What's the commute like?" → If you know the user's regular commute, use that. Otherwise, ask.
20
21**Rules:**
221. If both origin and destination are clear from context, proceed immediately.
232. If only one is clear, ask for the missing one.
243. If neither is clear and you have no prior context, ask the user for both.
254. Accept any format: addresses, city names, landmarks, coordinates — the script geocodes automatically.
26
27## Running the Traffic Check
28
29Execute the script with origin and destination as arguments:
30
31```bash
32python3 {baseDir}/scripts/check_traffic.py --origin "<ORIGIN>" --destination "<DESTINATION>"
33```
34
35**Examples:**
36
37```bash
38python3 {baseDir}/scripts/check_traffic.py --origin "Basel, Switzerland" --destination "Zurich, Switzerland"
39python3 {baseDir}/scripts/check_traffic.py --origin "Basel SBB" --destination "Paradeplatz, Zürich"
40python3 {baseDir}/scripts/check_traffic.py --origin "Aeschenplatz, Basel" --destination "ETH Zürich"
41```
42
43## Interpreting the Output
44
45The script returns JSON with one or more route alternatives. For each route:
46
47| Field | Meaning |
48|-------|---------|
49| `travel_time_min` | Total travel time **with current live traffic** |
50| `no_traffic_time_min` | Travel time with zero traffic (free-flow) |
51| `historic_traffic_time_min` | Typical travel time based on historical patterns |
52| `live_traffic_time_min` | Time including live incident data |
53| `traffic_delay_min` | Extra delay caused by current traffic |
54| `traffic_delay_pct` | Delay as percentage of free-flow time |
55| `congestion` | Derived level: `light`, `moderate`, or `heavy` |
56| `distance_km` | Route distance in kilometers |
57| `departure_time` / `arrival_time` | Departure and estimated arrival timestamps |
58
59### Congestion classification:
60- **Light**: traffic delay adds less than 20% to free-flow time
61- **Moderate**: 20–50% above free-flow
62- **Heavy**: more than 50% above free-flow
63
64## Presenting Results to the User
65
66When presenting traffic data, always include:
67
681. **The fastest route** and its estimated travel time.
692. **Traffic delay** in plain language (e.g., "Currently 8 minutes delay due to traffic on the A2, adding about 15% to the normal drive time").
703. **Comparison of alternatives** if multiple routes are returned.
714. **A recommendation**: whether to leave now or wait, based on congestion level.
72
73Keep it concise and practical. The user wants to know: *"How long will it take and should I go now?"*
74
75## Error Handling
76
77- If the script returns `{"status": "error"}`, relay the error message to the user.
78- If `TOMTOM_API_KEY` is not configured, tell the user to set it up in `~/.openclaw/openclaw.json`.
79- If geocoding fails (no coordinates found), the location may be too vague — ask the user to be more specific.
80- If no routes are returned, suggest trying different location descriptions.
modbender