Travel Mapify#

Create interactive, professional travel route maps from location names.

Overview#

This skill automatically:

1. Processes text input: Parses comma-separated location names directly
2. Geocodes locations to get precise coordinates using Amap API
3. Generates interactive maps with route optimization and POI management
4. Supports AI Vision workflow: When given travel planning images, use agent's AI Vision to extract POI names, then process as text input
5. Geocodes locations to get precise coordinates using Amap API
6. Generates interactive maps with route optimization and POI management
7. Integrates real hotel search using FlyAI for actual hotel recommendations
8. Creates professional outputs ready for sharing and presentation

When to Use#

Text Input Mode:

• User provides comma-separated location names directly (e.g., "上海外滩,上海迪士尼乐园,豫园")
• User wants to quickly create a travel map from a simple list of destinations
• User has location names but no visual reference image

AI Vision Image Processing Workflow:

• User has a travel planning image (screenshot, photo, or digital plan)
• Agent uses AI Vision to analyze the image and extract POI names with sequence/order
• Extracted POI names are passed as text input to the skill
• This hybrid approach combines AI automation with the skill's robust text processing

Hotel Integration Mode:

• User wants real hotel recommendations near their destination
• User needs actual pricing and availability data
• User wants booking links for hotels through FlyAI integration

Workflow#

Step 1: Input Processing and POI Extraction#

For Direct Text Input:

• Parse comma-separated location names directly
• Create POI entries with high confidence (user-provided)
• Automatic city detection: Smart city detection from location names (e.g., "北京军事博物馆" → city="北京")
• Fallback to default: Uses Shanghai as default when no city can be detected

For Image Input (AI Vision Workflow):

• Use agent's AI Vision capability to analyze travel planning images
• Extract POI names and sequence from numbered markers or route indicators
• Preserve exact order as marked in the original image
• Pass extracted names as text input to the skill's standard processing pipeline
• Leverage existing text processing for geocoding, validation, and map generation

Step 2: Geocoding and Coordinate Resolution#

• Use Amap geocoding API to resolve location names to precise coordinates
• Handle ambiguous locations with user confirmation
• Validate coordinate accuracy

Step 3: Enhanced Map Generation#

• Use optimized travel_mapify with unique map ID isolation as main template with all UX improvements
• Automatic localStorage isolation based on POI names to prevent data conflicts between different maps
• Optimized performance with streamlined template generation and reduced dependencies
• Create a single dual-mode interface with toggle between Edit/View modes
• Implement drag-and-drop and arrow button reordering (edit mode only)
• Generate optimized route with directional arrows
• Add "Generate Final" functionality to download clean version
• Integrate real FlyAI hotel search with professional loading states
• Replace alert popups with notification system

Step 4: Automatic Server Management#

• Automatically start HTTP server on port 9000 (or specified port)
• Automatically start hotel search server on port 8770 (or specified port)
• Check if servers are already running to avoid conflicts
• Provide direct access URLs in output
• Ensure all functionality is ready when map creation completes

Step 4: Professional Output Delivery#

• Provide unified HTML file that works in both editing and presentation contexts
• Include clear instructions for toggling modes and generating final version
• Ensure mobile-responsive design

File Structure#

text

flyai-travelmapify/
├── SKILL.md
├── INSTALL.md                          # Installation and setup guide
├── flyai-travelmapify.py              # **PORTABLE ENTRY POINT**: Main executable script
├── scripts/
│   ├── config.py                      # **DYNAMIC CONFIGURATION**: Path and environment detection
│   ├── main_travel_mapify_enhanced.py # **PRODUCTION MAIN**: Auto-starts servers + text input + unique ID isolation
│   ├── geocode_locations.py           # Amap geocoding integration
│   ├── generate_from_optimized_template.py # Optimized template with unique map ID isolation
│   └── hotel-search-server.py         # FlyAI hotel search backend server

**Note**: Image processing is handled externally using the agent's AI Vision capability. The extracted POI names are passed as text input to this skill.
├── references/
│   ├── amap_api_guide.md              # Amap API usage patterns
│   ├── poi_validation_rules.md        # POI validation and filtering rules
│   └── troubleshooting-guide.md       # Common issues and solutions
└── assets/
    └── templates/
        └── main-generic-template-with-unique-id.html # **PRODUCTION TEMPLATE**: Unique ID isolation + all features

Main Template: The skill now uses the optimized travel_mapify system with unique map ID isolation as the primary approach, which includes:

• Optimized Template Generation: Streamlined HTML generation with minimal dependencies
• Unique Map ID Generation: Automatically creates a hash-based ID from POI names (e.g., travelMap_abc123) to isolate localStorage data
• No Cross-Map Data Contamination: Each travel map saves/retrieves data independently using its unique ID
• Persistent Per-Map State: Hotel searches, date selections, and POI reordering are saved separately for each map
• Enhanced Performance: Reduced template complexity and faster map loading
• Real FlyAI hotel search integration
• Professional notification system (no alert popups)
• Loading states with timeout handling
• Enhanced UX with smart defaults

Automatic Server Management: The enhanced main script automatically starts both HTTP server (port 9000) and hotel search server (port 8770) when generating maps, ensuring all functionality is ready immediately.

Usage Examples#

Portable Execution#

bash

# From skill directory (recommended)
python3 flyai-travelmapify.py --locations "上海外滩,迪士尼乐园,豫园" --output-html shanghai-trip.html

# From any directory
python3 /path/to/flyai-travelmapify/flyai-travelmapify.py --locations "北京故宫,天坛,颐和园" --output-html beijing-trip.html

# AI Vision Image Processing Workflow:
# 1. Use agent's AI Vision to analyze travel image and extract POI names
# 2. Pass extracted names as text input to the skill
# Example: locations="解放碑,山城步道,十八梯,白象居,湖广会馆,来福士,洪崖洞,千厮门大桥"

# With custom ports
python3 flyai-travelmapify.py --locations "Tokyo Tower,Shibuya Crossing" --output-html tokyo-trip.html --http-port 8080 --hotel-port 9000

Image Input - AI Vision Enhanced#

User: "Here's my travel plan screenshot, can you make it interactive?" → Skill analyzes image using AI Vision model → If needed, requests clarification: "What city is this for?" or "How many attractions are marked?" → Extracts attractions with preserved sequence and generates interactive map

Image Input - Manual Clarification#

User provides image → Skill detects uncertainty → Requests city context → User responds "重庆" → Skill processes with enhanced accuracy

Image Input - Direct POI Entry#

When AI Vision cannot confidently identify attractions, skill prompts: "Please provide attraction names in order, separated by commas"

Image Input - Advanced Usage#

User: "I have a photo of our Beijing itinerary, please create a shareable map" → Skill processes image, validates locations, creates optimized route with professional styling

Text Input - Direct Locations with Auto City Detection#

User: "北京军事博物馆,北京科技大学" → Skill auto-detects city="北京" from location names → Parses locations directly, geocodes them, and generates interactive map

Text Input - Default City Fallback#

User: "外滩,迪士尼乐园,豫园" → Skill cannot detect city from generic names → Uses default city="上海" for geocoding → Generates interactive map

Text Input - Simple List#

User: "Create a travel map for: Tokyo Tower, Shibuya Crossing, Meiji Shrine" → Skill extracts location names, geocodes them, creates optimized route

Hotel Search Integration#

User: Clicks "搜酒店" button in generated map → Real FlyAI hotel search returns actual hotel data with prices and booking links → No mock data - uses real-time Fliggy MCP integration → Professional UX with loading states and notifications (no alert popups) → Default dates: today for check-in, tomorrow for check-out (1-night stay)

Customization Request#

