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

# 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

# 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:

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

# 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

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)

# 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