| name | flight-ticket-search |
| description | Google Flights 공개 검색 표면을 무료로 조회해 항공권 후보, 예약 검색 링크, 날짜/월/연도별 최저가·평균가 비교를 보수적으로 제공한다. |
| license | MIT |
| metadata | {"category":"travel","locale":"ko-KR","phase":"v1"} |
Flight Ticket Search
What this skill does
fast-flights 기반으로 Google Flights의 공개 검색 결과를 조회해 항공권 후보를 정리한다. API key, 로그인, 결제, CAPTCHA 우회 없이 무료 공개 표면만 사용한다.
제공 기능:
- 편도/왕복 항공권 검색
- Google Flights 예약 검색 링크 생성
- 상위 후보 가격, 항공사, 출도착 시간, 소요시간, 경유 수 정리
- 날짜 범위, 월별, 연도별 샘플 비교
- 최저가, 평균가, 최고가 및
low/typical/high 가격 band 요약
예약 링크는 특정 판매자 결제 deep link가 아니라 Google Flights 검색 결과 링크다. 실제 구매·결제·좌석 선택은 사용자가 브라우저에서 직접 진행해야 한다.
When to use
- "항공권 조회해줘"
- "인천에서 나리타 다음 달 최저가"
- "6월 ICN-NRT 월별 비교"
- "올해랑 내년 6월 1일 항공권 가격 비교"
- "서울에서 도쿄 왕복 예약 링크 줘"
- "ICN-LAX 비즈니스 가격 대략 비교해줘"
When not to use
- 실제 예약/결제/취소/좌석지정 자동화
- 로그인 회원가, 카드 할인, 쿠폰, 마일리지 적용가 확정
- CAPTCHA, fingerprint, bot-block 우회
- 스카이스캐너 직접 조회. 현재
skyscanner.net은 기본 접속부터 CAPTCHA/403이 걸리므로 안정 skill provider로 쓰지 않는다.
Required inputs
최소 입력:
- 출발 공항 IATA 코드:
ICN, GMP, PUS 등
- 도착 공항 IATA 코드:
NRT, HND, LAX 등
- 출발일
YYYY-MM-DD 또는 비교할 월/범위
선택 입력:
- 왕복 귀국일
YYYY-MM-DD
- 성인 수, 기본 1명
- 좌석 등급:
economy, premium-economy, business, first
- 비교 샘플 방식: 월별
weekly 또는 daily
사용자가 도시명만 말하면 IATA 코드를 추론하되 애매하면 확인한다. 흔한 기본값은 다음처럼 처리한다.
- 서울/인천 국제선:
ICN
- 서울 국내선/제주:
GMP 우선, 사용자가 인천을 말하면 ICN
- 도쿄: 나리타
NRT 또는 하네다 HND 중 사용자가 지정하지 않으면 둘 중 하나를 확인한다.
- 제주:
CJU
Helper script
이 skill은 저장소 내 helper를 직접 실행한다.
python3 flight-ticket-search/scripts/flight_ticket_search.py --help
최초 실행 시 ~/.cache/k-skill/flight-ticket-search/venv에 fast-flights==2.2를 설치하고 그 venv로 재실행한다. 저장소에는 의존성 vendoring이나 API key를 넣지 않는다.
Single search
편도:
python3 flight-ticket-search/scripts/flight_ticket_search.py search \
--from ICN \
--to NRT \
--date 2026-06-01 \
--adults 1 \
--seat economy \
--limit 5 \
--format markdown
왕복:
python3 flight-ticket-search/scripts/flight_ticket_search.py search \
--from ICN \
--to NRT \
--date 2026-06-01 \
--return-date 2026-06-08 \
--adults 1 \
--seat economy \
--limit 5
응답 주요 필드:
meta.booking_search_url — Google Flights 예약 검색 링크meta.price_band — Google이 표시하는 low/typical/high 가격 bandstats.min_price, stats.avg_price, stats.max_priceflights[].name, departure, arrival, duration, stops, price_textflights[].quality — complete 또는 partial
Monthly comparison
월별 비교는 지정 월의 날짜들을 실제 검색해 각 날짜의 최저가/평균가를 비교한다.
빠른 기본값은 주 1회 샘플링이다.
python3 flight-ticket-search/scripts/flight_ticket_search.py compare-month \
--from ICN \
--to NRT \
--month 2026-06 \
--sample weekly \
--limit 5
일별 전체 조회가 필요하면 --sample daily를 쓴다. 다만 28~31회 요청이 발생하므로 rate limit을 위해 --sleep을 1.5초 이상 유지한다.
python3 flight-ticket-search/scripts/flight_ticket_search.py compare-month \
--from ICN \
--to NRT \
--month 2026-06 \
--sample daily \
--sleep 2 \
--limit 10
월별 비교 응답:
stats.min_price — 샘플 날짜 중 최저가stats.avg_of_daily_min — 날짜별 최저가의 평균stats.max_of_daily_min — 날짜별 최저가 중 최고값cheapest_dates[] — 가장 싼 날짜와 예약 검색 링크rows[] — 날짜별 성공/실패 및 요약
Custom range comparison
사용자가 "다음주부터 2주간", "6월 1일부터 20일까지"처럼 범위를 주면 날짜 범위 비교를 사용한다.
python3 flight-ticket-search/scripts/flight_ticket_search.py compare-range \
--from ICN \
--to BKK \
--start-date 2026-06-01 \
--end-date 2026-06-20 \
--step-days 3 \
--limit 5
--step-days 1은 일별 비교, 7은 주별 비교다.
Year comparison
연도 비교는 같은 월일을 여러 연도에 대해 조회한다.
python3 flight-ticket-search/scripts/flight_ticket_search.py compare-years \
--from ICN \
--to NRT \
--years 2026,2027 \
--month-day 06-01 \
--limit 5
주의: Google Flights가 너무 먼 미래 날짜를 표시하지 않으면 해당 연도는 실패로 기록한다. 실패한 날짜를 숨기지 말고 failures에 같이 보고한다.
Reservation link policy
booking_search_url은 Google Flights 검색 URL이다.- 특정 항공사/OTA 결제 단계 deep link를 자동 추출하거나 클릭하지 않는다.
- 결제·예약 확정·로그인·여권 정보 입력은 skill 범위 밖이다.
- 사용자가 예약까지 원하면 링크를 열어 직접 확인하도록 안내한다.
Response style
대표님에게는 짧게 핵심부터 보고한다.
좋은 형식:
ICN → NRT / 2026-06-01 / 성인 1명 / economy
가격 band: typical
최저/평균/최고: ₩129,800 / ₩254,000 / ₩684,400
예약 검색 링크: <url>
1. Jeju Air — 09:45 → 12:15 / 2h30m / 직항 / ₩129,800
2. Air Seoul — 09:20 → 11:50 / 2h30m / 직항 / ₩143,500
3. Air Premia — 08:50 → 11:20 / 2h30m / 직항 / ₩160,800
월별 비교:
ICN → NRT / 2026-06 weekly 샘플
최저: 6/1 ₩129,800
샘플 평균: ₩142,300
비싼 날: 6/22 ₩188,000
싼 날짜 TOP 3
1. 2026-06-01 — ₩129,800
2. 2026-06-08 — ₩135,000
3. 2026-06-15 — ₩144,000
파싱 누락 후보는 숨기지 말고 이렇게 표시한다.
항공편 상세 확인 불가 — 시간 확인 불가 / 가격 ₩228,700
※ Google Flights 응답에서 항공사·시간 파싱이 일부 누락됐습니다.
Failure modes
- Google Flights HTML/프론트엔드 구조 변경으로 항공사명·시간 파싱이 비거나 깨질 수 있다.
- 일부 노선은 가격만 나오고 항공편 상세가
partial로 떨어질 수 있다.
- 잘못된 IATA 코드, 동일 출도착 공항, 실제 항공편이 없는 구간은 실패한다.
- 너무 먼 미래 날짜는 upstream에서 결과가 없을 수 있다.
- 비교 기능은 날짜별 실시간 조회라 요청 수가 많다. daily 월별 비교는 30회 안팎의 요청이 발생한다.
fast-flights fallback이 외부 fetch helper를 쓰는 경우 401 no token provided가 날 수 있다. 동일 입력의 실사용성이 낮은 케이스면 사전 validation으로 막고, 정상 노선이면 잠시 후 재시도한다.
Verified discovery notes
2026-05-10 로컬 프로브 기준:
- Skyscanner home/API: CAPTCHA/403 blocked로 직접 provider 부적합.
- Kiwi Tequila API: 무료 계정 API key 필요. 기본 무료/no-key 경로는 아님.
- Google Flights +
fast-flights==2.2: 국내선/일본/동남아/미국/유럽/호주/남미 일부 성공.
- 추가 테스트 성공:
ICN-CJU, ICN-NRT, ICN-PVG, ICN-SIN, ICN-BKK, ICN-DXB, ICN-LAX, ICN-JFK, ICN-LHR, ICN-CDG, ICN-FRA, ICN-HKG, ICN-TPE, ICN-SYD, ICN-GRU, ICN↔NRT, GMP↔CJU, business, 성인 2명.
- 정상 실패/차단 대상:
GMP-ICN, ICN-ICN, invalid airport code.
Done when
- 출발/도착/날짜/좌석/인원 조건을 확인했다.
- 단일 검색이면 상위 후보와 예약 검색 링크를 제공했다.
- 비교 검색이면 샘플 방식과 최저/평균/최고, 싼 날짜 TOP을 제공했다.
- 가격은 조회 시점 기준이며 실제 결제가는 달라질 수 있음을 표시했다.
- 로그인/결제/CAPTCHA 우회는 하지 않았다.
