Logo SearchApi

Google Flights Calendar API

Google Flights API uses the /api/v1/search?engine=google_flights_calendar endpoint to retrieve detailed flight information.

This includes price data for flights on specific dates, as well as the ability to filter results by flight duration, layovers, price, and other criteria.

API Parameters

Search Query

  • Name
    departure_id
    Required
    Required
    Description

    This parameter specifies the code for the departure airport or a location identifier.

    • Airport Code: A 3-letter uppercase code representing the departure airport (e.g., MAD for Madrid-Barajas Airport or JFK for John F. Kennedy International Airport). You can find these codes using resources like Google Flights or IATA.
    • Location Identifier (kgmid): A string that begins with /m/, used to represent a specific location. You can find this identifier on Wikidata by looking for the "Freebase ID" while searching for location. For example, /m/02_286 is the identifier for New York,United States.
    • Multiple Airports/Locations: You can specify more than one airport or location by separating them with commas. For example: SEA, MIA, /m/02_286.

  • Name
    arrival_id
    Required
    Required
    Description

    This parameter specifies the code for the arrival airport or a location identifier.

    • Airport Code: A 3-letter uppercase code representing the arrival airport (e.g., MAD for Madrid-Barajas Airport or JFK for John F. Kennedy International Airport). You can find these codes using resources like Google Flights or IATA.
    • Location Identifier (kgmid): A string that begins with /m/, used to represent a specific location. You can find this identifier on Wikidata by looking for the "Freebase ID" while searching for location. For example, /m/02_286 is the identifier for New York,United States.
    • Multiple Airports/Locations: You can specify more than one airport or location by separating them with commas. For example: SEA, MIA, /m/02_286.

Date Range

  • Name
    outbound_date_start
    Required
    Optional
    Description

    Defines the start date for the outbound flight search. Default value is equal to outbound_date. When used, it specifies the earliest departure date to consider. Combined with outbound_date_end, it returns flight prices for all outbound dates within the given range.

  • Name
    outbound_date_end
    Required
    Optional
    Description

    Defines the end date for the outbound flight search. Default value is equal to outbound_date_start + 7 days. Using flight_type=one_way, the response includes all outbound dates between these two values.

  • Name
    return_date_start
    Required
    Optional
    Description

    Defines the start date for the return flight search. Default value is equal to return_date. This parameter is only usable when flight_type=round_trip. When provided, it specifies the earliest possible return date in the search results.

  • Name
    return_date_end
    Required
    Optional
    Description

    Defines the end date for the return flight search. Default value is equal to return_date_start + 7 days. Using both outbound_date_start and return_date_start parameters will return all possible outbound-return date combinations within the specified ranges.

