FlightPowers: search round-trip flights
search_roundtrip_flightsFlightPowers round-trip fare search: live prices read from Google Flights, priced as paired legs rather than two separate one-ways. Input: origin and destination IATA codes -- the destination may be several codes, as "BCN,LIS,ATH" or ["BCN","LIS","ATH"] -- a departure date or range, and either a return date or a trip length in nights. Returns the total price for both legs, per-leg airline, stops and duration, and a single bookable buy_link for the trip.
Use it for any return-trip fare question. For a flexible search make ONE call: pass departure_date_from / departure_date_to for the outbound range and nights instead of return_date to compare trip lengths -- '5 to 7 nights in Rome sometime in May' is one call.
A WHOLE MONTH is one call too. departure_date_from "2026-10-01", departure_date_to "2026-10-31" and nights [3, 4, 5] prices every departure day in October at three trip lengths and tells you which combination is cheapest. That is 93 date/night combinations and the cap rises to cover them by itself -- do not narrow the question to make it fit, and do not split it into several calls.
Each date/night/destination combination is ONE request billed to the caller's plan, so a month at three trip lengths costs 93 of them and the same month across two destinations costs 186. Say that number before running a search that large if the user has not asked for it in so many words. A search that fails with a server error is retried once and RapidAPI bills the retry, so the figure to quote back is api_usage.hub_requests_billed (what the plan was actually charged), not the combination count. Both come back in api_usage, with the plan's remaining quota.
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. No key? Sign in with Google and the first 10 searches each day are free on this server -- ad-free, nothing to paste. Connect your own RapidAPI key at https://flights.flightpowers.com/connect to remove the cap.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum trips to return, after merging and sorting. | |
| nights | No | Trip length in nights; a number, or a list like [5, 6, 7]. The return date is derived from each departure date. | |
| sort_by | No | "best", "price", or "duration". Applied across all results. | best |
| verbose | No | Return every field the upstream sends on each fare, and every fare that was selected, with no row bound. Off by default: a result carries the best rows by your sort_by in a compact shape (dates, destination, airline, stops, duration, price, trip length and the booking link), because a wide search over a month and several destinations otherwise produces a megabyte of JSON that some hosts refuse to put in the conversation at all. Turn it on when you need the arrival times, the per-leg stop counts, the raw stop details or more rows than results_returned; results_total always says how many there were. | |
| currency | No | ISO currency code, default "usd". | usd |
| max_price | No | Only return trips at or below this total price. | |
| seat_type | No | 1 economy, 2 premium economy, 3 business, 4 first. | |
| passengers | No | One entry per traveller, not a count: 1 adult, 2 child (aged 2-11), 3 infant on lap, 4 infant in seat, e.g. [1, 1, 2] for two adults and a child. At least one adult, each infant on lap needs its own adult, at most 9. Omit for one adult. A counts list [adults, children, infants], e.g. [2, 1, 0], or a bare [2] for two adults, is recognised and converted to codes before the search; a list that is valid as codes is searched as codes. | |
| 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. | |
| return_date | No | Fixed return date. Use this OR nights, not both. | |
| from_airport | Yes | Origin IATA code, e.g. "TLV". One origin per search; a second one is refused rather than searched. | |
| max_searches | No | The billed requests this call may make, up or down. Leave it out for the normal behaviour: the cap covers the request when the request is reasonable (a whole month at three trip lengths is 93 combinations and a whole month x 3 nights x 3 destinations is 279; both run in full) and anything past it is sampled evenly across the range rather than cut short. Set it lower to spend less of the plan's quota on a wide search, or higher -- to a hard maximum of 300 -- for a grid wider than that. | |
| 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. | |
| departure_date | No | Single outbound date, "YYYY-MM-DD". | |
| max_return_stops | No | Maximum stops on the return leg. | |
| departure_date_to | No | Last date of an outbound range. | |
| departure_date_from | No | First date of an outbound range. | |
| max_departure_stops | No | Maximum stops on the outbound leg. | |
| return_airline_codes | No | Restrict the return leg to these airlines. | |
| departure_airline_codes | No | Restrict the outbound leg to these airlines. |
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 fares found, already sorted and deduplicated. An empty array is only meaningful when search_status is 'empty'. This is the TOP results_returned of results_total rows by the sort you asked for -- cheapest first by default, shortest first on sort_by 'duration' -- with every destination that has fares still represented. Each row is in a compact shape: destination, the date or dates, trip length in nights on a round trip, airline (both legs on a round trip), stops, duration, the price as a string and a number, Google's price band with its verdict, and the booking link. The origin is on the response as from_airport rather than repeated on every row. Arrival descriptions, per-leg stop counts, raw stop details and the duration in seconds are dropped; `verbose: true` returns them, and every row that was selected, on that call. | |
| 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. | |
| from_airport | No | The origin, as the upstream renders it ('Tel Aviv (TLV)'). One origin per search, so it is on the response rather than repeated on every row. | |
| result_count | No | How many rows are in `results`; same as results_returned. | |
| 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. | |
| results_total | No | How many fares the search selected across every searched combination, before any row bound. Equal to results_returned unless the server bounded a response it had widened itself. | |
| 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. 'trial_exhausted': the free signed-in allowance on this server is spent for today, so nothing was searched and nothing was billed; it renews at 00:00 UTC and connecting your own RapidAPI key removes the cap. Retrying does not help. 'quota_exceeded': the search was refused because the caller's remaining allowance or plan quota cannot cover the number of combinations asked for; combos_requested and combos_allowed_now carry the two numbers. Nothing was searched beyond what it cost to read the quota. Retrying the same search does not help -- ask for fewer dates or nights, or move to a larger plan. | |
| 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. `row_count` is how many of this destination's fares were selected; the fares themselves are in `results` and are not repeated here. `verbose: true` restores the `rows` array for callers that read it. | |
| 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. | |
| results_returned | No | How many of them are in `results` -- the best ones by the sort_by asked for, cheapest first by default, and never all of one destination at the expense of another. Lower than results_total only when `limit` was raised by the server to cover the fan-out rather than asked for; search_coverage.note says so when it happens, and `verbose: true` returns them all. |