whentofly

{'type': 'object', 'title': 'search_flightsArguments', 'required': ['from'], 'properties': {'ch': {'type': 'string', 'title': 'ch', 'default': 'direct', 'examples': ['web', 'mcp', 'direct'], 'maxLength': 64, 'description': "Acquisition channel tag (e.g. web, mcp, a campaign name) for first-party analytics. Durable booking links retain the validated Travelpayouts marker for commission but do not trust opaque shortlinks solely to carry provider-dashboard sub_id attribution. Defaults to 'direct'; reduced to a bounded registered channel."}, 'to': {'type': 'string', 'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'to', 'examples': ['ICN', 'airport:PVG', 'city:BJS', 'anywhere'], 'description': 'Destination location: a legacy code, airport:AAA, or city:AAA. Pass `anywhere` (or omit) to get the cheapest destinations from the origin instead of a specific route.'}, 'from': {'type': 'string', 'title': 'from', 'examples': ['SGN', 'airport:SHA', 'city:SHA'], 'description': 'Origin location. Use a legacy 3-letter code (SHA), an exact airport (airport:SHA), or an all-airports city (city:SHA). Required for every search, including to=anywhere.'}, 'cabin': {'type': 'string', 'title': 'cabin', 'default': 'economy', 'examples': ['economy', 'business'], 'description': 'Cabin class: economy (default), premium_economy, business, or first. The Travelpayouts calendar covers economy; Google Flights may additionally return action-bound seller quotes for the requested cabin. Actionless evidence remains in metadata.route_price_check.'}, 'top_n': {'type': 'integer', 'title': 'top_n', 'default': 10, 'maximum': 50, 'minimum': 1, 'examples': [10], 'description': 'Maximum number of results to return, sorted cheapest-first. Specific routes allow up to 50; anywhere mode returns at most 12.'}, 'latest': {'type': 'string', 'anyOf': [{'type': 'string', 'format': 'date'}, {'type': 'null'}], 'title': 'latest', 'examples': ['2026-12-28'], 'description': 'Latest acceptable return date for round-trip, or latest acceptable departure for one-way (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Optional: omit it and it is derived from `earliest` (or from the default window when both are omitted). A window ending before today is not searched; the response is empty with a `window_in_past` hint. Ignored in anywhere mode.'}, 'verify': {'type': 'string', 'title': 'verify', 'default': 'false', 'examples': ['false', 'true', 'full'], 'description': "How hard to cross-check the top result's route, dates, and cabin against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget and widen the request-local seller/date sample from at most three pairs to at most seven (set it when you can wait, e.g. an autonomous agent). The six-hour base and its cache key do not change. This does not verify the displayed airline, itinerary, gate, or booking URL; inspect `metadata.route_price_check` separately. Checked-bag searches keep this fare-only route check and verdict null even when verify=true or verify=full; seller-level baggage enrichment still runs. Displayed Travelpayouts fares remain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."}, 'one_way': {'type': 'boolean', 'title': 'one_way', 'default': False, 'description': 'If true, search one-way flights; return_date and duration_days will be null.'}, 'sellers': {'type': 'boolean', 'title': 'sellers', 'default': True, 'examples': [True, False], 'description': 'Whether to run the live seller-quote wave (Google Flights `booking_options`) for this request. Default `true`: unchanged behavior — the bounded frontier resolves seller prices, baggage basis, and the executable booking action. Set `sellers=false` to ask for the ranked fare calendar and the route-level price check ONLY: the response then carries `metadata.seller_enrichment_status="skipped"`, results keep their Travelpayouts-grounded prices and durable booking links, and no seller quote, seller-level baggage fee, or direct seller action is resolved. It exists for callers that want the price picture cheaply and do not intend to book — our own curve-seeding crons use it — because the seller wave is where a search\'s provider spend actually goes (about seven of its ~eight calls). Non-economy cabins have no calendar source, so `sellers=false` there leaves `metadata.route_price_check` as the only priced evidence and `results` may be empty.'}, 'currency': {'type': 'string', 'title': 'currency', 'default': 'USD', 'examples': ['USD', 'EUR', 'SGD'], 'description': 'Result currency, 3-letter ISO code UPPERCASE.'}, 'earliest': {'type': 'string', 'anyOf': [{'type': 'string', 'format': 'date'}, {'type': 'null'}], 'title': 'earliest', 'examples': ['2026-09-29'], 'description': 'Earliest acceptable departure date (ISO YYYY-MM-DD). Optional: omit it and a default window is searched, with the applied window echoed in `query` and flagged by `metadata.window_defaulted`. A date already in the past is clamped to today and reported as `window_clamped` in `metadata.hints` — unless `latest` has passed too, in which case the whole window is declined rather than clamped (see `latest`). Ignored in anywhere mode.'}, 'max_days': {'type': 'integer', 'title': 'max_days', 'default': 30, 'maximum': 365, 'minimum': 1, 'examples': [15], 'description': 'Maximum round-trip duration in days (return - departure); ignored for one-way and anywhere mode.'}, 'min_days': {'type': 'integer', 'title': 'min_days', 'default': 3, 'maximum': 365, 'minimum': 1, 'examples': [10], 'description': 'Minimum round-trip duration in days (return - departure); ignored for one-way and anywhere mode.'}, 'checked_bags': {'type': 'integer', 'title': 'checked_bags', 'default': 0, 'maximum': 1, 'minimum': 0, 'examples': [0, 1], 'description': "Checked bags requested for the current one-adult, specific-route search contract. Anywhere discovery rejects checked_bags=1. Set to 1 to add a seller's unambiguous first-checked-bag fee to the ranked customer price. Unknown fees remain labeled in results[].price_basis instead of being guessed. Seller enrichment still runs, but the fare-only verdict and route-price check remain null, including when verify=true or verify=full."}, 'max_transfers': {'type': 'integer', 'anyOf': [{'type': 'integer', 'maximum': 5, 'minimum': 0}, {'type': 'null'}], 'title': 'max_transfers', 'examples': [0, 1], 'description': 'Maximum number of transfers/layovers per leg. 0 = nonstop only, 1 = up to 1 stop, etc. Omit for no filter.'}}}

{'type': 'object', 'title': 'search_locationsArguments', 'required': ['q'], 'properties': {'q': {'type': 'string', 'title': 'q', 'examples': ['Shanghai', 'SHA', 'Zhangjiajie'], 'maxLength': 80, 'minLength': 1, 'description': 'Airport/city name or 3-letter code prefix.'}, 'limit': {'type': 'integer', 'title': 'limit', 'default': 12, 'maximum': 50, 'minimum': 1}}}