Mavplusz APImavplusz.hu ↗
Get real-time and scheduled departure data from Hungarian public transit stops via the MÁV+ system. Includes times, platforms, delays, and destinations.
What is the Mavplusz API?
The MÁV+ API provides departure data from Hungarian public transit stops through a single get_departures endpoint that returns up to 9 fields per departure, including scheduled and real-time times, delay in minutes, destination, line number, platform, and route name. It covers stops across Hungary identifiable by their GTFS stop IDs, and results are sorted chronologically by departure time.
curl -X GET 'https://api.parse.bot/scraper/c6edf73a-1844-4a91-88a1-a7c28f365698/get_departures?stop_id=SOM%3Ahkir%7Chkir_101357_99&time_range=3600&max_departures=10' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace mavplusz-hu-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""MÁV+ Hungarian Transit: fetch departures, inspect real-time delays."""
from parse_apis.máv__hungarian_transit_departures_api import MavPlusz, StopNotFound
client = MavPlusz()
# Construct a stop by its GTFS ID and fetch its departures (next 2 hours).
stop = client.stop(id="SOM:hkir|hkir_101357_99").refresh(time_range=7200)
print(f"Stop: {stop.name} ({stop.total_departures} departures)")
# Walk the first few departures — limit iteration with a slice.
for dep in stop.departures[:5]:
print(dep.departure_time, dep.destination, dep.line_number, dep.mode)
# Typed error handling: attempt to fetch a non-existent stop.
try:
bad = client.stop(id="FAKE:nonexistent|stop_000000_00").refresh()
except StopNotFound as exc:
print(f"Stop not found: {exc.stop_id}")
print("exercised: stop.refresh / departure field access / StopNotFound error")
Get all departures from a Hungarian transit stop. Returns departure time, destination, line number, track/platform, route name, and real-time information when available. Results are sorted by departure time. Each stop is identified by its GTFS ID. The time_range parameter controls how far into the future to look, and max_departures limits results per route pattern.
| Param | Type | Description |
|---|---|---|
| stop_id | string | The GTFS stop ID for the transit stop (e.g. 'SOM:hkir|hkir_101357_99' for Gyöngyös bus station, 'BUD:keleti|keleti_100001_99' for Budapest Keleti). |
| time_range | integer | Time range in seconds from now to fetch departures. Default is 86400 (24 hours). |
| max_departures | integer | Maximum number of departures per route pattern to return. |
{
"type": "object",
"fields": {
"stop_id": "string - GTFS stop identifier",
"stop_name": "string - Human-readable stop name",
"departures": "array of departure objects sorted by time, each containing departure_time, realtime_departure, delay_minutes, is_realtime, destination, line_number, route_name, trip_name, track, mode, route_color",
"total_departures": "integer - Total number of departures found"
},
"sample": {
"data": {
"stop_id": "SOM:hkir|hkir_101357_99",
"stop_name": "Gyöngyös, autóbusz-állomás",
"departures": [
{
"mode": "COACH",
"track": "9",
"trip_name": "3693/13",
"route_name": "Gyöngyös - Visonta - MVM Mátra Energia Zrt.",
"destination": "MVM Mátra Energia Zrt.",
"is_realtime": false,
"line_number": "3693",
"route_color": "F6AC00",
"delay_minutes": 0,
"departure_time": "08:40",
"realtime_departure": null
}
],
"total_departures": 49
},
"status": "success"
}
}About the Mavplusz API
What the API Returns
The get_departures endpoint accepts a stop_id parameter using the GTFS stop identifier format (e.g. SOM:hkir|hkir_101357_99 for the Gyöngyös bus station). Each response includes the stop's human-readable stop_name, a total_departures count, and a departures array. Every entry in that array carries departure_time (scheduled), realtime_departure (when available), delay_minutes, is_realtime flag, destination, line number, platform/track, and route name.
Filtering and Time Range
The time_range parameter controls how far ahead departures are fetched, defaulting to 86400 seconds (24 hours). You can narrow this to the next 30 or 60 minutes by passing a smaller integer. The max_departures parameter caps the number of departures returned per route pattern, which is useful when querying busy interchange stops that serve many lines.
GTFS Stop IDs
Stop IDs follow the GTFS format used by Hungarian transit operators under the MÁV+ network. Both rail and bus stops are addressable. You need the correct GTFS ID for the stop you are querying — for example, BUD:keleti for Budapest Keleti railway station. The stop_id field in the response echoes back the identifier you supplied, which is useful for request verification when querying multiple stops in parallel.
The Mavplusz API is a managed, monitored endpoint for mavplusz.hu — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when mavplusz.hu changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official mavplusz.hu API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display live departure boards for Hungarian bus and rail stations in a travel app
- Alert commuters when a departure has a non-zero
delay_minutesvalue on their regular route - Aggregate platform/track assignments across a multi-platform station for wayfinding displays
- Build a journey-planning tool that queries successive stops along a Hungarian rail corridor
- Monitor on-time performance by comparing
departure_timeandrealtime_departureover time - Filter departures to a specific destination to show the next available service
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does MÁV+ have an official developer API?+
What does the `is_realtime` field indicate, and when is it false?+
is_realtime is true, the response includes a live realtime_departure time and a computed delay_minutes value. When it is false, only the scheduled departure_time is available and delay_minutes will be null or zero. Real-time availability depends on whether the individual service is actively reporting live data to the MÁV+ system.Does the API support trip planning between two stops, or return intermediate stops along a route?+
How do I find the correct GTFS stop ID for a Hungarian station?+
SOM:hkir|hkir_101357_99 (Gyöngyös bus station) or BUD:keleti (Budapest Keleti). These IDs correspond to entries in the GTFS feed published by Hungarian transit operators. The mavplusz.hu web URL for a stop also contains the stop ID after /stop/, which can be used directly as the stop_id parameter.