Filters

  • Name
    flight_type
    Required
    Optional
    Description

    Defines the type of the flights. Available options:

    • round_trip Default
    • one_way

  • Name
    outbound_date
    Required
    Required
    Description

    Defines the outbound date. The date format is YYYY-MM-DD.

  • Name
    return_date
    Required
    Required
    Description

    Defines the return date. The date format is YYYY-MM-DD.

  • Name
    travel_class
    Required
    Optional
    Description

    Defines the travel class. Available options:

    • economy Default
    • premium_economy
    • business
    • first_class

  • Name
    stops
    Required
    Optional
    Description

    Defines the number of stops during the flight. Available options:

    • any - Any number of stops. Default
    • nonstop - Nonstop only.
    • one_stop_or_fewer - 1 stop or fewer.
    • two_stops_or_fewer - 2 stops or fewer.

  • Name
    max_price
    Required
    Optional
    Description

    Defines the maximum ticket price. Default is unlimited.

  • Name
    carry_on_bags
    Required
    Optional
    Description

    Defines the number of carry-on bags. Default is 0.

    Note: number can't be higher than amount of passengers.

  • Name
    checked_bags
    Required
    Optional
    Description

    Defines the number of checked bags. Default is 0.

    Note: number can't be higher than amount of passengers.

  • Name
    included_airlines
    Required
    Optional
    Description

    Defines the airline or alliance codes to be selected. An airline or alliance ID is an uppercase code (e.g., AC for Air Canada airline or ONEWORLD for oneworld alliance). Airline codes can be found on IATA. Multiple airlines can be combined by joining them with a comma. For example: AC,ONEWORLD.

  • Name
    excluded_airlines
    Required
    Optional
    Description

    Defines the airline or alliance codes to be excluded from available airlines. An airline ID is an uppercase code (e.g., AC for Air Canada airline or ONEWORLD for oneworld alliance). Airline codes can be found on IATA. Multiple airlines can be combined by joining them with a comma. For example: AC,ONEWORLD.

    Note: if included_airlines and excluded_airlines are used together, included_airlines takes priority.

  • Name
    outbound_times
    Required
    Optional
    Description

    Defines the outbound departure and arrival times range. This parameter accepts a string containing up to 4 comma-separated numbers, where the first two numbers specify the departure time range and the last two numbers specify the arrival time range. Each number represents the beginning of an hour (e.g., 4,18,2,18 for a 4:00 AM - 7:00 PM departure and a 2:00 AM - 7:00 PM arrival). Default values are: 0,23,0,23.

  • Name
    return_times
    Required
    Optional
    Description

    Defines the return departure and arrival times range. This parameter also accepts up to 4 comma-separated numbers, where the first two specify the departure time range and the last two specify the arrival time range, following the same format as outbound_times (e.g., 4,18,2,18 for a 4:00 AM - 7:00 PM departure and a 2:00 AM - 7:00 PM arrival). Default values are: 0,23,0,23.

    Note: available only if flight_type set to round_trip.

  • Name
    emissions
    Required
    Optional
    Description

    Defines the emission level of the flight. Use 1 to show only flights with lower than typical emissions for that route.

  • Name
    included_connecting_airports
    Required
    Optional
    Description

    Defines connecting airports to be included. By default all connecting_airports are included. An airport ID is an uppercase 3-letter code (e.g., CDG for Paris Charles de Gaulle Airport). Multiple airports can be combined by joining them with a comma.

  • Name
    excluded_connecting_airports
    Required
    Optional
    Description

    Defines connecting airports to be excluded from available airports. An airport ID is an uppercase 3-letter code (e.g., CDG for Paris Charles de Gaulle Airport). Multiple airports can be combined by joining them with a comma.

  • Name
    layover_duration_min
    Required
    Optional
    Description

    Defines the minimum layover duration in minutes (e.g., 60 for 1 hours).

  • Name
    layover_duration_max
    Required
    Optional
    Description

    Defines the maximum layover duration in minutes (e.g., 240 for 4 hours). Max value is 1800 minutes (30 hours).

  • Name
    max_flight_duration
    Required
    Optional
    Description

    Defines the maximum flight duration in minutes (e.g., 240 for 4 hours).

  • Name
    separate_tickets
    Required
    Optional
    Description

    Defines whether to display separate tickets. The default value is 0. Set to 1 to hide separate and self-transfer tickets, or 0 to show them.

Number of Passengers

  • Name
    adults
    Required
    Optional
    Description

    Defines the number of adults. Default is 1.

    Note: Maximum number of passengers is 9.

  • Name
    children
    Required
    Optional
    Description

    Defines the number of children. Default is 0.

  • Name
    infants_in_seat
    Required
    Optional
    Description

    Defines the number of infants in seat. Default is 0.

  • Name
    infants_on_lap
    Required
    Optional
    Description

    Defines the number of infants on lap. Default is 0.

Localization

  • Name
    gl
    Required
    Optional
    Description

    The default parameter us defines the country of the search. Check the full list of supported Google Travel gl countries.

  • Name
    hl
    Required
    Optional
    Description

    The default parameter en defines the interface language of the search. Check the full list of supported Google Travel hl languages.

  • Name
    currency
    Required
    Optional
    Description

    Defines the currency of the returned prices. Default is USD. Check the full list of supported Google Travel currency values.

Engine

  • Name
    engine
    Required
    Required
    Description

    Parameter defines an engine that will be used to retrieve real-time data. It must be set to google_flights_calendar.

