7# Google Flights Search
8
9Search Google Flights via agent-browser to find flight prices, schedules, and availability.
10
11## When to Use
12
13- User asks to search/find/compare flights or airfare
14- User wants to know flight prices between cities
15- User asks about flight schedules or availability
16- User wants to find the cheapest flight for specific dates
17
18## When NOT to Use
19
20- **Completing purchases**: This skill finds flights and extracts booking links, but do not attempt to complete a purchase on a booking site.
21- **Hotels/rental cars**: Use other tools for non-flight travel searches.
22- **Historical price data**: Google Flights shows current prices, not historical.
23
24## Session Convention
25
26- **Economy only** (default for domestic): --session flights
27- **Economy + Business comparison** (international or user requests): --session econ and --session biz
28- **Interactive fallback**: --session flights
29
30## Domestic vs International Detection
31
32**Domestic flights default to economy only.** Business class on US domestic routes is typically 3-5x the price and rarely worth showing unless asked.
33
34A flight is **domestic** if both origin and destination are US airports. Common US IATA codes: ATL, BOS, BWI, CLT, DEN, DFW, DTW, EWR, FLL, HNL, IAD, IAH, JFK, LAS, LAX, LGA, MCO, MDW, MIA, MSP, OAK, ORD, PHL, PHX, PDX, SAN, SEA, SFO, SJC, SLC, TPA.
35
36**When to show business class:**
37- International flights (always show economy + business comparison)
38- User explicitly asks for "business class" or "business"
39- User asks to "compare cabins" or "show all classes"
40
41**When to skip business class:**
42- Domestic US flights (economy only by default)
43- User explicitly asks for "economy" or "cheapest"
44
45## Fast Path: URL-Based Search (Preferred)
46
47Construct a URL with a natural language ?q= parameter. Loads results directly — **3 commands total**.
48
49### URL Template
50
51```
52https://www.google.com/travel/flights?q=Flights+from+{ORIGIN}+to+{DEST}+on+{DATE}[+returning+{DATE}][+one+way][+business+class][+N+passengers]
53```
54
55### Default: Economy Only (Domestic)
56
57For domestic flights, run a single session - **2 tool calls total**:
58
59```bash
60# Open and wait in one call
61agent-browser --session flights open "https://www.google.com/travel/flights?q=Flights+from+MIA+to+SFO+on+2026-04-28+returning+2026-04-30" && agent-browser --session flights wait --load networkidle
62
63# Snapshot results
64agent-browser --session flights snapshot -i
65# Keep session alive for booking links
66```
67
68Then present results in **compact list format** (see Output Format section below).
69
70### Economy + Business Comparison (International)
71
72For international flights, run two parallel sessions to show the price delta:
73
74```bash
75# Open both and wait in parallel
76(agent-browser --session econ open "https://www.google.com/travel/flights?q=Flights+from+BKK+to+NRT+on+2026-03-20+returning+2026-03-27" && agent-browser --session econ wait --load networkidle) &
77(agent-browser --session biz open "https://www.google.com/travel/flights?q=Flights+from+BKK+to+NRT+on+2026-03-20+returning+2026-03-27+business+class" && agent-browser --session biz wait --load networkidle) &
78wait
79
80# Snapshot both in parallel
81agent-browser --session econ snapshot -i &
82agent-browser --session biz snapshot -i &
83wait
84
85# Close biz (only needed for delta); keep econ alive for booking links
86agent-browser --session biz close
87```
88
89**Matching logic**: Match flights by airline name and departure time. Not all economy flights have a business equivalent (budget carriers like ZIPAIR, Air Japan don't offer business). Show "-" when no business match exists.
90
91**Tip**: When an airline appears in business results but not economy (e.g., Philippine Airlines), it may operate business-only pricing on that route. Include it with "-" for economy.
92
93### One Way
94
95Add +one+way to the URL. For international, run both economy and business in parallel:
96
97```bash
98# Domestic (economy only)
99agent-browser --session flights open "https://www.google.com/travel/flights?q=Flights+from+LAX+to+JFK+on+2026-04-15+one+way" && agent-browser --session flights wait --load networkidle
100
101# International (economy + business comparison)
102(agent-browser --session econ open "https://www.google.com/travel/flights?q=Flights+from+LAX+to+LHR+on+2026-04-15+one+way" && agent-browser --session econ wait --load networkidle) &
103(agent-browser --session biz open "https://www.google.com/travel/flights?q=Flights+from+LAX+to+LHR+on+2026-04-15+one+way+business+class" && agent-browser --session biz wait --load networkidle) &
104wait
105```
106
107### When User Asks for Business Only
108
109If the user specifically asks for business class (not a comparison), run just the business session:
110
111```bash
112agent-browser --session flights open "https://www.google.com/travel/flights?q=Flights+from+JFK+to+CDG+on+2026-06-01+returning+2026-06-15+business+class"
113agent-browser --session flights wait --load networkidle
114agent-browser --session flights snapshot -i
115# Keep session alive for booking links
116```
117
118### First Class / Multiple Passengers
119
120```bash
121agent-browser --session flights open "https://www.google.com/travel/flights?q=Flights+from+JFK+to+CDG+on+2026-06-01+returning+2026-06-15+first+class+2+adults+1+child"
122agent-browser --session flights wait --load networkidle
123agent-browser --session flights snapshot -i
124# Keep session alive for booking links
125```
126
127### What Works via URL
128
129| Feature | URL syntax | Status |
130|---------|-----------|--------|
131| Round trip | +returning+YYYY-MM-DD | Works |
132| One way | +one+way | Works |
133| Business class | +business+class | Works |
134| First class | +first+class | Works |
135| N passengers (adults) | +N+passengers | Works |
136| Adults + children | +2+adults+1+child | Works |
137| IATA codes | BKK, NRT, LAX | Works |
138| City names | Bangkok, Tokyo | Works |
139| Dates as YYYY-MM-DD | 2026-03-20 | Works (best) |
140| Natural dates | March+20 | Works |
141| **Premium economy** | +premium+economy | **Fails** |
142| **Multi-city** | N/A | **Fails** |
143
144### What Requires Interactive Fallback
145
146- **Premium economy** cabin class
147- **Multi-city** trips (3+ legs)
148- **Infant passengers** (seat vs lap distinction)
149- **URL didn't load results** (consent banner, CAPTCHA, locale issue)
150
151### Reading Results from Snapshot
152
153Each flight appears as a link element with a full description:
154
155```
156link "From 20508 Thai baht round trip total. Nonstop flight with Air Japan.
157 Leaves Suvarnabhumi Airport at 12:10 AM on Friday, March 20 and arrives
158 at Narita International Airport at 8:15 AM on Friday, March 20.
159 Total duration 6 hr 5 min. Select flight"
160```
161
162Parse economy + business snapshots into the **compact list format**:
163
164```
1651. JAL — Nonstop · 5h 55m
166 8:05 AM → 4:00 PM
167 Economy: THB 23,255 · Business: THB 65,915 (+183%)
168
1692. THAI — Nonstop · 5h 50m
170 10:30 PM → 6:20 AM+1
171 Economy: THB 28,165 · Business: THB 75,000 (+166%)
172
1733. Air Japan — Nonstop · 6h 05m
174 12:10 AM → 8:15 AM
175 Economy: THB 20,515 · Business: —
176
1774. ZIPAIR — Nonstop · 5h 45m
178 11:45 PM → 7:30 AM+1
179 Economy: THB 21,425 · Business: —
180```
181
182**Matching**: Pair economy and business results by airline + departure time. Budget carriers without business class show "—". Include "Best"/"Cheapest" labels from Google when present.
183
184## Booking Options Handoff
185
186After presenting the results table, **always offer booking links**: "Want booking links for any of these? Just say which one."
187
188When the user picks a flight, extract booking options by clicking the flight's link element in the snapshot. Google Flights shows a panel with booking providers (airlines, OTAs) each with a price and a "Continue" link to the booking site.
189
190### Workflow
191
192```bash
193# User picks flight #N — click the corresponding link from the results snapshot
194# Use --session flights (domestic) or --session econ (international comparison)
195agent-browser --session flights click @eN
196agent-browser --session flights wait 3000
197agent-browser --session flights snapshot -i
198```
199
200The booking panel snapshot will show link elements like:
201
202```
203link "Book with Emirates THB 28,960" → href="https://..."
204link "Book with Booking.com THB 29,512" → href="https://..."
205link "Book with Teaflight THB 28,171" → href="https://..."
206```
207
208Extract the provider name, price, and href URL from each link.
209
210### Output Format
211
212```
213📋 Booking Options for JAL BKK→NRT (5h 55m, Nonstop)
214
215| Provider | Price | Book |
216|----------|-------|------|
217| Emirates | THB 28,960 | [Continue](https://...) |
218| Booking.com | THB 29,512 | [Continue](https://...) |
219| Teaflight | THB 28,171 | [Continue](https://...) |
220```
221
222### Notes
223
224- **Session lifecycle**: Keep the results session (flights or econ) alive for booking links. For international comparisons, close --session biz immediately after extracting prices. Close the results session after the user gets booking links or declines.
225- **If booking panel fails to load**: Re-snapshot and wait longer before retrying.
226
227## Interactive Workflow (Fallback)
228
229Use for multi-city, premium economy, or when the URL path fails.
230
231### Open and Snapshot
232
233```bash
234agent-browser --session flights open "https://www.google.com/travel/flights"
235agent-browser --session flights wait 3000
236agent-browser --session flights snapshot -i
237```
238
239If a consent banner appears, click "Accept all" or "Reject all" first.
240
241### Set Trip Type (if not Round Trip)
242
243```bash
244agent-browser --session flights click @eN # Trip type combobox ("Round trip")
245agent-browser --session flights snapshot -i
246agent-browser --session flights click @eN # "One way" or "Multi-city"
247agent-browser --session flights wait 1000
248agent-browser --session flights snapshot -i
249```
250
251### Set Cabin Class / Passengers (if non-default)
252
253**Cabin class:**
254```bash
255agent-browser --session flights click @eN # Cabin class combobox
256agent-browser --session flights snapshot -i
257agent-browser --session flights click @eN # Select class
258agent-browser --session flights wait 1000
259agent-browser --session flights snapshot -i
260```
261
262**Passengers:**
263```bash
264agent-browser --session flights click @eN # Passengers button
265agent-browser --session flights snapshot -i
266agent-browser --session flights click @eN # "+" for Adults/Children/Infants
267agent-browser --session flights snapshot -i
268agent-browser --session flights click @eN # "Done"
269agent-browser --session flights wait 1000
270agent-browser --session flights snapshot -i
271```
272
273### Enter Airport (Origin or Destination)
274
275```bash
276agent-browser --session flights click @eN # Combobox field
277agent-browser --session flights wait 1000
278agent-browser --session flights snapshot -i
279agent-browser --session flights fill @eN "BKK"
280agent-browser --session flights wait 2000 # CRITICAL: wait for autocomplete
281agent-browser --session flights snapshot -i
282agent-browser --session flights click @eN # Click suggestion (NEVER press Enter)
283agent-browser --session flights wait 1000
284agent-browser --session flights snapshot -i
285```
286
287### Set Dates
288
289```bash
290agent-browser --session flights click @eN # Date textbox
291agent-browser --session flights wait 1000
292agent-browser --session flights snapshot -i
293# Calendar shows dates as buttons: "Friday, March 20, 2026"
294agent-browser --session flights click @eN # Click target date
295agent-browser --session flights wait 500
296agent-browser --session flights snapshot -i
297# Click "Done" to close calendar
298agent-browser --session flights click @eN # "Done" button
299agent-browser --session flights wait 1000
300agent-browser --session flights snapshot -i
301```
302
303### Search
304
305**"Done" only closes the calendar. You MUST click "Search" separately.**
306
307```bash
308agent-browser --session flights click @eN # "Search" button
309agent-browser --session flights wait --load networkidle
310agent-browser --session flights snapshot -i
311# Keep session alive for booking links
312```
313
314### Multi-City Specifics
315
316After selecting "Multi-city" trip type, the form shows one row per leg:
317
318- Each leg has: origin combobox, destination combobox, departure date textbox
319- **Origins auto-fill** from the previous leg's destination
320- Click "Add flight" to add more legs (default: 2 legs shown)
321- Click "Remove flight from X to Y" buttons to remove legs
322- Results show flights for the **first leg**, with prices reflecting the **total multi-city cost**
323
324Fill each leg's destination + date in order, then click "Search".
325
326## Output Format
327
328**Always use compact list format** — never markdown tables. Output is typically displayed in chatbot interfaces (Telegram, etc.) where tables render poorly.
329
330### Economy + Business comparison (default)
331
332```
3331. JAL — Nonstop · 5h 55m
334 8:05 AM → 4:00 PM
335 Economy: THB 23,255 · Business: THB 65,915 (+183%)
336
3372. THAI — Nonstop · 5h 50m
338 10:30 PM → 6:20 AM+1
339 Economy: THB 28,165 · Business: THB 75,000 (+166%)
340
3413. Air Japan — Nonstop · 6h 05m
342 12:10 AM → 8:15 AM
343 Economy: THB 20,515 · Business: —
344```
345
346### Economy only
347
348```
3491. JAL — Nonstop · 5h 55m
350 8:05 AM → 4:00 PM · THB 23,255
351
3522. THAI — Nonstop · 5h 50m
353 10:30 PM → 6:20 AM+1 · THB 28,165
354```
355
356### Format rules
357
358- One flight per numbered block, blank line between flights
359- Line 1: Airline — Stops · Duration
360- Line 2: Departure → Arrival times
361- Line 3: Prices (economy, business delta if applicable)
362- No code blocks around the flight list — plain text reads best
363- Keep the "Best value" recommendation as a plain text paragraph after the list
364
365## Key Rules
366
367| Rule | Why |
368|------|-----|
369| Prefer URL fast path | 2 tool calls (domestic) or 3 (international) vs 15+ interactive |
370| Chain open+wait with && | Eliminates a round-trip between tool calls |
371| Skip business for domestic | US domestic business is 3-5x price, rarely useful unless asked |
372| Parallel snapshots with & + wait | Both snapshots run concurrently for international |
373| wait --load networkidle | Smarter than fixed wait 5000 - returns when network settles |
374| Use fill not type for airports | Clears existing text first |
375| Wait 2s after typing airport codes | Autocomplete needs API roundtrip |
376| Always CLICK suggestions, never Enter | Enter is unreliable for autocomplete |
377| Re-snapshot after every interaction | DOM changes invalidate refs |
378| "Done" ≠ Search | Calendar Done only closes picker |
379| After presenting results, offer booking links | Users almost always want to book - prompt them |
380| Keep results session alive; close biz after results | Results session needed for booking clicks; biz only for delta |
381
382## Troubleshooting
383
384**Consent popups**: Click "Accept all" or "Reject all" in the snapshot.
385
386**URL fast path didn't work**: Fall back to interactive. Some regions/locales handle ?q= differently.
387
388**No results**: Verify airports (check combobox labels), dates in the future, or wait longer.
389
390**Bot detection / CAPTCHA**: Inform user. Do NOT solve CAPTCHAs. Retry after a short wait.
391
392## Deep-Dive Reference
393
394See [references/interaction-patterns.md](references/interaction-patterns.md) for:
395- Full annotated walkthrough (every command + expected output)
396- Airport autocomplete failure modes and recovery
397- Date picker calendar navigation
398- Multi-city searches
399- Scrolling for more results
400