# Google Flights Scraper & Fare Intelligence (`azzarilabs/google-flights-fare-intelligence`) Actor

Extract public Google Flights fares, schedules, airlines, stops, and explainable fare comparisons without API keys, login, or paid proxies.

- **URL**: https://apify.com/azzarilabs/google-flights-fare-intelligence.md
- **Developed by:** [Azzari Labs](https://apify.com/azzarilabs) (community)
- **Categories:** Travel, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 valid flight result delivereds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Scraper & Fare Intelligence

Extract public Google Flights itineraries and round-trip fares. No API key, login, paid proxy, or external paid service is required. The Actor returns a clean Dataset, a machine-readable `OUTPUT` summary, and a responsive `REPORT.html` for fare comparison.

### What it delivers

Each valid result includes:

- origin and destination IATA codes;
- requested departure and return dates;
- airline, departure and arrival time, duration, and stops;
- round-trip price and explicitly observed currency;
- flight number and cabin class only when Google exposes them;
- a Google Flights URL;
- a deterministic `Low`, `Typical`, `High`, or `N/A` value signal;
- evidence warnings when a field cannot be confirmed.

### Quick start

```json
{
  "origin": "GUA",
  "destination": "MIA",
  "adults": 1,
  "max_results": 10,
  "currency": "USD"
}
```

Dates are intentionally omitted from the sample. At runtime, departure defaults to today plus 14 days and return defaults to seven days after departure. This keeps the public sample evergreen and ADWIC-safe.

Other route examples:

```json
{
  "origin": "JFK",
  "destination": "LAX",
  "departure_date": "2026-10-20",
  "return_date": "2026-10-27",
  "adults": 2,
  "max_results": 20,
  "currency": "USD",
  "cabin_class": "economy"
}
```

Use future dates when providing dates explicitly. Supported cabin requests are `economy`, `premium_economy`, `business`, and `first`.

### Outputs

- **Dataset:** one typed record per validated, deduplicated fare.
- **OUTPUT:** status, route, dates, result count, comparable sample, median/range, currency, acquisition diagnostics, and warnings.
- **REPORT.html:** responsive route summary and fare table with airline, times, duration, stops, price, Value Signal, Google Flights link, methodology, and warnings.

An empty Google response or isolated HTTP failure completes as a clean `EMPTY` result with diagnostics. It does not create fabricated fares.

### Fare intelligence

Fare intelligence runs only when at least three delivered fares have one common, explicitly observed currency.

- `Low`: price is at or below 85% of the median.
- `Typical`: price is between the Low and High thresholds.
- `High`: price is at or above 115% of the median.
- `N/A`: insufficient or mixed-currency evidence.

The calculation is deterministic and reproducible. It is a comparison of observed results, not a prediction and not a guarantee that a fare is bookable.

### Currency and optional evidence

Currency comes from visible Google evidence such as “US dollars” or “euros”. The Actor never infers USD from an airport or country. When currency cannot be confirmed, the record uses `null` and emits `currency_evidence_unavailable`.

`flight_number` and `cabin_class` also remain `null` unless the result exposes those values explicitly. The generated Google Flights URL is a search URL, not a fabricated airline booking link.

### Acquisition and privacy

The Actor uses Python's standard HTTP client for bounded requests to public Google Flights pages. It has two isolated HTTP URL strategies, a 25-second timeout per strategy, and no browser runtime in the candidate. It does not bypass CAPTCHA, use residential proxies, call paid APIs, or require user credentials or private secrets.

Google can change public markup, localize responses, throttle traffic, or update fares between requests. Verify final availability, baggage rules, itinerary details, and price before booking.

### Billing contract

The prepared Pay-Per-Event event is `flight-result`. A result is billable only after a valid deduplicated record with explicit currency evidence has actually been delivered. Errors, timeouts, blocked responses, discarded candidates, duplicates, empty results, currency-unconfirmed records, and undelivered records are not billable.

The Pay-Per-Event price is **USD 0.003 per valid `flight-result` delivered**.

### Local QA

Run the deterministic suite from this directory:

```powershell
& "C:\path\to\python.exe" -m unittest discover -s tests -v
```

Fixtures are reduced evidence captures from the 2026-09-12 technical gate for GUA→MIA, JFK→LAX, and GUA→MAD. They contain public semantic flight-card text, not competitor code.

# Actor input Schema

## `origin` (type: `string`):

Three-letter IATA airport code, for example GUA or JFK.

## `destination` (type: `string`):

Three-letter IATA airport code, for example MIA or LAX.

## `departure_date` (type: `string`):

ISO date YYYY-MM-DD. If omitted, the Actor uses the run date plus 14 days.

## `return_date` (type: `string`):

ISO date YYYY-MM-DD. If omitted, the Actor uses seven days after departure.

## `adults` (type: `integer`):

Number of adult travelers.

## `max_results` (type: `integer`):

Maximum number of valid deduplicated flight results to deliver.

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

Requested ISO 4217 currency, such as USD or EUR. Output currency is populated only from explicit Google evidence.

## `cabin_class` (type: `string`):

Requested cabin. The per-flight field remains null unless Google exposes cabin evidence.

## Actor input object example

```json
{
  "origin": "GUA",
  "destination": "MIA",
  "adults": 1,
  "max_results": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `output` (type: `string`):

No description

## `report` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("azzarilabs/google-flights-fare-intelligence").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("azzarilabs/google-flights-fare-intelligence").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call azzarilabs/google-flights-fare-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,azzarilabs/google-flights-fare-intelligence"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bX5dvHOHoRq186hsc/builds/56zzgJDIuboGBYLrv/openapi.json