Google Flights

Perform Search

Overview

Method	Endpoint	Version	Description
`POST`	`/api/v1/open/search`	v1	Google Search API endpoint for retrieving search results

Request Headers

Header	Type	Required	Description
`Content-Type`	`string`	Yes	Must be set to `application/json`
`Accept`	`string`	No	Response format (defaults to `application/json`)

Authentication

API Key Authentication - Pass the API key as a request parameter: api_key=your_api_key - Example: "api_key": "your_api_key_here"

Request Example

curl -X POST "https://domain/api/v1/open/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    // ...
  }'

Response Format

All responses follow a standardized JSON structure:

{
  "code": 200,
  "msg": "Success",
  "reqId": "req_1234567890",
  "timestamp": "2025-01-08T10:30:00Z",
  "data": {
    // Response data object
  }
}

HTTP Status Codes

Code	Status	Description	Retry
200	OK	Request successful	No

Request Parameters

Parameter	Type	Required	Description	Default
`api_key`	`string`	Yes	API key for authentication
`engine`	`string`	Yes	Search engine type, currently engine value is `google_flights`	google
`departure_id`	`string`	Yes	Parameter defines the departure airport code or location kgmid. An airport code is an uppercase 3-letter code. You can search for it on Google Flights or IATA. For example, CDG is Paris Charles de Gaulle Airport and AUS is Austin-Bergstrom International Airport. A location kgmid is a string that starts with /m/. You can search for a location on Wikidata and use its "Freebase ID" as the location kgmid. For example, /m/0vzm is the location kgmid for Austin, TX. You can specify multiple departure airports by separating them with a comma. For example, CDG,ORY,/m/04jpl.
`arrival_id`	`string`	No	Parameter defines the arrival airport code or location kgmid. An airport code is an uppercase 3-letter code. You can search for it on Google Flights or IATA. For example, CDG is Paris Charles de Gaulle Airport and AUS is Austin-Bergstrom International Airport. A location kgmid is a string that starts with /m/. You can search for a location on Wikidata and use its "Freebase ID" as the location kgmid. For example, /m/0vzm is the location kgmid for Austin, TX. You can specify multiple arrival airports by separating them with a comma. For example, CDG,ORY,/m/04jpl.
`gl`	`string`	No	Search country code (e.g., us-United States, uk-United Kingdom, fr-France). Head to the Google countries page for a full list of supported Google countries.
`hl`	`string`	No	Search language code (e.g., en-English, es-Spanish, fr-French). Head to the Google languages page for a full list of supported Google languages.
`currency`	`string`	No	Parameter defines the currency of the returned prices. Default to USD. Head to the Google Travel Currencies page for a full list of supported currency codes.
`device`	`string`	No	Device type, currently only supports desktop version	desktop
`adults`	`string`	No	Parameter defines the number of adults. Default to 1	1
`children`	`string`	No	Parameter defines the number of children. Default to 0	0
`infants_in_seat`	`string`	No	Parameter defines the number of infants in seat. Default to 0	0
`infants_on_lap`	`string`	No	Parameter defines the number of infants on lap. Default to 0	0
`type`	`string`	No	Parameter defines the type of the flights. Available options: 1 - Round trip (default), 2 - One way, 3 - Multi-city. When this parameter is set to 3, use multi_city_json to set the flight information. To obtain the returning flight information for Round Trip (1), you need to make another request using a departure_token.
`outbound_date`	`string`	Yes	Parameter defines the outbound date. The format is YYYY-MM-DD. e.g. 2025-09-20
`return_date`	`string`	No	Parameter defines the return date. The format is YYYY-MM-DD. e.g. 2025-09-26. Parameter is required if type parameter is set to: 1 (Round trip)
`travel_class`	`string`	No	Parameter defines the travel class. Available options: 1 - Economy (default), 2 - Premium economy, 3 - Business, 4 - First
`multi_city_json`	`string`	No	Fill in this parameter, and its value will take precedence. Parameter defines the flight information for multi-city flights. It's a JSON string containing multiple flight information objects. Each object should contain the following fields: departure_id - The departure airport code or location kgmid. The format is the same as the main departure_id parameter. arrival_id - The arrival airport code or location kgmid. The format is the same as the main arrival_id parameter. date - Flight date. The format is the same as the outbound_date parameter. times - Time range for the flight. The format is the same as the outbound_times parameter. This parameter is optional. Example: {"itinerary":[{"departure_id":"PVG","arrival_id":"PEK","date":"2025-11-01","times":"4,18"},{"departure_id":"PEK","arrival_id":"PVG","date":"2025-11-11","times":"4,18"}],"adults":1,"children":0,"infants_in_seat":0,"infants_on_lap":0,"travel_class":1,"type":1} The example is a round trip flight from PVG to PEK on 2025-11-01, then from PEK to PVG on 2025-11-11. There is a departure time range from 4:00 AM - 7:00 PM for both the outbound and return flights.
`html`	`string`	No	Whether to return HTML format, 1-yes, 0-no	0

