RailRoute journey planner

Turn what somebody typed into RailRoute place ids. ALWAYS call this before plan_journey. A place is a city with all of its stations and airports — Mumbai covers CSMT, LTT, Dadar, Bandra Terminus and the airport — so the planner can choose the right terminal rather than making the traveller do it. Typing a station code ("CSMT") finds the city and says which terminal matched.

Every practical way to get from one place to another: direct trains with their fares per class, journeys with one change of train, flights, mixed train-and-flight itineraries, and GOVERNMENT BUSES from the state road transport corporations, priced from their own reservation systems. This is the whole answer in one call. Place ids come from find_place. Use it for bus questions too. On a large share of the corridors these corporations serve there is no through train at all — Mysuru to Mangaluru runs twenty-five buses a day and not one direct train — so a journey this tool answers with a bus is often the only through service that exists, not a second-best. Pass `train_class` when the traveller has named one ("3A", "sleeper") and every train is priced in it; leave it out and each train is priced in every class we have evidence it carries. Pass `modes: "trains_only"` when they have said train — do not ask them to choose otherwise, because the point of this planner is that they do not have to. Pass `arrive_by: true` when they named a time they must BE somewhere rather than a time they want to leave.

Live seat availability per class for one train on one date, plus every other way to book it when the through ticket will not confirm: a split at an intermediate station, boarding earlier, alighting later. This is the tool that rescues a waitlisted train. It spends a metered upstream call, so ask it about trains the traveller is actually considering rather than sweeping a list.

Every stop of one train with its scheduled arrival and departure, in order. Scheduled times only — this says nothing about where the train is today.

Every train scheduled to call at a station, in departure order — the enquiry board, not a journey plan. Use plan_journey when somebody wants to get somewhere; use this when they are asking what leaves from here. Scheduled times only.

Day-by-day service over a span of dates for a station pair: which days have a direct train and which have none, plus the weekly pattern. Use this when somebody is flexible about when they travel, or asks 'does it run on Sundays'. Timetable only — it says nothing about seats.

Other railway stations within a radius of one station, nearest first. Useful when a place has no service of its own and the traveller needs to know what is reachable — the planner already does this internally, so reach for it only when somebody asks the question directly.

Search forward up to a month for the first date this route can actually be travelled with a confirmed berth — direct trains and one-change journeys together. Use it when a traveller is flexible about WHEN and the date they asked for is waitlisted. EXPENSIVE: it checks seats across dozens of trains and dates, so it is limited to a few calls an hour; for a single date use check_train_options instead.