openapi: 3.0.0 info: title: Google Flights Deals API description: | The Google Flights Deals API surfaces cheap round-trip flight deals from a given origin, each ranked by how much cheaper it is than usual for that route, time of year, and trip length. It scrapes the google.com/travel/flights/deals discovery surface. **Note**: `departure_id` is required and selects the origin. The feed is origin-only by design: there is no `arrival_id`, and travel dates cannot be requested — the destinations and each deal's own cheapest dates are what the API returns. For a specific route or dates, use the Google Flights API. By default the API returns the cheapest deals to destinations anywhere. You can narrow that spread in one of two ways, and only one at a time: add a `q` prompt to have Google's AI curate the destinations (e.g. "beaches and islands"), or use the filters (`travel_class`, `stops`, `max_price`, `included_airlines`). Google honors a prompt or the filters, never both, so combining `q` with `max_price`, `included_airlines`, a `stops` other than `any`, a `travel_class` other than `economy`, or a passenger count above its default is rejected with a 400 rather than answered with results the filters were never applied to. Either way, narrowing may return fewer, or occasionally no, deals. Passenger counts (`adults`, `children`, `infants_in_seat`, `infants_on_lap`) scale displayed prices only when combined with a filter; on their own they leave the default deal feed unchanged. `currency` changes displayed prices and `hl` translates destination names/descriptions without changing which deals are returned. `gl` currently has no observable effect beyond being echoed into each deal's `booking_link`. **Cross-linking**: - Use a deal's destination kgmid with the Google Travel Explore Destination API to get detailed flight options for that destination. - Use a deal's destination `name` with the Google Hotels API `q` parameter to search for accommodations. Google Hotels takes free text, not a kgmid. - Use the booking_link (a Google Flights URL) to open the full itinerary in Google Flights. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Google Flights Deals Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Set to google_flights_deals to use this API. schema: type: string enum: ["google_flights_deals"] - name: departure_id in: query required: true description: 'Origin to find deals from. Accepts a 3-letter airport IATA code (e.g. JFK) or a location kgmid starting with /m/ or /g/ (e.g. /m/02_286 for New York).' schema: type: string - name: q in: query required: false description: "Free-text prompt describing the kind of destinations wanted (e.g. 'beaches and islands', 'places with great food'). Google's AI interprets it and curates the deals to matching destinations. Google honors a prompt or the filters, never both. Combining this with max_price, included_airlines, a stops other than any, a travel_class other than economy, or a passenger count above its default is rejected with a 400." schema: type: string - name: adults in: query required: false description: 'Number of adult passengers. Deal prices reflect this count only when the request also carries a filter; alone it leaves the default feed unchanged. All passenger counts combined cannot exceed 9. A count above the default cannot be combined with q.' schema: type: integer minimum: 1 maximum: 9 default: 1 - name: children in: query required: false description: 'Number of child passengers. Deal prices reflect this count only when the request also carries a filter; alone it leaves the default feed unchanged. All passenger counts combined cannot exceed 9. A count above the default cannot be combined with q.' schema: type: integer minimum: 0 maximum: 9 default: 0 - name: infants_in_seat in: query required: false description: 'Number of infants with their own seat. Deal prices reflect this count only when the request also carries a filter; alone it leaves the default feed unchanged. All passenger counts combined cannot exceed 9. A count above the default cannot be combined with q.' schema: type: integer minimum: 0 maximum: 9 default: 0 - name: infants_on_lap in: query required: false description: 'Number of infants on lap. Deal prices reflect this count only when the request also carries a filter; alone it leaves the default feed unchanged. All passenger counts combined cannot exceed 9. A count above the default cannot be combined with q.' schema: type: integer minimum: 0 maximum: 9 default: 0 - name: travel_class in: query required: false description: 'Cabin class for the deals. A non-economy class returns deals priced for that cabin, and cannot be combined with q.' schema: type: string default: "economy" enum: ["economy", "premium_economy", "business", "first_class"] - name: stops in: query required: false description: 'Maximum number of stops per flight. Any value other than any cannot be combined with q.' schema: type: string default: "any" enum: ["any", "nonstop", "one_stop_or_fewer", "two_stops_or_fewer"] - name: max_price in: query required: false description: 'Maximum round-trip deal price, in the requested currency. Only deals at or below this price are returned. Default is unlimited. Cannot be combined with q.' schema: type: integer minimum: 0 - name: included_airlines in: query required: false description: "Restricts deals to specific airlines or alliances by uppercase code (e.g. AC for Air Canada, ONEWORLD for the oneworld alliance). Combine multiple by joining them with a comma, for example AC,ONEWORLD. Cannot be combined with q." schema: type: string - name: currency in: query required: false description: Currency for prices. schema: type: string default: "USD" enum: ["ALL", "DZD", "ARS", "AMD", "AWG", "AUD", "AZN", "BSD", "BHD", "BYN", "BMD", "BAM", "BRL", "GBP", "BGN", "CAD", "XPF", "CLP", "CNY", "COP", "CRC", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "ILS", "JMD", "JPY", "JOD", "KZT", "KWD", "LBP", "MKD", "MYR", "MXN", "MDL", "MAD", "TWD", "NZD", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SEK", "CHF", "THB", "TRY", "UAH", "AED", "USD", "VND"] - name: hl in: query required: false description: 'Language code for the results. Translates destination names and descriptions; does not change which deals are returned.' schema: type: string default: "en-US" enum: ["af", "bs", "ca", "cs", "da", "de", "et", "en-GB", "en-US", "es", "es-419", "eu", "fil", "fr", "gl", "hr", "id", "is", "it", "sw", "lv", "lt", "hu", "ms", "nl", "no", "pl", "pt-BR", "pt-PT", "ro", "sq", "sk", "sl", "sr-Latn", "fi", "sv", "vi", "tr", "el", "bg", "mk", "mn", "ru", "sr", "uk", "ka", "iw", "ur", "ar", "fa", "am", "ne", "mr", "hi", "bn", "pa", "gu", "ta", "te", "kn", "ml", "si", "th", "lo", "km", "ko", "ja", "zh-CN", "zh-TW"] - name: gl in: query required: false description: 'Country code. Currently has no observable effect on the returned deals, prices, or localization. It is only echoed into each deal''s booking_link.' schema: type: string default: "US" enum: ["AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AG", "AR", "AM", "AU", "AT", "AZ", "BS", "BH", "BD", "BY", "BE", "BZ", "BJ", "BT", "BO", "BA", "BW", "BR", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "CF", "TD", "CL", "CN", "CO", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "EE", "ET", "FJ", "FI", "FR", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GT", "GG", "GY", "HT", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LY", "LI", "LT", "LU", "MG", "MW", "MY", "MV", "ML", "MT", "MU", "MX", "FM", "MD", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NZ", "NI", "NE", "NG", "NU", "MK", "NO", "OM", "PK", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SK", "SI", "SB", "SO", "ZA", "KR", "ES", "LK", "SH", "VC", "SR", "SE", "CH", "TW", "TJ", "TZ", "TH", "TL", "TG", "TO", "TT", "TN", "TR", "TM", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VE", "VN", "ZM", "ZW"] responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' deals: type: array description: List of flight deals from the origin, ranked by savings percentage (largest savings first). items: $ref: '#/components/schemas/Deal' error: type: string description: Error message if no results found SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: "Unique identifier for the search request" status: type: string description: "Status of the search request" created_at: type: string format: date-time description: "Timestamp when the search was created" request_time_taken: type: number description: "Time taken to make the request in seconds" parsing_time_taken: type: number description: "Time taken to parse the results in seconds" total_time_taken: type: number description: "Total time taken for the search in seconds" request_url: type: string description: "Google Flights Deals URL for this search" html_url: type: string description: "URL to view HTML results" json_url: type: string description: "URL to view JSON results" SearchParameters: type: object properties: engine: type: string description: Engine used for the search q: type: string description: AI prompt used to curate destinations departure_id: type: string description: Origin location identifier adults: type: string description: Number of adult passengers children: type: string description: Number of child passengers infants_in_seat: type: string description: Number of infants with own seat infants_on_lap: type: string description: Number of infants on lap travel_class: type: string description: Cabin class stops: type: string description: Maximum number of stops per flight max_price: type: string description: Maximum round-trip deal price in the requested currency included_airlines: type: string description: Airlines or alliances the deals are restricted to currency: type: string description: Currency code hl: type: string description: Language code gl: type: string description: Country code Deal: type: object required: [position, destination, origin, outbound_date, price, booking_link, is_round_trip, is_multiple_airlines] properties: position: type: integer description: Rank of the deal in the results (1-based), ordered by savings percentage. destination: $ref: '#/components/schemas/Destination' origin: $ref: '#/components/schemas/Origin' outbound_date: type: string description: 'Outbound flight date for this deal in YYYY-MM-DD format.' return_date: type: string description: 'Return flight date for this deal in YYYY-MM-DD format.' trip_length_days: type: integer description: Number of nights between the outbound and return dates. price: type: integer description: Deal price for the round trip, in the requested currency. typical_price: type: integer description: Typical price for this route and trip, in the requested currency. savings_percentage: type: integer description: Google's own curated "cheaper than usual" badge for the deal, as a percentage. Not computed from price and typical_price; Google withholds it on deals with no baseline to compare against. savings_amount: type: integer description: Absolute saving versus the typical price (typical_price - price), in the requested currency. Present whenever the deal is priced below its typical price. stops: type: integer description: Number of stops on the outbound flight (0 = nonstop). flight_duration: type: string description: Human-readable outbound flight duration (e.g. "5hr 20min"). duration: type: integer description: Outbound flight duration in minutes. airline: type: string description: Operating airline name. Omitted, along with `airline_code`, when multiple carriers serve the route and dates (see `is_multiple_airlines`). airline_code: type: string description: Operating airline IATA code. Omitted, along with `airline`, when multiple carriers serve the route and dates (see `is_multiple_airlines`). booking_link: type: string description: Google Flights URL to view and book the full itinerary. is_round_trip: type: boolean description: Whether the deal is a round trip. Deals are always round trip. is_multiple_airlines: type: boolean description: Whether multiple carriers serve this route and its dates, in which case Google names no single airline and `airline`/`airline_code` are omitted. Destination: type: object required: [name, country, airport_code, kgmid] properties: name: type: string description: Destination city name. country: type: string description: Destination country name. airport_code: type: string description: Destination airport IATA code. kgmid: type: string description: Destination Knowledge Graph machine ID. Usable as arrival_id in the Google Flights and Google Travel Explore Destination APIs (not Google Hotels, which takes free text). image: type: string description: Thumbnail image URL for the destination. tagline: type: string description: Short tagline describing the destination. description: type: string description: Longer description of the destination. Origin: type: object required: [airport_code] properties: airport_code: type: string description: Origin airport IATA code the deal departs from. ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong