Travel Query

Resolve a place name to IATA codes: 'London' -> LON (city) with LHR, LGW, STN...; 'JFK' -> John F. Kennedy International. Call this before search_flights whenever the person names a place rather than a code. Each result has match_type (exact | partial | fuzzy | country) and a 0-1 confidence (fuzzy never exceeds 0.7). All fuzzy means a probable typo: the closest spellings are offered -- ASK which one. 'country' means the query named a country: ask which city. Never invent a code -- on no_data, ask. Returns an envelope: {status, mode, data, coverage, as_of, notes}. status is ok | partial | no_data | expired | not_found. mode is 'test' or 'live' -- in test mode every fare is a Duffel fixture, not a real flight or price, and you must say so. `expired`: the offer existed and can no longer be booked -- search again. `not_found`: the id is wrong -- do NOT search again for it. Always pass notes[] on to the person.

Search live fares from TWO sources at once -- Duffel, and Ignav, which adds airlines Duffel does not sell (Southwest, JetBlue, Frontier and other low-cost carriers); each fare says its source, and data.suppliers says what each answered. One slice is one-way; two (out and back) is a return; up to four for multi-city (Ignav takes at most two). A round trip comes back OUTBOUND-FIRST: each outbound flight with its best 3 returns. Otherwise results are ITINERARIES: one schedule with its fares. Ranked 'best' by default -- fare plus a stated cost of time, overnights and long layovers -- because the cheapest trip is often one nobody wants. Compact by default; from_price and fares[].total are for ALL passengers together. Use time_window for time-of-day rules ('nothing before 7am, no red-eyes'; airport_buffer_minutes makes it the traveller's day, not the airport's) and max_layover_minutes to cap connections. Each call is a real request to airlines and spends one of the key's daily searches, so ask for missing dates or passenger counts rather than searching speculatively -- and use more_results, which is free, to see past the first page. Prices are NOT final: call get_offer before the person decides. Never ask for passport numbers, dates of birth or payment details in the conversation. A fare with source "ignav" is booked on the provider's own site (get_offer returns its booking_links). Returns an envelope: {status, mode, data, coverage, as_of, notes}. status is ok | partial | no_data | expired | not_found. mode is 'test' or 'live' -- in test mode every fare is a Duffel fixture, not a real flight or price, and you must say so. `expired`: the offer existed and can no longer be booked -- search again. `not_found`: the id is wrong -- do NOT search again for it. Always pass notes[] on to the person.

The next page of an earlier search_flights, with the same filters, grouping and sort. Pass search_id exactly as returned and the offset from the notes. This lists what the airlines already returned -- it does NOT spend a search. Offers that have expired since are left out and counted in the notes. Returns an envelope: {status, mode, data, coverage, as_of, notes}. status is ok | partial | no_data | expired | not_found. mode is 'test' or 'live' -- in test mode every fare is a Duffel fixture, not a real flight or price, and you must say so. `expired`: the offer existed and can no longer be booked -- search again. `not_found`: the id is wrong -- do NOT search again for it. Always pass notes[] on to the person.

Fetch one offer's CURRENT price, conditions and booking deadline. Search prices go stale within minutes; this is the number to quote when the person is deciding. For a fare with source "ignav" (offer_id ign_...) it also returns booking_links: the airline's (or an agency's) own pages where the person books it. Pass checked_bags to get the all-in price with bags, and the search_id the offer came from so all_in.alternative can name a fare on the same flights that already includes the bags -- one call answers 'what does this really cost with a bag?'. `expired` means search again; `not_found` means the id is wrong. Returns an envelope: {status, mode, data, coverage, as_of, notes}. status is ok | partial | no_data | expired | not_found. mode is 'test' or 'live' -- in test mode every fare is a Duffel fixture, not a real flight or price, and you must say so. `expired`: the offer existed and can no longer be booked -- search again. `not_found`: the id is wrong -- do NOT search again for it. Always pass notes[] on to the person.

Fetch 2-4 offers fresh and compare them. diff[] gives each relative to the cheapest: price delta, all-in delta (with checked_bags; ranked among offers that have one), checked bags, duration delta, stops_per_slice (one entry per leg -- [1, 1] is one stop each way, NOT two stops out), and whether it can be refunded or changed and at what penalty. Offers for DIFFERENT trips (route, dates, legs or passengers) are not ranked: data.comparable is false and the notes say why. Duplicate ids are ignored. Returns an envelope: {status, mode, data, coverage, as_of, notes}. status is ok | partial | no_data | expired | not_found. mode is 'test' or 'live' -- in test mode every fare is a Duffel fixture, not a real flight or price, and you must say so. `expired`: the offer existed and can no longer be booked -- search again. `not_found`: the id is wrong -- do NOT search again for it. Always pass notes[] on to the person.