canonical: https://jentic.com/apis/ptv.vic.gov.au/ptv-vic # Ptv Vic PTV Timetable API - Version 3 The PTV Timetable API returns Public Transport Victoria's scheduled and real-time departures, routes, stops, and service runs for metropolitan and regional train, tram, and bus services across Victoria, including Night Network. It finds stops and myki ticket outlets near a latitude and longitude or by search term, reports current and planned disruptions by route or stop, and estimates fares between myki zones. Train timetable data is updated daily and the remaining data weekly, and it is the same API PTV uses for its own apps. ## For AI agents Look up departures from a Victorian train, tram, or bus stop, find stops and myki outlets near a location, read current or planned disruptions, and estimate a fare between zones. Covers metropolitan and regional services, including real-time data where PTV publishes it. ## Scope Does not handle journey planning between two addresses, ticket purchase, or myki card top-ups. Use for Victorian public transport departures, stops, disruptions, and fare estimates only. ## Capabilities - Get upcoming departures from a stop for every route or one route, with direction_id, max_results, include_cancelled, and look_backwards options - Find stops and myki ticket outlets near a latitude and longitude within a max_distance - Search stops, routes, and outlets by a search term, optionally matching by suburb or GTFS stop id - List current or planned disruptions for all route types, one route, one stop, or a route and stop together - Trace a service run's stopping pattern, including skipped stops and vehicle position when Run is expanded - Estimate a myki fare between a minimum and maximum zone, including free tram zone journeys - Read stop facilities such as amenities, accessibility, staffing, and ticketing at Metro and V/Line stations ## Use cases ### Agent answers for Victorian commuters An AI assistant asked when the next service leaves can search the PTV Timetable API for the stop by name, then call the departures operation for that stop and route type to return the next few services, with the Run expanded to include vehicle position where PTV publishes real-time data. A follow-up disruption lookup for the same stop lets the agent warn about delays in the same answer. Example prompt: Search for 'Flinders Street', take the returned train stop_id, then get departures for route_type 0 at that stop with max_results 5 and expand Run ### Disruption alerts for a route Apps and bots that notify riders filter disruptions by route or stop and by disruption_status of current or planned. The disruption modes operation lists the categories in use, and a single disruption can be fetched by id for its full detail, so an alert service can post a change only once. Example prompt: Get disruptions for route_id 6 with disruption_status current and summarise each one by title and affected stops ### Nearby stops and ticket outlets Location-aware apps call the stops-by-geolocation operation with a latitude, longitude, route_types filter, and max_distance to list the closest stops, and the outlets-by-geolocation operation to find where to buy or top up a myki card. Stop details then return station facilities such as accessibility and staffing for Metro and V/Line stations. Example prompt: List stops near latitude -37.8183 and longitude 144.9671 with route_types 1 and max_distance 400, then fetch stop_accessibility details for the closest one ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v3/departures/route_type/{route_type}/stop/{stop_id}` | Departures for all routes from a stop | | GET | `/v3/stops/location/{latitude},{longitude}` | Stops near a location | | GET | `/v3/search/{search_term}` | Search stops, routes, and outlets | | GET | `/v3/disruptions` | Disruptions for all route types | | GET | `/v3/disruptions/route/{route_id}` | Disruptions for a route | | GET | `/v3/pattern/run/{run_ref}/route_type/{route_type}` | Stopping pattern for a service run | | GET | `/v3/fare_estimate/min_zone/{minZone}/max_zone/{maxZone}` | Estimate a fare by zone | | GET | `/v3/outlets/location/{latitude},{longitude}` | Ticket outlets near a location | ## Key resources - **Departures** — Scheduled and real-time departures from a stop, optionally for one route - **Stops** — Stops by location or route, with facilities for Metro and V/Line stations - **Routes and directions** — Route names, numbers, route types, and directions of travel - **Runs and patterns** — Individual service runs and their stopping patterns - **Disruptions** — Current and planned disruptions by route, stop, or id - **Outlets and fares** — myki ticket outlets and zone-based fare estimates ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 58 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 99 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 29 / 100 - Agent Usability: 94 / 100 - Security: 100 / 100 - AI Discoverability: 100 / 100 - **View full report:** https://jentic.com/apis/ptv.vic.gov.au/ptv-vic/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the PTV Timetable API by hand means registering a developer id, computing the request signature PTV's docs describe, and threading route_type, stop_id, and run_ref between calls. Through Jentic you install once, import the PTV Timetable API from the API Directory, and your agent finds each operation by intent with its parameters already described. - **Permission scoping:** The PTV Timetable API puts the stop id, route id, and run reference in the URL path (`/v3/departures/route_type/{route_type}/stop/{stop_id}`), so a rule can pin your agent to one stop or one route and the operations you pick. Every operation in this spec is a read, and you decide which lookups the agent may call. - **Credential handling:** The spec declares no security scheme, and the devid and signature values travel as ordinary query parameters. Any secret you do keep in your own Jentic One instance is held encrypted, injected at execution time, and never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'next departures from a stop' or 'current disruptions on a route', and Jentic returns the matching PTV operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Transport for NSW Open Data API** — Transport for NSW publishes real-time and scheduled transit data for New South Wales. - **MBTA V3 API** — The MBTA V3 API covers predictions, routes, and alerts for Boston-area transit. - **MapTiler Cloud API** — MapTiler renders maps and geocodes addresses to coordinates. ## FAQ ### What authentication does the PTV Timetable API use? The PTV Timetable API OpenAPI spec declares no security scheme. Instead, its operations accept devid and signature query parameters, described as your developer id and the authentication signature for the request. PTV's website explains how to register for a developer id and calculate the signature, so check those instructions before calling the live API. ### Can I get real-time departures with the PTV Timetable API? Yes, where PTV makes real-time data available for metropolitan train, tram, and bus services. GET `/v3/departures/route_type/{route_type}/stop/{stop_id}` returns departures for a stop, and expanding Run with the expand parameter adds VehiclePosition and VehicleDescriptor information. ### What are the rate limits for the PTV Timetable API? The OpenAPI spec does not specify rate limits for the PTV Timetable API. Check PTV's API FAQ at http://ptv.vic.gov.au/apifaq for current usage terms. ### How do I find stops near a location with the PTV Timetable API through Jentic? Search Jentic for 'find stops near a location', which returns GET `/v3/stops/location/{latitude}`,{longitude} with its input schema, then pass the coordinates with optional route_types, max_results, and max_distance filters. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Is there a PTV Timetable MCP server? You don't need an MCP server to give your agent the PTV Timetable API. Jentic connects it directly from the API Directory: import it and your agent calls its operations, which it finds on demand by intent rather than loading every tool definition into its context. ### Can I limit what my agent is allowed to do with the PTV Timetable API? Yes. Write a rule that allows only the departures and disruptions operations, and pin the departures path to one stop id such as `/v3/departures/route_type/0/stop/1071`, so a commuter bot answers for its home station and nothing wider, and every call it makes is logged.