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. 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

CODEBLOCK0

With Gmail Integration

CODEBLOCK1

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:

CODEBLOCK2

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

CODEBLOCK3

Step 4: Generate Itinerary

CODEBLOCK4

Step 5: Export (Optional)

CODEBLOCK5

Scripts Reference

generate_itinerary.py

Arguments:

• - --destination: Comma-separated list of cities/regions
• INLINECODE9: Trip start date (YYYY-MM-DD)
• INLINECODE10: Trip end date (YYYY-MM-DD)
• INLINECODE11: Path to bookings JSON (from gmailparser.py)
• INLINECODE12: Path to weather JSON (from weatherfetcher.py)
• INLINECODE13: Path to places JSON (from places_fetcher.py)
• INLINECODE14: Total budget amount (optional)
• INLINECODE15: Currency code (SGD, USD, JPY, etc.)
• INLINECODE16: Output language (zh, en, ja, ko)
• INLINECODE17: Comma-separated tags (history, nature, food, shopping, concerts)
• INLINECODE18: Output file path (.html, .md, or .json)

gmail_parser.py

Requirements: GOGKEYRINGPASSWORD environment variable

Arguments:

• - --account: Gmail account email
• INLINECODE21: Start date for email search (YYYY-MM-DD)
• INLINECODE22: Search keywords (default: "flight,hotel,booking,confirmation")
• INLINECODE23: Output JSON file

weather_fetcher.py

Arguments:

• - --destinations: Comma-separated cities
• INLINECODE26: Forecast start date
• INLINECODE27: Forecast end date
• INLINECODE28: Output JSON file

places_fetcher.py

Arguments:

• - --destinations: Comma-separated cities
• INLINECODE31: Activity tags (temples, museums, food, shopping)
• INLINECODE32: Display language
• INLINECODE33: Output JSON file

translator.py

Arguments:

• - --text: Text to translate
• INLINECODE36: Source language code
• INLINECODE37: Comma-separated target language codes
• INLINECODE38: Output JSON file

budget_calculator.py

Arguments:

• - --destination: Primary destination
• INLINECODE41: Number of days
• INLINECODE42: Path to bookings JSON
• INLINECODE43: Budget category (budget, mid-range, luxury)
• INLINECODE44: Output JSON file

export_html.py

Arguments:

• - --input: Itinerary JSON file
• INLINECODE47: HTML template (default: assets/itinerary_template.html)
• INLINECODE48: Output HTML file

References

• - destinationtemplates.md: Pre-built templates for popular destinations (Tokyo, Seoul, Paris, etc.)
• traveltips.md: Climate guides, packing lists, visa requirements, cultural tips
• emailpatterns.md: Email parsing rules for different booking platforms
• poidatabase.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:

CODEBLOCK6

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
• INLINECODE50 — Attraction and restaurant search
• INLINECODE51 — Gmail parsing (optional, requires GOGKEYRINGPASSWORD)
• INLINECODE52 — 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 GOGKEYRINGPASSWORD 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