flight-ticket-search

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 가격 band
• stats.min_price, stats.avg_price, stats.max_price
• flights[].name, departure, arrival, duration, stops, price_text
• flights[].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 우회는 하지 않았다.