travel-itinerary-builder

# Travel Itinerary Builder Generate comprehensive, print-ready travel itineraries with automatic integration of weather, places, dining, transportation, and budget planning. ## ⚠️ Security & Privacy Notice **This skill accesses sensitive data and requires external credentials:** ### Gmail Access (Optional) - The `gmail_parser.py` script **reads your Gmail messages** to extract booking confirmations - Requires `GOG_KEYRING_PASSWORD` environment variable (for GOG CLI authentication) - **What it accesses**: Email subjects, snippets, and full message bodies matching search queries - **What it extracts**: Flight details (PNR, times), hotel bookings, car rentals, activity tickets - **Data handling**: Extracted data is stored locally in JSON files; no external transmission ### Google Places API (Optional) - The `places_fetcher.py` script queries Google Places for attractions - Requires `GOOGLE_PLACES_API_KEY` environment variable (free tier: 1000 requests/month) - Fallback to built-in database if API key not provided ### External CLI Dependencies - **gog** (Google OAuth CLI): Authenticates Gmail access via OAuth2 - **goplaces**: Queries Google Places API - **curl**: Fetches weather data from wttr.in **Before installing**: 1. Review all scripts in `scripts/` directory 2. Only provide credentials if you trust the external CLIs 3. Consider running in an isolated environment (container/VM) 4. Gmail integration is **optional** — you can use the skill without it ## Quick Start ### Basic Usage ```bash # Generate itinerary from user input python3 scripts/generate_itinerary.py \ --destination "Tokyo, Osaka, Kyoto" \ --start-date "2026-03-06" \ --end-date "2026-03-15" \ --language zh \ --output ./japan_trip.html ``` ### With Gmail Integration ```bash # Extract bookings from Gmail and generate itinerary python3 scripts/gmail_parser.py \ --account rachelchoo1212@gmail.com \ --after "2026-03-01" \ --output ./bookings.json python3 scripts/generate_itinerary.py \ --bookings ./bookings.json \ --destination "Tokyo, Osaka" \ --start-date "2026-03-06" \ --end-date "2026-03-15" \ --output ./trip.html ``` ## Core Features ### 1. Automatic Data Collection - **Weather forecasts**: Integrates with `weather` skill for daily forecasts - **Points of interest**: Uses `goplaces` skill for attractions, restaurants, landmarks - **Multi-language names**: Shows place names in user language + local language - **Gmail parsing**: Extracts flight, hotel, car rental bookings from confirmation emails ### 2. Intelligent Planning - **Daily schedules**: Auto-generates time-based itineraries (08:00 departure → 10:00 attraction → 12:00 lunch) - **Transportation routing**: Calculates distances, travel times, and costs for driving/transit - **Budget estimation**: Computes total costs for accommodation, meals, transport, tickets - **Packing lists**: Generates climate-appropriate packing suggestions ### 3. Output Formats - **HTML**: Beautiful dark-themed, print-ready documents (based on proven template) - **Markdown**: Editable plain-text format - **JSON**: Structured data for further processing - **PDF**: Optional export via HTML → PDF conversion ## Workflow ### Step 1: Gather Information Ask user for: - Destinations (cities/regions) - Travel dates (start and end) - Budget range (optional) - Interests/tags (history, nature, food, shopping, concerts) - Language preference (zh, en, ja, ko) - Special requirements (dietary, accessibility, child-friendly) ### Step 2: Extract Existing Bookings (Optional) If user has Gmail access configured: ```bash python3 scripts/gmail_parser.py \ --account <email> \ --after <YYYY-MM-DD> \ --keywords "flight,hotel,booking,reservation,confirmation" \ --output bookings.json ``` This extracts: - ✈️ Flights: airline, flight number, departure/arrival times, PNR - 🏨 Hotels: name, address, check-in/out dates, booking number, price - 🚗 Car rentals: company, car type, pickup/return times, booking number - 🎫 Tickets: concerts, museums, activities with times and seat info Supported platforms: Agoda, Booking.com, Singapore Airlines, ANA, Trip.com, Klook, KKday ### Step 3: Query Weather and Places ```bash # Weather forecasts for each destination python3 scripts/weather_fetcher.py \ --destinations "Tokyo,Osaka,Kyoto" \ --start-date "2026-03-06" \ --end-date "2026-03-15" \ --output weather.json # Points of interest python3 scripts/places_fetcher.py \ --destinations "Tokyo,Osaka,Kyoto" \ --interests "temples,food,shopping" \ --language zh \ --output places.json ``` ### Step 4: Generate Itinerary ```bash python3 scripts/generate_itinerary.py \ --bookings bookings.json \ --weather weather.json \ --places places.json \ --start-date "2026-03-06" \ --end-date "2026-03-15" \ --budget 2000 \ --currency SGD \ --language zh \ --output japan_trip.html ``` ### Step 5: Export (Optional) ```bash # Export to PDF python3 scripts/export_pdf.py japan_trip.html japan_trip.pdf # Sync to Notion (if configured) python3 scripts/sync_notion.py japan_trip.json ``` ## Scripts Reference ### `generate_itinerary.py` Core generator. Combines all data sources into a complete itinerary. **Arguments**: - `--destination`: Comma-separated list of cities/regions - `--start-date`: Trip start date (YYYY-MM-DD) - `--end-date`: Trip end date (YYYY-MM-DD) - `--bookings`: Path to bookings JSON (from gmail_parser.py) - `--weather`: Path to weather JSON (from weather_fetcher.py) - `--places`: Path to places JSON (from places_fetcher.py) - `--budget`: Total budget amount (optional) - `--currency`: Currency code (SGD, USD, JPY, etc.) - `--language`: Output language (zh, en, ja, ko) - `--interests`: Comma-separated tags (history, nature, food, shopping, concerts) - `--output`: Output file path (.html, .md, or .json) ### `gmail_parser.py` Extracts travel bookings from Gmail using GOG skill. **Requirements**: GOG_KEYRING_PASSWORD environment variable **Arguments**: - `--account`: Gmail account email - `--after`: Start date for email search (YYYY-MM-DD) - `--keywords`: Search keywords (default: "flight,hotel,booking,confirmation") - `--output`: Output JSON file ### `weather_fetcher.py` Fetches weather forecasts for destinations using weather skill. **Arguments**: - `--destinations`: Comma-separated cities - `--start-date`: Forecast start date - `--end-date`: Forecast end date - `--output`: Output JSON file ### `places_fetcher.py` Queries points of interest using goplaces skill. **Arguments**: - `--destinations`: Comma-separated cities - `--interests`: Activity tags (temples, museums, food, shopping) - `--language`: Display language - `--output`: Output JSON file ### `translator.py` Translates place names to multiple languages. **Arguments**: - `--text`: Text to translate - `--source-lang`: Source language code - `--target-langs`: Comma-separated target language codes - `--output`: Output JSON file ### `budget_calculator.py` Estimates trip costs based on destination, duration, and bookings. **Arguments**: - `--destination`: Primary destination - `--days`: Number of days - `--bookings`: Path to bookings JSON - `--category`: Budget category (budget, mid-range, luxury) - `--output`: Output JSON file ### `export_html.py` Converts itinerary JSON to styled HTML using template. **Arguments**: - `--input`: Itinerary JSON file - `--template`: HTML template (default: assets/itinerary_template.html) - `--output`: Output HTML file ## References - **destination_templates.md**: Pre-built templates for popular destinations (Tokyo, Seoul, Paris, etc.) - **travel_tips.md**: Climate guides, packing lists, visa requirements, cultural tips - **email_patterns.md**: Email parsing rules for different booking platforms - **poi_database.md**: Common attractions with multi-language names ## Assets - **itinerary_template.html**: Dark-themed HTML template with CSS styling - **icons/**: SVG icons for flights, hotels, restaurants, attractions - **fonts/**: Web fonts for print-quality output ## Multi-Language Support Place names are displayed in **user language + local language**: ``` 东京塔 (東京タワー / Tokyo Tower) 和歌山城 (和歌山城 / Wakayama Castle) ``` Supported languages: Chinese (zh), English (en), Japanese (ja), Korean (ko) ## Output Example Generated HTML includes: - 📅 **Day-by-day timeline** with emoji icons - 🌤️ **Daily weather** forecasts - ✈️ **Flight details** with boarding times - 🏨 **Hotel information** with check-in/out - 🚗 **Driving routes** with distances and tolls - 🍽️ **Restaurant recommendations** with local specialties - 💰 **Budget breakdown** by category - 📋 **Packing checklist** based on climate - ⚠️ **Important reminders** (visa, insurance, IDP) ## Integration with Other Skills This skill calls: - `weather` — Daily forecasts - `goplaces` — Attraction and restaurant search - `gog` — Gmail parsing (optional, requires GOG_KEYRING_PASSWORD) - `notion` — Sync to Notion database (optional, requires Notion API key) ## Tips - **For self-driving trips**: Include rental car details, calculate fuel costs, note toll roads - **For concert/event trips**: Add venue info, seating, merchandise shop times - **For multi-city trips**: Calculate transit times between cities - **For international trips**: Include visa requirements, vaccination, travel insurance reminders ## Troubleshooting - **Gmail parsing fails**: Check GOG_KEYRING_PASSWORD is set and account has access - **Weather data missing**: Ensure dates are within forecast range (usually 10 days) - **Places not found**: Try broader search terms or check goplaces API key - **HTML rendering issues**: Open in modern browser (Chrome, Firefox, Safari) ## Future Enhancements - Real-time flight status updates - Amadeus API integration for flight price tracking - Google Sheets export for budget tracking - PDF generation without external tools - Mobile-responsive HTML output