Search buses
search_busesSearches live Paytm bus routes and shows an interactive results card (operator, bus type, timings, rating, seats left, price). One-way, domestic, search only -- no seat selection or booking happens in chat. REQUIRED ARGS (same posture as search_flights): source, destination, and date are ALL mandatory. source/destination are free-text city names (e.g. 'Bengaluru', 'Hyderabad'); date is YYYY-MM-DD. There is no default date. The search runs for a date the traveller gave; a relative date they actually said ('tomorrow', 'next Friday') resolves to YYYY-MM-DD. When the date, source or destination is missing, the request is incomplete and the missing value comes from the traveller: a guessed today, tomorrow or weekend searches a day they did not ask for. With all three present, the traveller sees results only once the search runs. CITY DISAMBIGUATION: many Indian city names are ambiguous (e.g. 'Aurangabad' matches cities in Maharashtra, Bihar, Uttar Pradesh and West Bengal). An ambiguous name returns needsDisambiguation=true with sourceCityOptions / destinationCityOptions instead of a guess; the traveller picks one, and the search runs again with the chosen source_city_id / destination_city_id plus the original free-text source/destination. Filters: bus_type is 'AC' or 'Non-AC' when the traveller only named climate ('ac buses', 'non ac'), and a full type ('AC Sleeper', 'AC Semi-Sleeper', 'AC Seater', 'Non-AC Sleeper', 'Non-AC Semi-Sleeper', 'Non-AC Seater') only when they named a berth; a berth they did not name narrows the search wrongly. time_slot (early_morning 00:00-06:00, morning 06:00-12:00, afternoon 12:00-18:00, evening 18:00-24:00; no night slot), depart_after/depart_before (an hour or "HH:MM"; depart_before is exclusive, so 4-7 AM is 04:00 to 07:00, not 08:00). A window that crosses midnight is not one call. operators (list of operator names), max_price, min_rating, paytm_assured, boarding_point (matches by area name across all boarding points). Sort: recommended (default) | cheapest | fastest | earliest | rating. Invalid filter values are rejected with an error rather than silently ignored. Ratings below 15 reviews are not shown -- a missing rating means 'not enough reviews yet', not a bad bus. Named filters are sent to the Paytm wrapper (e.g. AC → is_ac) and the matching buses are shown. When those filters match nothing, the result says so; dropping the filters is the traveller's call, since an unfiltered search opens a second results card for the same query. Refining the search (only AC, cheaper, leaving after 9pm, better rated, etc.) is a new search with the changed filters and the same route and date, answered with new results rather than a pointer to the widget's chips. This tool lists a per-trip Paytm Checkin seat-layout URL as the dweb booking link (bookingUrl) and a matching seat deeplink for mweb/app (bookingDeeplink) -- there is no in-chat seat selection or payment; the traveller completes booking on Paytm Checkin. Questions about amenities, boarding/dropping points, or cancellation for a specific bus (or a tap on a card) are answered by get_bus_details with that card's tripRef, without a new search.
AI CARD SUMMARIES: the bus-search widget loads its one-line AI summaries itself (skeleton footers, then text or remove), so the results card is complete without another tool. Amenities and ratings come only from Paytm's data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Travel date as YYYY-MM-DD. Mandatory — do not invent a date if the traveller omitted it; ask them first. | |
| source | Yes | Departure city name, e.g. "Bengaluru". | |
| sort_by | No | recommended | cheapest | fastest | earliest | rating. | recommended |
| bus_type | No | "AC" or "Non-AC" when the traveller only named climate, or a full type ("AC Sleeper", "AC Semi-Sleeper", "AC Seater", "Non-AC Sleeper", "Non-AC Semi-Sleeper", "Non-AC Seater"). | |
| max_price | No | Budget cap in INR (per traveller, starting fare). | |
| operators | No | Restrict to these operator names. | |
| time_slot | No | early_morning [00:00, 06:00) | morning [06:00, 12:00) | afternoon [12:00, 18:00) | evening [18:00, 24:00). "early morning" is accepted. "night" is rejected. There is no overnight slot. | |
| min_rating | No | Minimum star rating (buses with under 15 ratings are excluded from this filter -- their rating isn't shown either). | |
| destination | Yes | Arrival city name, e.g. "Hyderabad". | |
| depart_after | No | Earliest departure, e.g. 18 or "18:00" (inclusive). 7, "7", and "07:00" are the same instant. | |
| depart_before | No | Exclusive end, e.g. 7 or "07:30". "4–7 AM" is depart_after="04:00", depart_before="07:00". "00:00" means the end of this day. A window whose end is earlier than its start (22:00 to 04:00) is rejected; this search does not cross midnight. | |
| paytm_assured | No | Only Paytm Assured buses. | |
| boarding_point | No | Restrict to buses with a matching boarding-point area. | |
| source_city_id | No | Resolved Paytm city id for source -- only pass this after a prior call returned needsDisambiguation with sourceCityOptions, using the id the traveller picked. | |
| destination_city_id | No | Same, for destination. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| buses | No | ||
| search | Yes | ||
| currency | No | INR | |
| followups | No | ||
| moreBuses | No | ||
| sortRanks | No | ||
| summaries | No | ||
| disclaimer | No | ||
| summariesPending | No | ||
| sourceCityOptions | No | ||
| totalBeforeFilter | No | ||
| serverProcessingMs | No | ||
| needsDisambiguation | No | ||
| destinationCityOptions | No |