Flight search with flights_search

flights_search searches Google Flights for a known origin, destination, and outbound date. It supports one-way and round-trip itineraries with semantic cabin and passenger fields.

When to use it

Use it when the route is known and the agent needs itineraries, prices, airlines, stops, or duration. Choose travel_explore_search when the destination is not decided.

This tool supports one-way and round-trip searches. Multi-city itineraries are not currently supported.

Quick example

from serpapi_search_tools import flights_search

flight_tool = flights_search(
    default_params={"currency": "USD", "hl": "en"},
)
agent_tools = [flight_tool]

Example invocation:

{
  "departure_id": "LAX",
  "arrival_id": "AUS",
  "outbound_date": "2030-08-01",
  "return_date": "2030-08-04",
  "travel_class": "business",
  "adults": 1
}

Inputs the agent can provide

Field Type Required Default and constraints
departure_id string yes Specific airport IATA code such as LHR, or an exact city Google Knowledge Graph location ID (KGMID) beginning with /m/ or /g/, such as /m/04jpl for London; metropolitan codes such as LON are unsupported; see the Google Flights API; comma-separated values are supported
arrival_id string yes Specific airport IATA code such as CDG, or an exact city KGMID beginning with /m/ or /g/, such as /m/05qtj for Paris; metropolitan codes such as PAR are unsupported; see the Google Flights API; comma-separated values are supported
outbound_date date string yes Future date in YYYY-MM-DD format
return_date date string no Provide for a round trip; omit for one way; must not be before outbound
travel_class enum no economy; also premium_economy, business, or first
adults integer no 1; at least 1
children integer no 0; cannot be negative
infants_in_seat integer no 0; cannot be negative
infants_on_lap integer no 0; cannot be negative

Three-letter alphabetic airport codes are normalized to uppercase. City-wide searches require a KGMID, such as /m/04jpl for London or /m/05qtj for Paris; LON and PAR are metropolitan codes rather than specific airport codes. Omitting return_date makes the request one way; supplying it makes the request a round trip.

Configure the tool

Constructor option Default Use it for
provider "auto" Detect one installed SDK or select one explicitly
default_params None Fix currency, locale, stops, airline, bag, or time filters supported by SerpApi
mode compact Return the main flight result sections; use SearchResultMode.FULL to keep supporting sections and all fields on retained results
response_format markdown Return Markdown by default, or use SearchResultFormat.JSON for structured fields
result_limit 10 Maximum entries retained independently from best_flights and other_flights in either mode
api_key None Override environment key lookup
timeout None Set the built-in client timeout
client None Add caching, logging, testing, or response compaction
include_examples True Add a route-search hint to the description
name "flights_search" Rename a configured route capability

Useful SerpApi parameters

This tool keeps price display predictable:

from serpapi_search_tools import flights_search

us_flights = flights_search(
    default_params={"currency": "USD", "hl": "en", "gl": "us"},
    name="us_flights",
)

SerpApi also supports airline, stops, baggage, maximum price, departure time, arrival time, and other filters. The package validates common conflicts: for example, include and exclude airline lists cannot both be set, return-time filters need a round trip, and bag counts cannot exceed eligible passengers.

What comes back

Both modes apply result_limit independently to best_flights and other_flights, keeping up to 10 itineraries in each list by default. Flight legs and layovers within an itinerary are not shortened. Use full mode for supporting sections such as price insights, airports, and metadata. Add result_limit=None to keep every returned itinerary.

Common mistakes

  • Flight searches use structured route and date fields; there is no q input.
  • Omitting the route or outbound date.
  • Using a metropolitan code such as LON or PAR instead of a specific airport code or city KGMID.
  • Supplying a return date before outbound.
  • Asking for multi-city itineraries through this one-route schema.
  • Combining both include_airlines and exclude_airlines defaults.
  • Travel dates must be in the future.

Official SerpApi documentation

See the direct travel example and the OpenAI Agents travel planner.