FlightPowers: search one-way flights
search_oneway_flightsFind one-way flight fares for any date range or multiple destinations, with live prices, airline, duration, stops, and booking links. Compare historical price insights to see if a fare is a good deal.
Instructions
FlightPowers one-way fare search: live prices read from Google Flights. Input: origin and destination IATA codes -- the destination may be several codes, as "BCN,LIS,ATH" or ["BCN","LIS","ATH"] -- plus either one departure date or a date range. Returns each flight's price, airline, duration, stops, a bookable buy_link, and Google's historical price range (price_insights_low / price_insights_high) so you can say whether a fare is actually a good deal.
Use it for any one-way fare question, including open-ended ones. For a flexible search make ONE call with a date range and/or several destinations -- do NOT call it once per date. 'Cheapest flight to Sri Lanka anywhere in October' is one call, not thirty.
Each date/destination combination is one billed request; the count and the plan's remaining quota come back in api_usage.
by_destination carries one entry per destination you asked for -- empty ones included, each with a reason -- so read it before telling a user a destination has no flights.
Requires the caller's own RapidAPI key for the Google Flights Live API. Get one (free tier available) at https://rapidapi.com/mtnrabi/api/google-flights-live-api, then pass it as an x-rapidapi-key header (preferred), a ?rapidapi_key= query parameter on the server URL, or your client's own API key field -- first non-empty wins. Usage counts against the caller's own RapidAPI plan, not ours; every response reports what it spent and what is left in api_usage.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum flights to return, after merging and sorting. | |
| sort_by | No | "best", "price", or "duration". Applied across all results. | best |
| currency | No | ISO currency code, default "usd". | usd |
| max_price | No | Only return flights at or below this price. | |
| max_stops | No | Maximum stops per flight. 0 means non-stop only. | |
| seat_type | No | 1 economy, 2 premium economy, 3 business, 4 first. | |
| passengers | No | Passenger counts as [adults, children, infants]. | |
| to_airport | Yes | Destination airport. One IATA code ("BCN"), several separated by commas ("BCN,LIS,ATH"), or a list (["BCN","LIS","ATH"]) -- every shape is accepted and the destinations are compared in the same search. | |
| from_airport | Yes | Origin IATA code, e.g. "TLV". One origin per search; a second one is refused rather than searched. | |
| max_searches | No | Cap the billed requests this call may make. Lower it to spend less of the plan's quota on a wide search; the range is then sampled evenly rather than cut short. | |
| use_fallback | No | Leave unset. Switches the search to a second, independent flight data source instead of the usual Google Flights page read. Unset already escalates to that source once, automatically, after a search's retries have failed. true forces it inline on every attempt -- much slower, and it can time out. false disables it entirely, that automatic retry included. | |
| airline_codes | No | Restrict to these airline codes, e.g. ["LY"]. | |
| departure_date | No | Single departure date, "YYYY-MM-DD". | |
| arrival_time_max | No | Latest arrival hour, 0-23. | |
| arrival_time_min | No | Earliest arrival hour, 0-23. | |
| departure_date_to | No | Last date of a departure range. | |
| departure_time_max | No | Latest departure hour, 0-23. | |
| departure_time_min | No | Earliest departure hour, 0-23. | |
| departure_date_from | No | First date of a departure range. | |
| exclude_airline_codes | No | Exclude these airline codes. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Present when there is something the model must relay to the user rather than silently absorb -- no results, a degraded search, a missing key or a spent quota. | |
| partial | No | Present when some searches failed but others succeeded. Plain text saying how much of the request the results cover. | |
| results | Yes | The itineraries or properties found, already sorted and deduplicated. An empty array is only meaningful when search_status is 'empty'. | |
| api_usage | No | What this call cost the caller's own RapidAPI plan, and what remains on it. Present on every response that reached the upstream, including a degraded one -- a search that failed was still billed. | |
| signup_url | No | Where the caller subscribes or changes plan. | |
| result_count | No | ||
| needs_api_key | No | True when no usable RapidAPI key arrived with the call, or the upstream rejected the one that did. No search was run and nothing was billed; signup_url and message say how to fix it. | |
| search_status | No | Whether the underlying search actually completed, read from the backend's X-Search-Status header. 'ok': every combination searched returned results. 'empty': the search completed and Google genuinely has no itineraries for it -- a real answer, not a failure. 'partial': some combinations returned results and some failed, so the list is incomplete. 'degraded': every combination failed, so the search did not happen and an empty list means nothing; this case is also flagged with isError: true and is safe to retry. | |
| by_destination | No | One entry per destination the REQUEST asked for, in request order, present whether or not that destination has any flights in `results`. A destination with an empty `rows` array is a hole in the answer, and `reason` says which kind of hole: 'no_flights' (searched, answered, Google has nothing), 'search_failed' (searched and the search errored, so nothing is known), 'not_in_limit' (searched, found flights, none fitted in `limit`) or 'not_searched' (never searched -- the per-call fan-out cap sampled it away). 'ok' means it has rows. Read this rather than inferring coverage from `results`: a destination missing from `results` looks identical to one that has no flights, and they are not the same answer. `rows` are the same row objects that are in `results`, in the same order -- nothing here is data the answer does not already contain. | |
| quota_exhausted | No | True when the caller's RapidAPI plan has no requests left for the current period. | |
| search_coverage | No | What was actually searched. Present whether or not the request was truncated, so a model can state honestly what its answer rests on. |