natbag

Natbag — Ben Gurion Airport Flights

Live flight data, destination weather, and historical analysis for Ben Gurion Airport (TLV/LLBG). Data from Israel's open data portal (data.gov.il), covering a rolling ~3-day window.

Query Workflow

Show step progress to the user as each step runs:

1. Step 1: Fetching flights — run query_flights.py with appropriate filters
2. Step 2: Getting weather — fetch destination weather (for single flight or when relevant)
3. Step 3: Checking history — query historical stats (only if user asks about delays/patterns)

Not all steps run every time. Skip steps that aren't relevant to the query:

• Departure board → Step 1 only
• "Is my flight on time?" → Step 1 + Step 2
• "Are El Al flights usually delayed?" → Step 3 only
• "Next flight to London with weather" → Step 1 + Step 2

Display each step label before running it so the user sees progress.

Data Sources

1. Live flights: data.gov.il API — departures, arrivals, status, gates
2. Weather: Open-Meteo API — free, no API key — current conditions at destination
3. Historical: Local SQLite DB at ~/.natbag/flights.db — accumulated via daily snapshots

Daily Snapshot (Automatic)

A PreToolUse hook runs snapshot.py automatically whenever this skill is invoked. On first run, it copies the shipped data/db.db (airlines + airports) to ~/.natbag/flights.db, adds the flights table, and fetches live flights. On subsequent runs, it self-guards: skips if it already ran today or if the user disabled snapshots.

After the first invocation, inform the user: "Natbag initialized. Flight data and IATA reference loaded. Historical data will accumulate automatically on each use. To disable daily snapshots, set daily_snapshot: false in ~/.natbag/config.json."

Replace SKILL_DIR with the resolved path to this skill's directory (where this SKILL.md lives).

Querying Live Flights

Use the composable query_flights.py script for live API queries:

python3 SKILL_DIR/scripts/query_flights.py --departures --date YYYY-MM-DD
python3 SKILL_DIR/scripts/query_flights.py --arrivals --date YYYY-MM-DD --upcoming
python3 SKILL_DIR/scripts/query_flights.py --arrivals --airline LY --date YYYY-MM-DD
python3 SKILL_DIR/scripts/query_flights.py --destination JFK --upcoming
python3 SKILL_DIR/scripts/query_flights.py --flight LY001
python3 SKILL_DIR/scripts/query_flights.py --status DELAYED
python3 SKILL_DIR/scripts/query_flights.py --search "London"

Flags can be combined. All scripts return JSON — Claude handles formatting for the user.

CRITICAL: Always use --date YYYY-MM-DD when counting or listing flights for a specific day. Without it, the API returns a rolling ~3-day window, inflating counts. When --date is set, the script automatically pages through all API results before filtering, so counts are accurate. Replace YYYY-MM-DD with the actual date (e.g., 2026-04-03).

For raw API access, use curl directly — see references/api.md for filter patterns.

Resolving Ambiguous Queries

The local DB at ~/.natbag/flights.db includes airlines and airports tables (from data/db.db) for resolving user input:

• Airline name → code: User says "El Al" or "Wizz Air" → look up IATA code:

  python3 SKILL_DIR/scripts/query_history.py --airline-lookup "El Al"
  

• Multi-airport cities: User says "flights to London" → find all London airports:

  python3 SKILL_DIR/scripts/query_history.py --airports London
  

  Then query each relevant code (LHR, LGW, STN, LTN, LCY) or use full-text search --search London.
• Partial flight numbers: User says "flight 001" without airline → use --search 001 to match across all airlines.
• Hebrew city names: User types "לונדון" → use --search לונדון. Supports partial prefix matching (e.g., --search לונ finds לונדון).
• Empty results: If a filtered query returns 0 results, try broadening: drop the direction filter, switch from exact filter to --search, or check if the city has multiple airport codes.

Output Fields

query_flights.py returns clean JSON with these fields:

Field	Content
flight	Airline code + number (e.g., "LY 1008")
airline	Airline full name
date	Scheduled date (YYYY-MM-DD)
time	Scheduled time (HH:MM)
updated_time	Actual/updated time (compare with time to detect delays)
direction	"departure" or "arrival"
city / city_he	City name (English / Hebrew)
country / country_he	Country (English / Hebrew)
airport	IATA airport code
terminal	Terminal number
gate	Gate assignment (null if unassigned)
checkin_zone	Check-in zone (null if N/A)
status / status_he	Flight status (English / Hebrew)

Full field reference and curl examples: see references/api.md. For complete output examples: see examples/ (departure board, single flight, historical stats).

Destination Weather

After showing flight info, offer weather at the destination. Uses Open-Meteo (free, no key).

Steps:

1. Get the city field from the flight JSON (e.g., "BERLIN")
2. Geocode: curl -s 'https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1'
3. Extract latitude and longitude from results[0]
4. Fetch weather: curl -s 'https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true'
5. Display: temperature, weather description, wind speed

Open-Meteo returns the most populated city match, so "Berlin" → Berlin Germany (not Berlin NH). Tested and correct for all TLV route cities.

Weather codes: 0=Clear, 1-3=Partly cloudy, 45/48=Fog, 51-55=Drizzle, 61-65=Rain, 71-75=Snow, 80-82=Showers, 95=Thunderstorm.

Historical Analysis

Use the composable query_history.py script for historical queries:

python3 SKILL_DIR/scripts/query_history.py --coverage                    # data range
python3 SKILL_DIR/scripts/query_history.py --ontime                      # all airlines
python3 SKILL_DIR/scripts/query_history.py --ontime --airline LY          # specific airline
python3 SKILL_DIR/scripts/query_history.py --delays --route JFK           # delays by route
python3 SKILL_DIR/scripts/query_history.py --cancellations                # cancellation rates
python3 SKILL_DIR/scripts/query_history.py --airports London              # multi-airport lookup
python3 SKILL_DIR/scripts/query_history.py --airline-lookup "Wizz"        # airline code lookup

