Find Carris Metropolitana bus stops by name and/or near a coordinate.

Use this first whenever the user names a place, street, station or gives a location, to get the stop_id needed by next_arrivals. Results include the lines serving each stop.

Args: query: Text to match in the stop name (accent/case-insensitive, all words must match), e.g. "Gare do Oriente", "Cacilhas terminal". A 6-digit stop id also works. lat, lon: A coordinate (WGS84). Results are sorted by straight-line distance from it. Note: buses inside Lisbon city are mostly run by Carris (a different company, not covered here); Carris Metropolitana serves the wider region. radius_m: Only stops within this many metres of lat/lon. Default 500 when no query is given; unlimited when a query is given. limit: Max stops to return (default 10, max 50).

Upcoming buses at a Carris Metropolitana stop, real-time where available.

Use for "when is the next bus at X?" (get stop_id from find_stops first). Each arrival says whether it is "realtime" (live GPS estimate) or "scheduled" (timetable only: the bus may not have started its trip yet). minutes_from_now uses the real-time estimate when present. Times are Europe/Lisbon. Only today's operational day is covered, so late at night the list may be short or empty.

Args: stop_id: 6-digit stop id, e.g. "060361". line_id: Optional 4-digit line number to keep only that line, e.g. "2794". limit: Max arrivals to return (default 10, max 50).

Details of a Carris Metropolitana line: name, route ends, directions, municipalities.

Use for "where does line 4715 go?", "which bus goes from Cacilhas to Almada?", or to check whether a line passes a stop (include_stops=True). If line is not an exact line number it is treated as text (e.g. "Oriente Setubal") and the matching lines are listed instead. trips_today = 0 means the line does not run today (some lines are seasonal or weekday-only). Departure times past midnight are written "24:30", "25:10" (same service day).

Args: line: 4-digit line number ("4715") or free text matched against line names. include_stops: Also list every stop (id + name) in order for each direction.

Service alerts (detours, works, strikes, stops not served) for Carris Metropolitana.

Use before recommending a trip, or when the user asks "is line X disrupted?". Filter by line and/or stop; with no filter, returns all current alerts (there are often ~100). Alerts are mostly published in Portuguese only.

Args: line_id: 4-digit line number, e.g. "4407". stop_id: 6-digit stop id, e.g. "160584". include_upcoming: Also return alerts that start in the future (default True). language: Preferred language ("pt" or "en"); falls back to what exists. limit: Max alerts to return (default 20, max 100).

Live GPS positions of the buses currently running on a Carris Metropolitana line.

Use for "where is the 3508 right now?" or to see how many buses are out on a line. Each vehicle includes its position, heading, speed, the stop it is at / heading to, and how many seconds old the fix is.

Args: line_id: 4-digit line number, e.g. "3508".