Response Example

{
    "code": 200,
    "data": {
        "search_metadata": {
            "raw_html_file": "oss_html",
            "total_time_taken": 2.032416469,
            "id": "1985902431212408832",
            "json_endpoint": "oss_json",
            "created_at": "2025-10-29 08:53:31",
            "processed_at": "2025-10-29 08:53:33",
            "google_url": "https://www.google.com/travel/flights/search?tfs=CBwQAhoeEgoyMDI1LTExLTExagcIARIDUFZHcgcIARIDUEVLQAFIAXABggELCP___________wGYAQI",
            "status": "Success"
        },
        "search_information": {
          "time_taken_displayed": 0.042
        },
        "search_parameters": {
            "engine": "google_flights",
            "html": "0",
            "google_domain": "www.google.com",
            "q": "google_flights",
            "departure_id": "PVG",
            "arrival_id": "PEK",
        },
        "best_flights": [
          {
            "flights": [
              {
                "departure_airport": {
                  "name": "Shanghai Pudong International Airport",
                  "id": "PVG",
                  "time": "2025-10-17 18:00"
                },
                "arrival_airport": {
                  "name": "Beijing Capital International Airport",
                  "id": "PEK",
                  "time": "2025-10-17 15:30"
                },
                "duration": 150,
                "airplane": "Airbus A321",
                "airline": "China Eastern",
                "airline_logo": "https://www.gstatic.com/flights/airline_logos/70px/MU.png",
                "travel_class": "Economy",
                "flight_number": "MU 5161",
                "legroom": "31 in"
              }
            ],
            "total_duration": 150,
            "carbon_emissions": {
              "this_flight": 137000,
              "typical_for_this_route": 114000,
              "difference_percent": 20
            },
            "price": 312,
            "type": "round trip",
            "airline_logo": "https://www.gstatic.com/flights/airline_logos/70px/MU.png",
            "departure_token": "CjRIemlncmtPQjRBWEVBQ0VfVHdCRy0tLS0tLS0tc21iZHQxMkFBQUFBR2p3c2MwTlFsa2dBEgZNVTUxNjEaCwjM8wEQAhoDVVNEOB1wzPMB"
          }
        ],
        "other_flights": [
          {
            "flights": [
              {
                "departure_airport": {
                  "name": "Shanghai Pudong International Airport",
                  "id": "PVG",
                  "time": "2025-10-17 16:55"
                },
                "arrival_airport": {
                  "name": "Macau International Airport",
                  "id": "MFM",
                  "time": "2025-10-17 19:45"
                },
                "duration": 170,
                "airplane": "Airbus A321",
                "airline": "Air Macau",
                "airline_logo": "https://www.gstatic.com/flights/airline_logos/70px/NX.png",
                "travel_class": "Economy",
                "flight_number": "NX 135",
                "legroom": "29 in",
                "ticket_also_sold_by": "Shenzhen"
              },
              {
                "departure_airport": {
                  "name": "Macau International Airport",
                  "id": "MFM",
                  "time": "2025-10-18 8:10"
                },
                "arrival_airport": {
                  "name": "Beijing Capital International Airport",
                  "id": "PEK",
                  "time": "2025-10-18 11:25"
                },
                "duration": 195,
                "airplane": "Airbus A320",
                "airline": "Air Macau",
                "airline_logo": "https://www.gstatic.com/flights/airline_logos/70px/NX.png",
                "travel_class": "Economy",
                "flight_number": "NX 6",
                "legroom": "29 in",
                "ticket_also_sold_by": "Shenzhen"
              }
            ],
            "layovers": [
              {
                "duration": 745,
                "name": "Macau International Airport",
                "id": "MFM"
              }
            ],
            "total_duration": 1110,
            "carbon_emissions": {
              "this_flight": 353000,
              "typical_for_this_route": 114000,
              "difference_percent": 210
            },
            "price": 233,
            "airline_logo": "https://www.gstatic.com/flights/airline_logos/70px/NX.png",
            "departure_token": "CjRIemlncmtPQjRBWEVBQ0VfVHdCRy0tLS0tLS0tc21iZHQxMkFBQUFBR2p3c2MwTlFsa2dBEglOWDEzNXxOWDYaCwjTtQEQAhoDVVNEOB1w07UB"
          }
        ],
        "price_insights": {
          "lowest_price": 233,
          "price_level": "high"
        },
        "airports": [
          {
            "departure": [
              {
                "airport": {
                  "id": "PVG",
                  "name": "Shanghai Pudong International Airport"
                },
                "city": "Shanghai",
                "country": "China",
                "country_code": "CN",
                "image": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcTujsAS0i3-zbeimLQQ8RJnTX80xFZm7VnTsswhTD6W1aHQZWxzA7pNb0BMAVpelCNQq3SEx1592gylHw",
                "thumbnail": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcSf_rHrecM1vgBbijdc3hHmMhc7Ur5d25JUiJtkb1TFjyb8o00dh6hVYtkXSkreGSokUxE8IQygysyFoMm4DaloR8oEdOOr1fKHxMByxDQ"
              }
            ]
          }
        ]
    },
    "msg": "string",
    "reqId": "string"
}