Add --days N to change the lookback period (default: 30). All output is JSON.

Flight Change History

Track how flights evolve over time — status changes, time updates, gate reassignments:

python3 SKILL_DIR/scripts/query_history.py --flight-history LY001         # all changes for a flight
python3 SKILL_DIR/scripts/query_history.py --delay-patterns               # when are delays announced?
python3 SKILL_DIR/scripts/query_history.py --delay-patterns --airline LY   # per-airline patterns
python3 SKILL_DIR/scripts/query_history.py --status-transitions            # status paths (e.g., DELAYED -> CANCELED)

Change history accumulates from version 1.1.0 onward. Older flights (captured before the upgrade) will not have change records.

Use --flight-history when the user asks about a specific flight's progression. Use --delay-patterns when they ask about how early delays are typically announced. Use --status-transitions when they ask about flights that were delayed then cancelled, or other status paths.

If the database doesn't exist or is empty, inform the user: "Historical data accumulates from install date via daily snapshots. Run python3 SKILL_DIR/scripts/snapshot.py --force to start collecting now."

For custom SQL queries, use sqlite3 ~/.natbag/flights.db directly. The DB also has airlines, airports, and flight_changes tables for JOINs. See references/api.md for query patterns.

Output Formatting

Departure/Arrival Board

Ben Gurion Departures — March 21, 2026

Time    Flight    Airline     To               Gate     Status
14:10   LY 001    El Al       London (LHR)     B2-B4    ON TIME
14:30   IZ 1511   Arkia       Larnaca (LCA)    G11      DELAYED → 15:04
15:00   6H 996    Israir      Amsterdam (AMS)   —       CANCELED

• Sort by date + time
• For DELAYED flights, show updated_time
• Use — for null gate/checkin_zone values
• Omit past flights (status DEPARTED/LANDED) unless the user explicitly asks for all

Single Flight Detail

Flight LY 001 — El Al Israel Airlines
Route:     Tel Aviv (TLV) → London Heathrow (LHR)
Scheduled: 14:10  |  Updated: 14:10
Terminal:  3      |  Gate: B2-B4  |  Check-in: B
Status:    ON TIME

London Weather: 12°C, Partly Cloudy, Wind 15 km/h

Historical Stats

El Al to JFK — Last 30 Days (from local DB)
Total: 28  |  On time: 19 (68%)  |  Avg delay: 22 min
Cancellations: 1 (3.6%)

Hebrew Support

When the user writes in Hebrew, respond in Hebrew and use the Hebrew fields from the JSON:

• City names: city_he instead of city
• Country names: country_he instead of country
• Status: status_he instead of status
• Board header: לוח טיסות נתב"ג — יציאות / הגעות

Smart Behaviors

• "my flight": Ask for flight number or destination to narrow down
• Pickup planning: Show arrival time + suggest arriving 30 min after expected landing. If DELAYED, use updated_time instead of time
• Delay detection: When updated_time > time, calculate and show delay duration in minutes
• Weather proactively: When showing a single flight detail, include destination weather automatically
• First use: Mention that historical data accumulates over time via daily snapshots. The user can disable this in ~/.natbag/config.json by setting daily_snapshot: false

Snapshot Management

The scripts/snapshot.py script fetches current flights and stores them in SQLite:

• Runs automatically via PreToolUse hook on each skill invocation (self-guards to once daily)
• python3 SKILL_DIR/scripts/snapshot.py --force to run manually anytime
• Opt-out: set daily_snapshot: false in ~/.natbag/config.json
• First run copies shipped data/db.db (airlines + airports) to ~/.natbag/flights.db
• Data deduplicates by airline+flight+scheduled time
• Status and gate info are updated on each snapshot

Gotchas

• Field names are cryptic: All fields start with CH (Hebrew abbreviation for "חברה"/company). Always refer to the field reference, never guess. Common mistake: using STATUS instead of CHRMINE.
• Rolling window inflates counts: API returns ~3 days of data, NOT just today. When counting flights for a specific day, ALWAYS pass --date YYYY-MM-DD to filter. Without it, "how many flights today?" will return 3x the real number. This has caused wrong answers repeatedly.
• Uppercase values: Filter values must be uppercase. filters={"CHRMINE":"delayed"} returns 0 results silently — use "DELAYED". Same for airline codes: "ly" → no results, "LY" → works.
• API timeout: data.gov.il can be slow (5-15s). If curl hangs, retry once. Error: curl: (28) Operation timed out — fix with curl -s --max-time 30.
• Bad resource ID: Returns {"success": false, "error": {"__type": "Not Found Error", "message": "לא נמצא: Resource was not found."}}. Fix: verify the resource_id constant hasn't changed.
• Malformed filters JSON: Returns {"success": false, "error": {"filters": ["Cannot parse JSON"], "__type": "Validation Error"}}. Fix: ensure filters value is valid JSON with properly escaped quotes in the URL.
• Empty result confusion: "total": 0 with "success": true means the filter matched nothing — not an error. Check: is the value uppercase? Is the field name correct? Is the flight within the 3-day window?
• Gate availability: CHCINT and CHCKZN are often null for flights >24h away or for arrivals. Don't treat null gate as an error.
• "NOT FINAL": Many future flights show status "NOT FINAL" — this means the schedule isn't confirmed yet, not that the flight is cancelled. Don't alarm the user.
• No booking: This skill provides information only. Cannot book, modify, or cancel flights. If asked, clearly say so.