User: "Can you adjust the route order and add missing locations?" → Skill provides editable interface with search functionality and reordering tools

Technical Requirements#

• Python 3.7+: Required for all scripts (uses standard library only)
• FlyAI CLI: Must be installed globally ( npm install -g @openclaw/flyai)
• Amap API: Uses built-in default API key (no user key required)
• Local Proxy: Built-in proxy server handles Amap API requests (default port 8769)
• Web Browser: Modern browser with JavaScript support for interactive features

Required Skills#

This skill depends on the following OpenClaw skills:

• amap-maps: Provides Amap LBS services for geocoding, POI search, and location services

Both skills must be installed in your OpenClaw workspace under the skills/ directory:

text

~/.openclaw/workspace/
├── skills/
│   ├── flyai-travelmapify/
│   └── amap-maps/

Portable Design#

✅ No hardcoded paths - Automatically detects OpenClaw workspace and FlyAI installation ✅ Cross-platform - Works on Windows, macOS, and Linux ✅ Self-contained - All scripts and templates included in skill directory ✅ Environment-aware - Adapts to different system configurations ✅ Fallback mechanisms - Multiple detection methods for required components

Output Files#

The skill generates HTML files using the optimized travel_mapify system with unique map ID isolation as the main template:

[location]-travel-map-optimized.html - Dual-mode interface with all professional enhancements:

• Real FlyAI Hotel Search Integration:

  • Actual hotel data with prices and booking links
  • Loading states with "搜索中..." button text
  • 5-second timeout with auto-re-enable
  • No mock data - uses real Fliggy MCP integration

• Professional UX Improvements:

  • Notification system instead of alert popups
  • Auto-hiding messages after 3 seconds
  • Smart date defaults (today check-in, tomorrow check-out)

• Edit Mode (📝): Full-featured editing interface with:

  • Left-panel POI management
  • Search functionality for adding new locations
  • Drag-and-drop and arrow button reordering
  • Real-time map preview

• View Mode (👁️): Clean presentation version with:

  • Optimized route display
  • Numbered POI markers with directional arrows
  • Professional styling ready for sharing

• Generate Final: Download button to create a clean version without edit controls

Files are self-contained and work in any modern web browser when served via HTTP server.

Error Handling#

• Poor Image Quality: Request higher quality image or manual POI entry
• Ambiguous Locations: Present options for user selection
• API Rate Limits: Implement retry logic with exponential backoff
• Missing Coordinates: Fall back to approximate coordinates with user verification
• HTML Display Issues: Use local HTTP server instead of file:// protocol
• Map Loading Failures: Check AMap API key restrictions and network connectivity
• localStorage Corruption: Implement fallback data and validation logic

Enhanced UX Features#

Professional User Interface:

• No alert popups: All messages displayed in non-intrusive notification area
• Loading states: Hotel search button shows "搜索中..." during API calls
• Timeout handling: 5-second timeout automatically re-enables search button
• Auto-hiding notifications: Messages disappear after 3 seconds
• Visual feedback: Error messages in red, success messages in green

Smart Defaults:

• Date selection: Today for check-in, tomorrow for check-out (1-night stay)
• Hotel sorting: Results sorted by distance from destination
• Top results: Shows top 5 closest hotels for better user experience

Best Practices#

• Always verify extracted POIs with the user before finalizing
• Provide clear instructions for customizing the generated maps
• Optimize for mobile viewing with responsive design
• Include north indicator and scale reference for professional appearance
• Always test via HTTP server: Never rely on file:// protocol for web applications
• Implement robust error handling: Wrap API calls and provide user feedback
• Validate all inputs: Sanitize data before processing
• Document dependencies: Clearly specify API keys, network, and browser requirements
• Use optimized travel_mapify with unique map ID isolation: All travel maps now automatically generate unique IDs based on POI names to prevent localStorage conflicts between different maps
• Leverage enhanced performance: The optimized system provides faster map generation and loading