Complete Response Parameters Overview

search_metadata

object Contains metadata about the search execution

Parameter	Type	Description	Applicable Terminal
`id`	`string`	Unique identifier for the search request	desktop
`json_endpoint`	`string`	Provide an interface endpoint for searching related JSON data, through which JSON-formatted search data can be obtained	desktop
`created_at`	`string`	The timestamp when the search request was created, recording the time when the search was initiated	desktop
`processed_at`	`string`	The timestamp when the search results were processed and became available for return, recording the time point from processing to completion of the search	desktop
`google_url`	`string`	The Google search URL, which contains the search keyword "coffee" along with language parameters (hl=en for English), regional parameters (gl=us for the United States), and other search parameters, used to redirect to the corresponding Google search page	desktop
`status`	`string`	Status of the search execution (e.g., Success)	desktop
`raw_html_file`	`string`	Identifier for the original HTML file	desktop
`total_time_taken`	`number`	The total time spent on the entire search process (including request sending, result parsing, and other stages)	desktop

search_information

object Contains information about the search results

Parameter	Type	Description	Applicable Terminal
`time_taken_displayed`	`number`	TDisplay time (i.e., the time spent on displaying the search results)	desktop

search_parameters

object Contains the parameters used for the search

Parameter	Type	Description	Applicable Terminal
`departure_id`	`string`	Departure airport code or location kgmid	desktop
`arrival_id`	`string`	Arrival airport code or location kgmid	desktop
`engine`	`string`	Search engine used for this query (e.g., google_web)	desktop
`html`	`string`	When HTML=0, returns JSON; when HTML=1, returns HTML; when HTML=2, returns both JSON and HTML	desktop
`device`	`string`	Device type used during search (e.g., desktop)	desktop
`google_domain`	`string`	Specifies the corresponding Google domain (e.g., google.com, etc., used to distinguish Google services in different regions/locales)	desktop

best_flights

object[] Optimal flight recommendation set filtered and returned based on multiple dimensions such as price, flight duration, number of stopovers, and airline reputation

