Flights — Airfare Search via Travelpayouts/Aviasales

Prerequisites

Environment variable TRAVELPAYOUTS_TOKEN must be set with a valid Travelpayouts API token.

Quick Reference

Usage

1. Resolve IATA codes

If the user provides a city name instead of an IATA code, resolve it first:

python3 scripts/search_flights.py --lookup "Istanbul"

Pick the most relevant result's code field.

2. Search flights on a specific date

python3 scripts/search_flights.py --from MOW --to LED --date 2026-04-15 --return 2026-04-20

Add --direct for non-stop only. Add --limit N to cap results (default 10).

3. Price calendar (cheapest days in a month)

python3 scripts/search_flights.py --from MOW --to LED --month 2026-04

Returns results sorted by price. Use to recommend the cheapest travel dates.

4. Latest found prices (price monitoring)

python3 scripts/search_flights.py --from MOW --latest

Shows recently found prices from the origin to any destination. Add --to AER to filter. Add --one-way for one-way only.

5. Popular destinations from a city

python3 scripts/search_flights.py --from MOW --directions

Returns destinations sorted by price — useful for "where can I fly cheaply from X?" queries.

Output Format

All commands output JSON to stdout:

{
  "query": {"from": "MOW", "to": "LED", "date": "2026-04-15"},
  "results": [
    {
      "price": 2454,
      "airline": "Pobeda",
      "airline_code": "DP",
      "flight": "DP 209",
      "from_airport": "VKO",
      "to_airport": "LED",
      "departure": "2026-04-07T07:50:00+03:00",
      "duration_min": 90,
      "duration_str": "1h 30min",
      "transfers": 0,
      "transfers_str": "non-stop",
      "link": "https://aviasales.ru/search/..."
    }
  ],
  "cheapest": 2454,
  "count": 5
}

Presenting Results to the User

1. Highlight the cheapest option first.
2. For each result show: price, airline, flight number, departure time, duration, stop type.
3. Format the link field as a clickable URL for booking.
4. For calendar queries, recommend the cheapest dates.

API Endpoints

Common IATA Codes

References

• Airline codes: See references/airlines.md for a reference mapping of IATA airline codes to names. The script auto-fetches the latest mapping from the Travelpayouts API with a 24-hour cache; this file serves as a fallback.