# Google Flights Smart Search — Natural-Language Flight Deals (`good-apis/google-flights-smart-search`) Actor

Type a trip in plain English and get the best flight deals across every date and destination combination. Pay per search — $2.50 / 1,000 searches; the natural-language translation is free.

- **URL**: https://apify.com/good-apis/google-flights-smart-search.md
- **Developed by:** [Danny](https://apify.com/good-apis) (community)
- **Categories:** Travel, AI
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.50 / 1,000 searches

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Google Flights Smart Search — Natural-Language Flight Deals

Type a trip in plain English and get the best flight deals across **every date and destination
combination** — not just one search. Describe origins, multiple destinations, a month or date window,
a range of nights, day-of-week rules, direct-only, cabin, budget, and passengers, all in one sentence.
The request is understood, expanded into many real Google Flights searches, and the cheapest options
are ranked for you.

**Billing: pay per search — $2.50 / 1,000 searches. The natural-language translation is free.** You set `max_searches` as
your spend cap; you are charged only for the flight searches actually run (`searches_performed` in the
output), never for the natural-language parsing.

### What you get

- Understands free text: "3–5 night trip from Tel Aviv to Barcelona or Athens in August, direct only".
- Explores combinations: multiple origins × destinations × dates in the window × nights range.
- Applies your filters: direct-only, max price, preferred/avoided airlines, departure time.
- Returns ranked deals (cheapest first) plus the cheapest option per destination.

### Input

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | The trip in plain English (origins, destinations, dates, nights, filters). |
| `max_searches` | integer | No | Spend cap: the most searches the fan-out runs (1–120, default 40). You are billed per search performed. |
| `top_n` | integer | No | How many ranked deals to return (1–100, default 20). |
| `currency` | string | No | Currency code for prices (default `USD`). |

#### Example input

```json
{
  "query": "3-5 night trip from Tel Aviv to Barcelona or Athens in August, direct only",
  "max_searches": 40,
  "top_n": 20,
  "currency": "USD"
}
````

```json
{
  "query": "one way from New York to London on 2026-08-20, business class",
  "max_searches": 5
}
```

### Output

Each dataset item is one ranked flight deal:

```json
{
  "origin": "TLV",
  "destination": "ATH",
  "outbound_date": "2026-08-27",
  "return_date": "2026-09-01",
  "nights": 5,
  "price": "$293",
  "price_numeric": 293,
  "airline": "Aegean",
  "stops": 0,
  "duration": "2 hr 5 min",
  "departure_time": "…",
  "arrival_time": "…",
  "booking_url": "https://www.google.com/travel/flights?tfs=…"
}
```

#### Fields

| Field | Description |
|-------|-------------|
| `origin` / `destination` | Airport IATA codes for this deal. |
| `outbound_date` / `return_date` | Dates for the itinerary (`return_date` null for one-way). |
| `nights` | Nights at the destination (round-trip). |
| `price` / `price_numeric` | Price as displayed and as a number, for sorting/filtering. |
| `airline` | Primary airline. |
| `stops` | Number of stops (0 = nonstop). |
| `duration` | Total travel time. |
| `booking_url` | Google Flights link for this itinerary. |

### Pagination

None to handle — one run explores up to `max_searches` combinations and returns the ranked deals
directly. Raise `max_searches` for broader coverage (and a higher bill); lower it to cap spend.

### Python client

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("good-apis/google-flights-smart-search").call(run_input={
    "query": "3-5 night trip from Tel Aviv to Barcelona or Athens in August, direct only",
    "max_searches": 40,
})
for deal in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(deal["origin"], "->", deal["destination"], deal["price"], deal["airline"])
```

### Node.js client

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });
const run = await client.actor('good-apis/google-flights-smart-search').call({
  query: '3-5 night trip from Tel Aviv to Barcelona or Athens in August, direct only',
  max_searches: 40,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const deal of items) console.log(deal.origin, '->', deal.destination, deal.price);
```

Install the client with `npm install apify-client`.

### FAQ

**How am I billed?** Per **search performed**, not per result. One free-text request expands into up
to `max_searches` real flight searches; you pay for the number actually run (returned as
`searches_performed`). The natural-language translation is free.

**How do I control cost?** With `max_searches`. It's a hard cap on how many searches the fan-out runs,
so it's your maximum spend for the run. A simple one-way query may only need 1 search even if the cap
is 40 — you're billed for the 1.

**Why did I get fewer searches than my cap?** Your request produced fewer combinations than the cap
(e.g. a single date and destination), so only those ran.

**Why fewer/zero deals than expected?** Filters (direct-only, max price, airline) can exclude flights,
and very tight windows may have little availability. Widen the dates/destinations or relax filters.

**Do I need a login or account for the source?** No — you only need your Apify token.

# Actor input Schema

## `query` (type: `string`):

Describe the trip in plain English — origins, destination(s), dates, nights, direct, cabin, budget, passengers. Relative dates work: 'tomorrow', 'this weekend', 'next Monday', 'next week', 'in 3 days'. Leave this blank to use one of the ready-made samples below.

## `example` (type: `string`):

Pick a ready-made example to see how it works. Used only if the free-text field above is left blank.

## `max_searches` (type: `integer`):

The most flight searches the fan-out will run. You are billed only for searches actually performed, so this is your spend cap. More searches = broader coverage of dates/destinations.

## `top_n` (type: `integer`):

How many ranked (cheapest-first) deals to return.

## `currency` (type: `string`):

Currency code for prices (e.g. USD, EUR, GBP).

## Actor input object example

```json
{
  "query": "one way from New York to London tomorrow, business class",
  "example": "",
  "max_searches": 40,
  "top_n": 20,
  "currency": "USD"
}
```

# Actor output Schema

## `deals` (type: `string`):

All ranked deals (cheapest first). Each item is one flight option.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "one way from New York to London tomorrow, business class"
};

// Run the Actor and wait for it to finish
const run = await client.actor("good-apis/google-flights-smart-search").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "query": "one way from New York to London tomorrow, business class" }

# Run the Actor and wait for it to finish
run = client.actor("good-apis/google-flights-smart-search").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "one way from New York to London tomorrow, business class"
}' |
apify call good-apis/google-flights-smart-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=good-apis/google-flights-smart-search",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Google Flights Smart Search — Natural-Language Flight Deals",
        "description": "Type a trip in plain English and get the best flight deals across every date and destination combination. Pay per search — $2.50 / 1,000 searches; the natural-language translation is free.",
        "version": "1.2",
        "x-build-id": "4zZ71qeBE4auHlmcQ"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/good-apis~google-flights-smart-search/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-good-apis-google-flights-smart-search",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/good-apis~google-flights-smart-search/runs": {
            "post": {
                "operationId": "runs-sync-good-apis-google-flights-smart-search",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/good-apis~google-flights-smart-search/run-sync": {
            "post": {
                "operationId": "run-sync-good-apis-google-flights-smart-search",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "query": {
                        "title": "Flight request (free text)",
                        "type": "string",
                        "description": "Describe the trip in plain English — origins, destination(s), dates, nights, direct, cabin, budget, passengers. Relative dates work: 'tomorrow', 'this weekend', 'next Monday', 'next week', 'in 3 days'. Leave this blank to use one of the ready-made samples below."
                    },
                    "example": {
                        "title": "…or pick a sample to start from",
                        "enum": [
                            "",
                            "3-5 night trip from Tel Aviv to Barcelona, Paris or London anytime in August, direct only",
                            "one way from New York to London next Monday, business class",
                            "round trip Madrid to New York, Dec 22 to Jan 2, premium economy",
                            "cheapest flight from Boston to Miami this weekend",
                            "weekend getaway from Berlin to Rome or Barcelona, 2 nights, any weekend in September, direct",
                            "family trip, 2 adults and 2 kids, Chicago to Orlando, 5 nights in June",
                            "round trip from London to Tokyo, 7-10 nights, next month, avoid layovers over 4 hours"
                        ],
                        "type": "string",
                        "description": "Pick a ready-made example to see how it works. Used only if the free-text field above is left blank.",
                        "default": ""
                    },
                    "max_searches": {
                        "title": "Max searches (spend cap)",
                        "minimum": 1,
                        "maximum": 120,
                        "type": "integer",
                        "description": "The most flight searches the fan-out will run. You are billed only for searches actually performed, so this is your spend cap. More searches = broader coverage of dates/destinations.",
                        "default": 40
                    },
                    "top_n": {
                        "title": "Number of deals to return",
                        "minimum": 1,
                        "maximum": 100,
                        "type": "integer",
                        "description": "How many ranked (cheapest-first) deals to return.",
                        "default": 20
                    },
                    "currency": {
                        "title": "Currency",
                        "type": "string",
                        "description": "Currency code for prices (e.g. USD, EUR, GBP).",
                        "default": "USD"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```