Files

615 lines
19 KiB
Python

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
MBTA Transit CLI - Query real-time predictions from MBTA v3 API.
Usage:
mbta.py next [--stop STOP] [--route ROUTE] [--limit N]
mbta.py departures [--config CONFIG]
mbta.py stops --search QUERY
mbta.py routes [--type TYPE]
mbta.py alerts [--route ROUTE]
mbta.py dashboard [--config CONFIG] [--port PORT]
Environment:
MBTA_API_KEY - Optional but recommended for higher rate limits
Get one free at: https://api-v3.mbta.com/portal
"""
import argparse
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Optional
import requests
try:
import yaml
YAML_AVAILABLE = True
except ImportError:
YAML_AVAILABLE = False
MBTA_API_BASE = "https://api-v3.mbta.com"
MBTA_API_KEY = os.getenv("MBTA_API_KEY")
HEADERS = {"accept": "application/json"}
if MBTA_API_KEY:
HEADERS["x-api-key"] = MBTA_API_KEY
# Route type mappings
ROUTE_TYPES = {
0: "Light Rail", # Green Line
1: "Heavy Rail", # Red, Orange, Blue Lines
2: "Commuter Rail",
3: "Bus",
4: "Ferry",
}
def api_get(endpoint: str, params: dict = None) -> dict:
"""Make a GET request to MBTA API."""
try:
resp = requests.get(
f"{MBTA_API_BASE}/{endpoint}",
params=params or {},
headers=HEADERS,
timeout=10,
)
resp.raise_for_status()
return resp.json()
except requests.RequestException as e:
print(f"Error: API request failed - {e}", file=sys.stderr)
sys.exit(1)
def parse_iso8601(dt_str: Optional[str]) -> Optional[datetime]:
"""Parse ISO8601 datetime string."""
if not dt_str:
return None
try:
return datetime.fromisoformat(dt_str)
except Exception:
return None
def now_utc() -> datetime:
return datetime.now(timezone.utc)
def format_minutes(delta_min: float) -> str:
"""Format minutes for display."""
if delta_min < 1:
return "now"
elif delta_min < 60:
return f"{int(delta_min)} min"
else:
hours = int(delta_min // 60)
mins = int(delta_min % 60)
return f"{hours}h {mins}m"
def get_predictions(
stop_id: str,
route_id: Optional[str] = None,
direction_id: Optional[int] = None,
limit: int = 5,
) -> list[dict[str, Any]]:
"""Fetch predictions for a stop."""
params = {
"filter[stop]": stop_id,
"sort": "departure_time",
"page[limit]": limit * 2, # Fetch extra to filter
"include": "trip,route",
}
if route_id:
params["filter[route]"] = route_id
if direction_id is not None:
params["filter[direction_id]"] = str(direction_id)
data = api_get("predictions", params)
# Build lookup maps
trips = {}
routes = {}
for item in data.get("included", []):
if item.get("type") == "trip":
trips[item["id"]] = item
elif item.get("type") == "route":
routes[item["id"]] = item
results = []
now = now_utc()
for pred in data.get("data", []):
attrs = pred.get("attributes", {})
# Get trip info
trip_id = pred.get("relationships", {}).get("trip", {}).get("data", {}).get("id")
trip = trips.get(trip_id, {})
trip_attrs = trip.get("attributes", {})
# Get route info
route_ref = pred.get("relationships", {}).get("route", {}).get("data", {}).get("id")
route = routes.get(route_ref, {})
route_attrs = route.get("attributes", {})
# Parse departure time
dep_str = attrs.get("departure_time") or attrs.get("arrival_time")
dep_dt = parse_iso8601(dep_str)
if not dep_dt:
continue
delta = dep_dt - now
delta_min = delta.total_seconds() / 60.0
# Skip past departures
if delta_min < -1:
continue
headsign = trip_attrs.get("headsign") or attrs.get("headsign", "")
results.append({
"route": route_ref or "Unknown",
"route_name": route_attrs.get("long_name", route_ref),
"route_color": route_attrs.get("color", ""),
"headsign": headsign,
"departure_time": dep_dt.astimezone().strftime("%H:%M"),
"minutes": round(delta_min),
"minutes_display": format_minutes(delta_min),
"status": attrs.get("status"),
"direction_id": attrs.get("direction_id"),
})
# Sort by minutes and limit
results.sort(key=lambda x: x["minutes"])
return results[:limit]
def search_stops(query: str, limit: int = 10) -> list[dict]:
"""Search for stops by name. Searches stations first, then bus stops."""
results = []
query_lower = query.lower()
# First search stations (location_type=1) - these are the main transit hubs
for location_type in ["1", "0"]:
params = {
"filter[location_type]": location_type,
"page[limit]": 1000,
}
data = api_get("stops", params)
for stop in data.get("data", []):
attrs = stop.get("attributes", {})
name = attrs.get("name", "")
if query_lower in name.lower():
# Skip duplicates
if any(r["id"] == stop["id"] for r in results):
continue
results.append({
"id": stop["id"],
"name": name,
"description": attrs.get("description", ""),
"municipality": attrs.get("municipality", ""),
"wheelchair_accessible": attrs.get("wheelchair_boarding") == 1,
"is_station": location_type == "1",
})
# If we have enough results from stations, don't search bus stops
if len(results) >= limit:
break
# Sort by relevance (stations first, then exact match, starts with, contains)
def sort_key(s):
name_lower = s["name"].lower()
station_priority = 0 if s.get("is_station") else 1
if name_lower == query_lower:
return (station_priority, 0, name_lower)
elif name_lower.startswith(query_lower):
return (station_priority, 1, name_lower)
else:
return (station_priority, 2, name_lower)
results.sort(key=sort_key)
return results[:limit]
def get_routes(route_type: Optional[int] = None) -> list[dict]:
"""Get all routes, optionally filtered by type."""
params = {}
if route_type is not None:
params["filter[type]"] = str(route_type)
data = api_get("routes", params)
results = []
for route in data.get("data", []):
attrs = route.get("attributes", {})
results.append({
"id": route["id"],
"name": attrs.get("long_name", route["id"]),
"short_name": attrs.get("short_name", ""),
"type": ROUTE_TYPES.get(attrs.get("type"), "Unknown"),
"color": attrs.get("color", ""),
"description": attrs.get("description", ""),
})
return results
def get_alerts(route_id: Optional[str] = None) -> list[dict]:
"""Get active service alerts."""
params = {
"filter[activity]": "BOARD,EXIT,RIDE",
}
if route_id:
params["filter[route]"] = route_id
data = api_get("alerts", params)
results = []
for alert in data.get("data", []):
attrs = alert.get("attributes", {})
# Get affected routes
affected = []
for entity in attrs.get("informed_entity", []):
if "route" in entity:
affected.append(entity["route"])
results.append({
"id": alert["id"],
"header": attrs.get("header", ""),
"description": attrs.get("description", ""),
"severity": attrs.get("severity", ""),
"effect": attrs.get("effect", ""),
"affected_routes": list(set(affected)),
"url": attrs.get("url"),
})
return results
def load_config(config_path: str) -> dict:
"""Load configuration from YAML file."""
if not YAML_AVAILABLE:
print("Error: PyYAML required. Install with: pip install pyyaml", file=sys.stderr)
sys.exit(1)
path = Path(config_path)
if not path.exists():
print(f"Error: Config file not found: {config_path}", file=sys.stderr)
sys.exit(1)
with open(path) as f:
return yaml.safe_load(f)
def get_all_departures(config: dict) -> list[dict]:
"""Get departures for all configured panels/stops."""
results = []
for panel in config.get("panels", []):
panel_result = {
"title": panel.get("title", "Unknown"),
"walk_minutes": panel.get("walk_minutes", 5),
"services": [],
}
for service in panel.get("services", []):
predictions = get_predictions(
stop_id=service["stop_id"],
route_id=service.get("route_id"),
direction_id=service.get("direction_id"),
limit=service.get("limit", 3),
)
# Filter by headsign if specified
headsign_filter = service.get("headsign_contains", "").lower()
if headsign_filter:
predictions = [
p for p in predictions
if headsign_filter in p["headsign"].lower()
]
# Apply walk time filter
walk_min = panel.get("walk_minutes", 0)
predictions = [
p for p in predictions
if p["minutes"] >= walk_min - 1
]
# Mark warnings
for p in predictions:
p["warning"] = walk_min <= p["minutes"] < walk_min + 2
panel_result["services"].append({
"label": service.get("label", service.get("route_id", "Unknown")),
"destination": service.get("destination", ""),
"predictions": predictions[:3],
})
results.append(panel_result)
return results
def print_predictions(predictions: list[dict], title: str = None):
"""Pretty print predictions."""
if title:
print(f"\n🚇 {title}")
print("-" * 40)
if not predictions:
print(" No upcoming departures")
return
for p in predictions:
warning = "⚠️ " if p.get("warning") else ""
route = p["route"]
headsign = p["headsign"]
mins = p["minutes_display"]
time = p["departure_time"]
print(f" {warning}{route} → {headsign}")
print(f" {mins} (at {time})")
def cmd_next(args):
"""Handle 'next' command - quick departure lookup."""
if not args.stop:
print("Error: --stop is required", file=sys.stderr)
sys.exit(1)
predictions = get_predictions(
stop_id=args.stop,
route_id=args.route,
limit=args.limit,
)
if args.json:
print(json.dumps(predictions, indent=2))
else:
print_predictions(predictions, f"Departures from {args.stop}")
def cmd_departures(args):
"""Handle 'departures' command - all configured stops."""
config = load_config(args.config)
results = get_all_departures(config)
if args.json:
print(json.dumps(results, indent=2))
else:
for panel in results:
print(f"\n{'='*50}")
print(f"📍 {panel['title']} (walk: {panel['walk_minutes']} min)")
print("=" * 50)
for service in panel["services"]:
label = service["label"]
dest = service["destination"]
print(f"\n {label} {dest}")
if not service["predictions"]:
print(" No upcoming departures")
continue
for p in service["predictions"]:
warning = "⚠️ " if p.get("warning") else " "
print(f" {warning}{p['minutes_display']} (at {p['departure_time']})")
def cmd_stops(args):
"""Handle 'stops' command - search for stops."""
results = search_stops(args.search)
if args.json:
print(json.dumps(results, indent=2))
else:
print(f"\n🔍 Stops matching '{args.search}':")
print("-" * 40)
if not results:
print(" No stops found")
return
for stop in results:
access = "♿" if stop["wheelchair_accessible"] else ""
print(f" {stop['id']}: {stop['name']} {access}")
if stop["municipality"]:
print(f" ({stop['municipality']})")
def cmd_routes(args):
"""Handle 'routes' command - list routes."""
route_type = None
if args.type:
type_map = {
"rail": 1,
"subway": 1,
"light": 0,
"green": 0,
"bus": 3,
"commuter": 2,
"ferry": 4,
}
route_type = type_map.get(args.type.lower())
results = get_routes(route_type)
if args.json:
print(json.dumps(results, indent=2))
else:
print("\n🚇 MBTA Routes:")
print("-" * 40)
current_type = None
for route in results:
if route["type"] != current_type:
current_type = route["type"]
print(f"\n{current_type}:")
name = route["name"] or route["short_name"]
print(f" {route['id']}: {name}")
def cmd_alerts(args):
"""Handle 'alerts' command - service alerts."""
results = get_alerts(args.route)
if args.json:
print(json.dumps(results, indent=2))
else:
print("\n⚠️ Service Alerts:")
print("-" * 40)
if not results:
print(" No active alerts")
return
for alert in results:
routes = ", ".join(alert["affected_routes"][:3])
print(f"\n [{alert['severity']}] {routes}")
print(f" {alert['header']}")
if alert["effect"]:
print(f" Effect: {alert['effect']}")
def cmd_dashboard(args):
"""Handle 'dashboard' command - start web server."""
try:
from flask import Flask, render_template_string
except ImportError:
print("Error: Flask required for dashboard. Install with: pip install flask", file=sys.stderr)
sys.exit(1)
config = load_config(args.config)
app = Flask(__name__)
TEMPLATE = """
<!DOCTYPE html>
<html>
<head>
<title>MBTA Departures</title>
<meta http-equiv="refresh" content="30">
<style>
body { font-family: -apple-system, sans-serif; background: #1a1a2e; color: #eee; padding: 20px; }
.container { max-width: 1200px; margin: 0 auto; }
h1 { text-align: center; color: #fff; }
.panel { background: #16213e; border-radius: 10px; padding: 20px; margin: 20px 0; }
.panel-title { font-size: 1.3rem; margin-bottom: 15px; color: #e94560; }
.service { margin: 15px 0; padding: 10px; background: #0f3460; border-radius: 5px; }
.service-header { font-weight: bold; margin-bottom: 10px; }
.prediction { padding: 5px 0; display: flex; justify-content: space-between; }
.warning { color: #ffc107; }
.time { color: #888; }
.updated { text-align: center; color: #666; margin-top: 20px; }
</style>
</head>
<body>
<div class="container">
<h1>🚇 MBTA Departures</h1>
{% for panel in panels %}
<div class="panel">
<div class="panel-title">📍 {{ panel.title }} ({{ panel.walk_minutes }} min walk)</div>
{% for service in panel.services %}
<div class="service">
<div class="service-header">{{ service.label }} {{ service.destination }}</div>
{% for p in service.predictions %}
<div class="prediction {% if p.warning %}warning{% endif %}">
<span>{% if p.warning %}⚠️{% endif %} {{ p.headsign }}</span>
<span>{{ p.minutes_display }} <span class="time">({{ p.departure_time }})</span></span>
</div>
{% else %}
<div class="prediction">No upcoming departures</div>
{% endfor %}
</div>
{% endfor %}
</div>
{% endfor %}
<div class="updated">Updated: {{ updated }}</div>
</div>
</body>
</html>
"""
@app.route("/")
def index():
results = get_all_departures(config)
updated = datetime.now().strftime("%H:%M:%S")
return render_template_string(TEMPLATE, panels=results, updated=updated)
@app.route("/api/departures")
def api_departures():
results = get_all_departures(config)
return {"panels": results, "updated": datetime.now().isoformat()}
print(f"Starting dashboard at http://localhost:{args.port}")
app.run(host="0.0.0.0", port=args.port, debug=False)
def main():
parser = argparse.ArgumentParser(
description="MBTA Transit CLI - Real-time predictions",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=__doc__,
)
parser.add_argument("--json", action="store_true", help="Output as JSON")
subparsers = parser.add_subparsers(dest="command", help="Commands")
# next command
next_parser = subparsers.add_parser("next", help="Get next departures from a stop")
next_parser.add_argument("--stop", "-s", required=True, help="Stop ID")
next_parser.add_argument("--route", "-r", help="Filter by route ID")
next_parser.add_argument("--limit", "-l", type=int, default=5, help="Number of results")
# departures command
dep_parser = subparsers.add_parser("departures", help="Get departures for all configured stops")
dep_parser.add_argument("--config", "-c", default="config.yaml", help="Config file path")
# stops command
stops_parser = subparsers.add_parser("stops", help="Search for stops")
stops_parser.add_argument("--search", "-s", required=True, help="Search query")
# routes command
routes_parser = subparsers.add_parser("routes", help="List routes")
routes_parser.add_argument("--type", "-t", help="Filter by type (rail, bus, commuter, ferry)")
# alerts command
alerts_parser = subparsers.add_parser("alerts", help="Get service alerts")
alerts_parser.add_argument("--route", "-r", help="Filter by route ID")
# dashboard command
dash_parser = subparsers.add_parser("dashboard", help="Start web dashboard")
dash_parser.add_argument("--config", "-c", default="config.yaml", help="Config file path")
dash_parser.add_argument("--port", "-p", type=int, default=6639, help="Port number")
args = parser.parse_args()
if not args.command:
parser.print_help()
sys.exit(1)
commands = {
"next": cmd_next,
"departures": cmd_departures,
"stops": cmd_stops,
"routes": cmd_routes,
"alerts": cmd_alerts,
"dashboard": cmd_dashboard,
}
commands[args.command](args)
if __name__ == "__main__":
main()