| name | flyai-travelmapify |
| version | 2.2.0 |
| description | Copy Xiaohongshu travel planning homework into interactive route maps with real FlyAI hotel search in seconds. |
| author | rudy2steiner |
| license | MIT |
| tags | ["travel","maps","routing","ai-vision","geocoding","flyai","hotels","unique-id","server-management","interactive","xiaohongshu"] |
Travel Mapify
Transform travel planning images into interactive, professional travel route maps.
Overview
This skill automatically:
- Supports dual input modes: Process travel planning images (OCR) OR direct comma-separated location names
- Extracts POIs from images using OCR and AI analysis (image mode)
- Parses location names directly from text input (text mode)
- Geocodes locations to get precise coordinates using Amap API
- Generates interactive maps with route optimization and POI management
- Integrates real hotel search using FlyAI for actual hotel recommendations
- Creates professional outputs ready for sharing and presentation
When to Use
Image Input Mode:
- User uploads a travel planning screenshot/image with location names
- User wants to convert a hand-drawn or digital travel itinerary into an interactive map
- User has a photo of a travel plan written on paper or displayed on screen
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
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 Image Input (AI Vision Enhanced):
- Use AI Vision analysis instead of traditional OCR for better accuracy on complex travel planning images
- Interactive clarification: When recognition is uncertain, request user input for city/location context and expected attraction count
- Manual fallback: If AI vision cannot confidently identify attractions, prompt user to provide attraction names directly
- Preserve sequence: Maintain the exact numbered order as marked in the original travel planning image
- Filter noise: Ignore garbled text, background interference, and corrupted characters that plague traditional OCR
For 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
- No OCR processing required
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
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 + dual input + unique ID isolation
│ ├── extract_pois_from_image_vision.py # **AI VISION ENHANCED**: Interactive POI extraction with user clarification
│ ├── 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
├── 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
python3 flyai-travelmapify.py --locations "上海外滩,迪士尼乐园,豫园" --output-html shanghai-trip.html
python3 /path/to/flyai-travelmapify/flyai-travelmapify.py --image ~/Downloads/trip-plan.jpg --output-html my-trip.html
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 Key: Valid Amap Web API key for geocoding and map tiles
- Local Proxy: Running local proxy server for Amap API requests (default port 8769)
- Web Browser: Modern browser with JavaScript support for interactive features
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
