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.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 80,
      "description": "A city, station name or station code"
    },
    "limit": {
      "default": 5,
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "minLength": 2,
      "maxLength": 80,
      "description": "Place id from find_place"
    },
    "to": {
      "type": "string",
      "minLength": 2,
      "maxLength": 80,
      "description": "Place id from find_place"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Travel date in IST. Today is allowed; the past is refused."
    },
    "arrive_by": {
      "default": false,
      "description": "When true, `date` is the day they must ARRIVE, and journeys may depart the day before.",
      "type": "boolean"
    },
    "quota": {
      "default": "GN",
      "type": "string",
      "enum": [
        "GN",
        "TQ",
        "PT",
        "LD",
        "SS"
      ]
    },
    "modes": {
      "default": "any",
      "description": "Restrict the answer. Default 'any' ranks trains, flights and government buses together — leave it out unless the traveller has actually named a mode. 'trains_only' and 'flights_only' both drop the buses.",
      "type": "string",
      "enum": [
        "any",
        "trains_only",
        "flights_only"
      ]
    },
    "train_class": {
      "description": "Price every train in this class: 2S Second Sitting, SL Sleeper, CC AC Chair Car, 3E AC 3 Economy, 3A AC 3 Tier, 2A AC 2 Tier, 1A First AC, EC Executive Chair Car. Omit to price each train in every class we know it carries.",
      "type": "string",
      "enum": [
        "2S",
        "SL",
        "CC",
        "3E",
        "3A",
        "2A",
        "1A",
        "EC"
      ]
    },
    "include_connections": {
      "default": "auto",
      "description": "Journeys with one change of train. 'auto' searches for them when direct trains are thin, which is when they matter; 'always' searches regardless and costs a few more seconds.",
      "type": "string",
      "enum": [
        "auto",
        "always",
        "never"
      ]
    },
    "ask_preferences": {
      "default": true,
      "description": "Whether to ask the traveller for a travel class when they have not named one. Set false for automated or bulk use.",
      "type": "boolean"
    },
    "limit": {
      "default": 8,
      "description": "How many of EACH kind to return. Raise it only if the traveller asks to see more.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "from",
    "to",
    "date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "train_number": {
      "type": "string",
      "pattern": "^\\d{4,6}$"
    },
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12,
      "description": "Station code the traveller boards at"
    },
    "to": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12,
      "description": "Station code the traveller alights at"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "quota": {
      "default": "GN",
      "type": "string",
      "enum": [
        "GN",
        "TQ",
        "PT",
        "LD",
        "SS"
      ]
    },
    "include_rac": {
      "default": true,
      "description": "RAC is a ticket that carries a right to board, so it counts as bookable by default.",
      "type": "boolean"
    }
  },
  "required": [
    "train_number",
    "from",
    "to",
    "date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "train_number": {
      "type": "string",
      "pattern": "^\\d{4,6}$"
    }
  },
  "required": [
    "train_number"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "station_code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12,
      "description": "Station code, e.g. CNB"
    },
    "after": {
      "description": "Only departures at or after this IST clock time, HH:MM",
      "type": "string",
      "pattern": "^\\d{2}:\\d{2}$"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "station_code"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12,
      "description": "Origin station code"
    },
    "to": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12,
      "description": "Destination station code"
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day of the span"
    },
    "days": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 120
    }
  },
  "required": [
    "from",
    "to",
    "start_date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "station_code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12
    },
    "radius_km": {
      "default": 40,
      "type": "integer",
      "minimum": 1,
      "maximum": 150
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 40
    }
  },
  "required": [
    "station_code"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12,
      "description": "Origin station code"
    },
    "to": {
      "type": "string",
      "minLength": 1,
      "maxLength": 12,
      "description": "Destination station code"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The date to search forward FROM"
    },
    "quota": {
      "default": "GN",
      "type": "string",
      "enum": [
        "GN",
        "TQ",
        "PT",
        "LD",
        "SS"
      ]
    }
  },
  "required": [
    "from",
    "to",
    "date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}