Parameter	Type	Description	Applicable Terminal
`flights`	`object[]`	Array of flight information containing details of specific flights	desktop
`flights[].departure_airport`	`object`	Departure airport information	desktop
`flights[].departure_airport.name`	`string`	Departure airport name	desktop
`flights[].departure_airport.id`	`string`	Departure airport code	desktop
`flights[].departure_airport.time`	`string`	Departure time	desktop
`flights[].arrival_airport`	`object`	Arrival airport information	desktop
`flights[].arrival_airport.name`	`string`	Arrival airport information	desktop
`flights[].arrival_airport.id`	`string`	Arrival airport code	desktop
`flights[].arrival_airport.time`	`string`	Arrival time	desktop
`flights[].duration`	`number`	Flight duration of a single segment	desktop
`flights[].airplane`	`string`	Aircraft model	desktop
`flights[].airline`	`string`	Airline	desktop
`flights[].airline_logo`	`string`	Image link of airline logo	desktop
`flights[].travel_class`	`string`	Cabin class	desktop
`flights[].flight_number`	`string`	Flight number	desktop
`flights[].legroom`	`string`	Legroom	desktop
`total_duration`	`number`	Total flight duration	desktop
`carbon_emissions`	`object`	Carbon emission data	desktop
`carbon_emissions.this_flight`	`number`	Carbon emissions of this flight	desktop
`carbon_emissions.typical_for_this_route`	`number`	Typical carbon emissions of this route	desktop
`carbon_emissions.difference_percent`	`number`	Percentage difference between this flight’s carbon emissions and the typical route emissions	desktop
`price`	`number`	Flight price	desktop
`type`	`string`	Flight type	desktop
`airline_logo`	`string`	Airline logo image link	desktop
`departure_token`	`string`	Identifier token associated with departure information	desktop

other_flights

object[] A set of alternative flight recommendations filtered and returned based on multiple dimensions such as price, flight duration, number of stopovers, and airline reputation

Parameter	Type	Description	Applicable Terminal
`flights`	`object[]`	An array of flight information containing details of specific flights	desktop
`flights[].departure_airport`	`object`	Departure airport information	desktop
`flights[].departure_airport.name`	`string`	Departure airport name	desktop
`flights[].departure_airport.id`	`string`	Departure airport code	desktop
`flights[].departure_airport.time`	`string`	Departure time	desktop
`flights[].arrival_airport`	`object`	Arrival airport information	desktop
`flights[].arrival_airport.name`	`string`	Arrival airport information	desktop
`flights[].arrival_airport.id`	`string`	Arrival airport code	desktop
`flights[].arrival_airport.time`	`string`	Arrival time	desktop
`flights[].duration`	`number`	Flight duration of a single segment	desktop
`flights[].airplane`	`string`	Aircraft model	desktop
`flights[].airline`	`string`	Airline	desktop
`flights[].airline_logo`	`string`	Image link of airline logo	desktop
`flights[].travel_class`	`string`	Cabin class	desktop
`flights[].flight_number`	`string`	Flight number	desktop
`flights[].legroom`	`string`	Legroom	desktop
`flights[].ticket_also_sold_by`	`string`	Which channels or agencies can also sell the ticket	desktop
`layovers`	`object[]`	Array of transfer airport information	desktop
`layovers[].duration`	`number`	Layover duration	desktop
`layovers[].name`	`string`	Transit airport name	desktop
`layovers[].id`	`string`	IATA code of the transit airport	desktop
`total_duration`	`number`	Total flight duration	desktop
`carbon_emissions`	`object`	Carbon emission data	desktop
`carbon_emissions.this_flight`	`number`	Carbon emissions of this flight	desktop
`carbon_emissions.typical_for_this_route`	`number`	Typical carbon emissions of this route	desktop
`carbon_emissions.difference_percent`	`number`	Percentage difference between this flight’s carbon emissions and the typical route emissions	desktop
`price`	`number`	Flight price	desktop
`airline_logo`	`string`	Airline logo image link	desktop
`departure_token`	`string`	Identifier token associated with departure information	desktop

price_insights

object Price Insights module: Key reference information on flight prices

Parameter	Type	Description	Applicable Terminal
`lowest_price`	`number`	Lowest available price for the currently queried flight	desktop
`price_level`	`string`	Categorical description of price levels, used to indicate how the current price compares among similar flights	desktop

airports

object A collection of airport information related to the flight, including departure airport, arrival airport, and transit airports (if applicable)

Parameter	Type	Description	Applicable Terminal
`departure`	`object[]`	A list containing details such as departure airport, city, and country	desktop
`departure[].airport`	`object`	An object encapsulating detailed information about the departure airport	desktop
`departure[].airport.id`	`string`	Identifier code of the departure airport	desktop
`departure[].airport.name`	`string`	Departure airport name	desktop
`departure[].city`	`string`	Name of the city where the departure airport is located	desktop
`departure[].country`	`string`	Name of the country where the departure airport is located	desktop
`departure[].country_code`	`string`	Code of the country where the departure airport is located	desktop
`departure[].image`	`string`	Image resource link related to the departure airport	desktop
`departure[].thumbnail`	`string`	Thumbnail image resource link related to the departure airport	desktop