Google Flights Search

Fetch live flight data from Google Flights via SearchAPI.io, then score and rank results using the flight-scoring skill, then ALWAYS save the search via the flight-price-monitor skill for automatic price tracking.

Install

CODEBLOCK0

Requirements

• - Python 3 — uses only stdlib (urllib, json, argparse). No pip installs needed.
• SearchAPI.io account — free tier includes 100 requests/month. Sign up here.
• SEARCHAPI_KEY — get your API key from SearchAPI.io after registering, then add it to .env at the project root. OpenClaw loads it automatically.

---

Quick Reference

Situation	Action
User asks for flights	Run search_searchapi.py, score results, then save via INLINECODE7
Round-trip search

Add --return-date AND --top 5 to get return flight details | | User says "around [date]" | Use --days 3 centered on that date | | User says "cheapest in March" | Use --days 3 and pick a representative start date | | Specific date | Use --days 1 (or --days 3 for ±1 flexibility) | | Direct only | Add --stops 0 | | Multi-passenger | Add --adults N |

---

Usage

CODEBLOCK1

All Parameters

Parameter	Required	Default	Description
INLINECODE16	Yes	—	Origin IATA code (e.g. TLV)
INLINECODE18

Yes | — | Destination IATA code (e.g. LON, LHR, LGW) | | --date | Yes | — | Outbound date YYYY-MM-DD | | --return-date | No | — | Return date YYYY-MM-DD (makes it a round-trip search) | | --days | No | 1 | Number of days to search forward from --date (max: 3) | | --currency | No | USD | Currency code (USD, EUR, ILS) | | --adults | No | 1 | Number of adult passengers | | --stops | No | any | 0 = direct only, 1 = up to 1 stop, 2 = up to 2 stops | | --class | No | economy | 1=economy, 2=premiumeconomy, 3=business, 4=firstclass | | --top | No | — | Auto-fetch return flight details for top N outbound results. Use --top 5 for round-trips. | | --departure-token | No | — | Fetch return flights for a specific outbound (advanced, rarely needed directly) | | --booking-token | No | — | Fetch booking options (real airline/OTA URLs) for a specific flight using its booking_token |

Destination codes

Google Flights accepts:

• - Airport codes: LHR, CDG, INLINECODE52
• City codes: LON (all London airports), PAR (all Paris), INLINECODE55

Use city codes when the user hasn't specified a preferred airport.

---

Output Format

The script prints JSON to stdout.

One-Way / Outbound Only

CODEBLOCK2

Round-Trip with --top 5 (includes return flight details)

When --top N is used with --return-date, each of the top N outbound results includes a nested return_flight object with full return leg details:

CODEBLOCK3

Important: The price is the combined round-trip price (same on both outbound and return_flight). The return_flight object has its own airline, flight number, times, layovers, and stops — use all of these when formatting results.

Booking Token Lookup (--booking-token)

After scoring, use the booking_token from each top result to fetch real booking URLs.

You must pass the same --from, --to, --date used in the original search. For round-trips, also pass --return-date.

CODEBLOCK4

Returns:

CODEBLOCK5

Use the first option whose book_with matches the airline (direct airline link). If no airline match, use the first option. If --booking-token fails or returns no options, fall back to vendor-booking-link.

---

Full Workflow

CODEBLOCK6

Always score before presenting. Never dump raw JSON to the user.
Always include booking links. Prefer booking_token for real URLs; fall back to vendor-booking-link if unavailable. Never link to Google Flights or aggregators.
Round-trips MUST use --top 5 to get return flight details. Without --top, only outbound info is returned.

Step 8: Save Price Monitor (MANDATORY)

After presenting results, ALWAYS save the search for price monitoring. Build a compact snapshot from the top 10-15 flights as "Airline|FlightNum|DepTime": price pairs, then run:

CODEBLOCK7

• - --user-id: The peer ID from the session (e.g. whatsapp:+972523866782). If unknown, use the user's name.
• INLINECODE78: The channel the user is on (whatsapp, telegram, etc.)
• INLINECODE81: The user's address on that channel. Use last if unknown.
• INLINECODE83: JSON object of "Airline|FlightNum|HH:MM": price pairs from the results.
• Omit --return-date if it was a one-way search.

This overwrites any previous monitor for this user. A cron job checks every 2 hours and notifies the user of price changes.

---

Mapping Script Output → Scoring Inputs

Scoring field	Script field
Price	INLINECODE86
Stops

stops |
| Departure time | departure_time (extract HH:MM) |
| Arrival time | arrival_time (extract HH:MM) |
| Overnight flag | overnight |
| Duration | duration_minutes |
| Risky layover | min_layover_minutes < 60 |
| Airline | airline |
| Flight number | flight_number |
| Route | origin → destination (IATA codes) |

---

Error Handling

Error	Cause	Fix
INLINECODE97	Missing .env entry	Add SEARCHAPI_KEY=your_key to INLINECODE100
INLINECODE101

Invalid API key | Check key at searchapi.io |
| HTTP 429 | Rate limit hit | Wait and retry, or use --days in smaller batches |
| No results for a date | Route not available | Try adjacent dates or different destination airport code |

---

Notes

• - El Al does not fly on Shabbat — Friday evening and Saturday flights from TLV won't appear for El Al.
• Secondary airports: Wizz/Ryanair use LTN, STN, BGY etc. — when the script returns results from these, mention the airport to the user.
• Prices are per-person unless --adults is set. For groups, multiply accordingly and note total.
• Round-trip: Use --return-date YYYY-MM-DD --top 5 to search round-trip and auto-fetch return flight details for the top 5 results.