# SPTrans Olho Vivo MCP > SPTrans Olho Vivo connects your AI agent to São Paulo's public transit system data. It lets you track buses in real time—get precise GPS coordinates, check arrival forecasts at any stop or along a line, and look up entire bus networks using structured queries. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** public-transit, real-time-tracking, gps-data, urban-mobility, api-integration, transit-forecast ## Description Connect this server and you'll give your AI agent access to São Paulo’s real-time transit data. You can ask it anything about the city bus network—getting live positions, predicting arrivals, or mapping out specific routes—without switching apps or digging through documentation. **Live Vehicle Tracking** Your agent uses this server to track buses in motion. You can call `get_all_positions` to pull the current GPS coordinates for every active bus across the entire São Paulo network. If you need a tighter focus, `get_positions_by_line` lets you get real-time coordinates only for buses running on one specific route. For vehicles that aren't moving but are parked or waiting in a terminal garage, use `get_positions_in_garage`. **Predicting Bus Arrivals** Need to know when the next bus hits? You can run predictions using several tools. Call `get_forecast` to get arrival times for a specific stop and a given line. If you want to see what's coming into one spot, regardless of the line, use `get_forecast_by_stop`. For full route planning, `get_forecast_by_line` calculates predicted arrivals across every single stop on a defined route. **Finding Network Elements** The server helps you map out the entire system. You can find specific bus lines by name or number using `search_lines`, or narrow that down further by direction of travel with `search_lines_by_direction`. If you're looking for a stop, use `search_stops` to locate it via its name or physical address. To see every stop associated with one line, run `search_stops_by_line`; if you want all stops within a specific transit corridor, use `search_stops_by_corridor`. You can also list the operating companies involved in the area by calling `list_companies`, and review the city's defined intelligent bus corridors and their boundaries using `list_corridors`. **Comprehensive Data Discovery** Your agent processes this data through multiple steps. If you start by searching for a stop, say using `search_stops`, your AI client can then take that result and pass it directly into `get_forecast_by_stop`. To get the current picture of every bus running in town, the system runs `get_all_positions`; if you only care about one line's status, it uses `get_positions_by_line`. **The Flow In Action** When your agent needs to know what lines are available, it can first use `search_lines`, and then pass that information along with a stop ID found via `search_stops` to calculate expected arrivals using `get_forecast`. The server handles all the structured queries, delivering concrete answers about arrival times or vehicle locations. You don't have to manage any of this complexity; just ask your agent, and it uses these tools to get you the answer. ## Tools ### get_forecast_by_line Calculates predicted arrival times for all stops along one specified route. ### get_forecast_by_stop Lists predicted arrivals from all lines heading to a specific stop code. ### get_forecast Provides arrival predictions for a specific stop and a given bus line. ### get_positions_by_line Gets the real-time GPS coordinates for every bus currently running on a single defined line. ### get_positions_in_garage Retrieves the current GPS location of buses that are parked or waiting in a terminal garage. ### get_all_positions Retrieves the current GPS coordinates for every single active bus in the São Paulo network. ### list_companies Lists all operating companies involved in São Paulo's bus transit network by area. ### list_corridors Returns a list of the city’s official intelligent bus corridors and their boundaries. ### search_lines_by_direction Searches for bus lines, applying a filter based on their general direction of travel. ### search_lines Finds existing bus lines using either a name or a route number for filtering. ### search_stops_by_corridor Lists all known stops that fall within a specified intelligent transit corridor. ### search_stops_by_line Returns every stop location associated with a specific bus line number or name. ### search_stops Locates specific bus stops by entering the name or the physical address of the stop. ## Prompt Examples **Prompt:** ``` Search for bus lines related to 'Lapa'. ``` **Response:** ``` I found several lines for 'Lapa', including line 8000-10 (Terminal Lapa) with code 33657. Would you like to see the current bus positions for this line? ``` **Prompt:** ``` What are the arrival forecasts for stop code 650005666? ``` **Response:** ``` For stop 650005666, the next bus on line 8000-10 is expected in 5 minutes. There is also a bus for line 8615-10 arriving in 12 minutes. ``` **Prompt:** ``` Show me the real-time positions of buses on line 33657. ``` **Response:** ``` There are currently 4 buses active on line 33657. Two are near Terminal Lapa, one is on Rua Clélia, and one is approaching the city center. ``` ## Capabilities ### Track Live Fleet Positions Get real-time GPS coordinates for all buses, or filter the data to show only vehicles on a specific bus line. ### Predict Bus Arrivals Retrieve estimated arrival times for lines at a single stop, or get a forecast of arrivals across an entire route. ### Discover Network Elements Search for bus lines by name/number, find specific stops using addresses, and list operating companies in the area. ### Monitor Garage Status Check the live GPS location of buses that are currently parked or undergoing maintenance at a terminal garage. ### Map Transit Corridors List and search through the city's defined intelligent bus corridors to understand network geography. ## Use Cases ### Commuter needs immediate route info A commuter is standing at an unknown stop. They tell their agent: 'What's coming to me?' The agent uses `search_stops` with the address, gets the stop ID, and immediately runs `get_forecast_by_stop`. The result tells them which lines and when they arrive. ### Planner needs fleet density data A researcher wants to know how many buses are currently active on Line 33657. They instruct the agent: 'Show me all positions for line 33657.' The agent uses `get_positions_by_line` and returns a count of active vehicles, helping analyze peak usage. ### Developer needs to build a widget A developer's app needs to show all major routes in an area. They ask the agent: 'List all intelligent corridors.' The agent executes `list_corridors`, providing the foundational boundaries necessary for their map visualization layer. ### User checks a specific destination A user is planning a trip to Terminal Lapa. They ask: 'What lines go there?' The agent uses `search_stops` and then runs `search_lines_by_direction` using the resulting stop data, giving them all relevant options. ## Benefits - Pinpoint exact bus locations right now. Use `get_all_positions` to see the entire fleet's movement or use `get_positions_by_line` to track a single route in real time. - Get immediate arrival predictions without guessing. Ask for forecasts at your stop using `get_forecast_by_stop`, which checks multiple lines arriving there. - Map the whole system quickly. You can find out what buses run through an area by using `list_corridors` or finding stops via `search_stops`. - Understand network structure instantly. Use `list_companies` to see who operates in a sector, and use `list_corridors` to map the major transit paths. - Save time on searches. Instead of manually checking routes, ask your agent to find all stops for a line using `search_stops_by_line`. ## How It Works The bottom line is you get live operational data from São Paulo's bus network without writing any code or running complex database joins yourself. 1. First, subscribe to the SPTrans Olho Vivo server and provide your required API Token. 2. Next, tell your AI agent what you need—for example, 'Find all buses near Paulista Avenue.' 3. The agent runs the necessary sequence of tools (like `search_stops` then `get_positions_by_line`) and delivers the final answer in plain text. ## Frequently Asked Questions **How do I find the bus stops needed for get_forecast_by_stop?** You must use `search_stops` first to locate a stop by name or address. This tool returns the unique stop ID, which you then pass into `get_forecast_by_stop`. **What is the difference between get_all_positions and get_positions_by_line?** `get_all_positions` gives you coordinates for every single bus on the whole network. `get_positions_by_line` limits that view, giving you GPS data only for buses running on one specific line. **Can I use search_lines to find a route by direction?** Yes, you can narrow down results using `search_lines_by_direction`. This is better than just using `search_lines` if you know the general way the bus is heading. **What data does list_corridors provide?** `list_corridors` provides a list of the city's official intelligent corridors. You can then use `search_stops_by_corridor` to find all stops within that specific boundary. **When should I use `get_positions_in_garage` instead of tracking active buses?** Use this tool for vehicles that aren't running routes. It tracks the real-time location of buses parked in a garage, specific to certain companies or lines. This is useful when you need to check fleet availability before service hours. **If my search using `search_lines` returns no data, how should my agent handle it?** The server will return a structured empty list and an HTTP 200 status code. Your AI client must check for null or empty arrays in the response body rather than waiting for a hard error message. **What are the recommended rate limits when calling `get_forecast` repeatedly?** We recommend implementing a backoff strategy if you poll frequently. While we don't list specific limits, continuous high-volume requests risk throttling; always check Vinkius documentation for current usage tiers. **What data points are available when I call `list_companies`?** The tool returns a structured list of operating companies. Each entry includes the company's official name, its associated area code, and general operational status information for filtering. **How do I find the specific code for a bus line?** Use the `search_lines` tool with the line number or name (e.g., '8000' or 'Lapa'). The agent will return the line code (`cl`), which is required for tracking positions or forecasts. **Can I see the arrival times for all buses at a particular stop?** Yes! Use the `get_forecast_by_stop` tool with the stop code (`cp`). It will list all upcoming bus arrivals for that location in real-time. **Is it possible to track the live location of buses on a map?** While the MCP returns raw coordinates, you can use `get_positions_by_line` to get the latitude and longitude of every active bus on a line, which your AI can then describe or plot.