API key

  • Name
    api_key
    Required
    Required
    Description

    The api_key authenticates your requests. Use it as a query parameter (https://www.searchapi.io/api/v1/search?api_key=YOUR_API_KEY) or in the Authorization header (Bearer YOUR_API_KEY).

API Examples

Round Trip

Round Trip

The Google Flights Calendar API supports a maximum of 200 unique outbound and return date combinations in a single request. If the total number of combinations exceeds this limit, the API will return an empty response.

For example, specifying outbound_date_start=2025-02-21, outbound_date_end=2025-02-26, return_date_start=2025-02-27, and return_date_end=2025-03-27 results in 174 date combinations, which is within the limit. Ensure that your selected date ranges do not exceed 200 combinations to receive valid results.

GET
https://www.searchapi.io/api/v1/search?arrival_id=MAD&departure_id=JFK&engine=google_flights_calendar&flight_type=round_trip&outbound_date=2025-03-01&outbound_date_end=2025-03-03&outbound_date_start=2025-03-01&return_date=2025-03-08&return_date_end=2025-03-15&return_date_start=2025-03-08
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "google_flights_calendar",
  "flight_type": "round_trip",
  "departure_id": "JFK",
  "arrival_id": "MAD",
  "outbound_date": "2025-03-01",
  "return_date": "2025-03-08",
  "outbound_date_start": "2025-03-01",
  "outbound_date_end": "2025-03-03",
  "return_date_start": "2025-03-08",
  "return_date_end": "2025-03-15"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "calendar": [
    {
      "departure": "2025-03-13",
      "return": "2025-04-01",
      "price": 515
    },
    {
      "departure": "2025-03-13",
      "return": "2025-04-02",
      "price": 507
    },
    {
      "departure": "2025-03-13",
      "return": "2025-04-03",
      "price": 497,
      "is_lowest_price": true
    },
    {
      "departure": "2025-03-13",
      "return": "2025-04-04",
      "price": 497,
      "is_lowest_price": true
    },
    {
      "departure": "2025-03-13",
      "return": "2025-04-05",
      "price": 522
    },
    ...
  ]
}

One-Way

One-Way

For one_way flights, the Google Flights Calendar API allows a maximum search range of 200 days. If the difference between outbound_date_start and outbound_date_end exceeds 200 days, the API will return an empty response.

GET
https://www.searchapi.io/api/v1/search?arrival_id=MAD&departure_id=JFK&engine=google_flights_calendar&flight_type=one_way&outbound_date=2025-03-01&outbound_date_end=2025-03-24&outbound_date_start=2025-03-01
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "google_flights_calendar",
  "flight_type": "one_way",
  "departure_id": "JFK",
  "arrival_id": "MAD",
  "outbound_date": "2025-03-01",
  "outbound_date_start": "2025-03-01",
  "outbound_date_end": "2025-03-24"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "calendar": [
    {
      "departure": "2025-03-13",
      "price": 360
    },
    {
      "departure": "2025-03-14",
      "price": 335
    },
    {
      "departure": "2025-03-15",
      "price": 367
    },
    {
      "departure": "2025-03-16",
      "price": 271,
      "is_lowest_price": true
    },
    {
      "departure": "2025-03-17",
      "price": 312
    },
    ...
  ]
}

Has No Flights

Has No Flights
GET
https://www.searchapi.io/api/v1/search?arrival_id=LHR&departure_id=ANC&engine=google_flights_calendar&flight_type=round_trip&outbound_date=2025-03-01&outbound_date_end=2025-03-03&outbound_date_start=2025-03-01&return_date=2025-03-02&return_date_end=2025-03-04&return_date_start=2025-03-01
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "google_flights_calendar",
  "flight_type": "round_trip",
  "departure_id": "ANC",
  "arrival_id": "LHR",
  "outbound_date": "2025-03-01",
  "return_date": "2025-03-02",
  "outbound_date_start": "2025-03-01",
  "outbound_date_end": "2025-03-03",
  "return_date_start": "2025-03-01",
  "return_date_end": "2025-03-04"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "calendar": [
    {
      "departure": "2025-02-28",
      "return": "2025-03-05",
      "price": 1600
    },
    {
      "departure": "2025-02-28",
      "return": "2025-02-28",
      "has_no_flights": true
    },
    {
      "departure": "2025-03-01",
      "return": "2025-03-01",
      "has_no_flights": true
    },
    ...
  ]
}