FlightMapify Skill#

Overview#

FlightMapify creates interactive flight route maps that allow users to search for flights between cities and visualize flight paths on an interactive map. Unlike TravelMapify which focuses on ground travel routes, FlightMapify is specifically designed for air travel planning.

Features#

• Optimized server management with automatic port conflict resolution
• Flask-based flight search server for robust API handling
• Interactive flight search between origin and destination cities
• Real-time flight data from FlyAI (Fliggy MCP)
• Support for both direct and connecting flights with complete route information
• Visual flight path display on Amap maps with animated markers
• Direct booking links to Fliggy
• Support for both domestic and international flights
• Single-date input for simple flight queries
• Enhanced UX with loading states, notifications, and auto-hiding messages
• Professional error handling with user-friendly feedback
• Environment variable configuration for API Key management
• Complete connecting flight details including transfer cities, prices, and durations

Usage#

Environment Setup#

FlightMapify is an OpenClaw skill that supports optional user-configurable FlyAI API Key.

Configuration Options:

1. User-provided API Key (Recommended - avoids rate limiting)

   Get your API key from: https://flyai.open.fliggy.com/console bash

   export FLYAI_API_KEY=your_api_key_here
   
   

2. FlyAI Built-in API Key (Default)

   • If FLYAI_API_KEY is not configured, FlyAI will use its built-in default API key
   • Built-in key may have rate limits for frequent requests
   • No configuration required for basic usage

Environment Variables:

• FLYAI_API_KEY: Your FlyAI API key for flight search (optional, recommended to avoid rate limits)
• FLYAI_API_TOKEN: Alternative API token variable (optional)
• FLYAI_TOKEN: Another API token variable for compatibility (optional)

Note: FLYAI_API_KEY is optional. If not set, FlyAI will use its built-in default API key, but this may be subject to rate limiting for frequent requests.

Generate Flight Map#

bash

# Generate a flight map between two cities
flightmapify --origin "北京" --destination "上海" --date "2026-04-22" --output flight-beijing-shanghai.html

Parameters#

• --origin: Departure city (required)
• --destination: Arrival city (required)
• --date: Travel date in YYYY-MM-DD format (required)
• --output: Output HTML file name (required)
• --port: HTTP server port (default: 9000)

Integration#

FlightMapify integrates with the existing FlyAI skill for real-time flight search and booking capabilities. It uses Amap for map visualization and provides a clean, focused interface for flight planning.

API Keys#

• Amap API Key: Uses built-in default API key (no user key required)
• Custom Amap Key: Set AMAP_API_KEY environment variable to use your own key

Local Server Architecture#

• Flight search server runs locally on dynamic ports
• HTTP server serves from OpenClaw workspace directory
• All URLs use localhost for security and simplicity

Technical Details#

Server Architecture#

• Flight Search Server: Flask-based server on configurable port (default: 8790)
• HTTP Server: Lightweight server for map display (default: 9000)
• Port Management: Automatic port conflict resolution and server health checks

Flight Data#

• Direct Flights: Non-stop flights with price, duration, and booking links
• Connecting Flights: Multi-segment flights with transfer cities, complete pricing, and duration
• Route Visualization: Interactive map showing flight paths with animated markers
• Real-time Data: Live search results from FlyAI API

Environment Variables#

• FLYAI_API_KEY: Your FlyAI API key for flight search (optional, recommended to avoid rate limits)
• FLYAI_API_TOKEN: Alternative API token variable (optional)
• FLYAI_TOKEN: Another API token variable for compatibility (optional)

Note: FLYAI_API_KEY is optional. If not set, FlyAI will use its built-in default API key, but this may be subject to rate limiting for frequent requests. Setting your own API key is recommended for production use or high-volume requests.

Changelog#

Version 1.4.0 (2026-04-16)#

• ✅ Reverted to optional API Key configuration
• ✅ Support for FlyAI built-in default API key (may have rate limits)
• ✅ User-provided API Key recommended to avoid rate limiting
• ✅ Updated documentation with clear configuration options
• ✅ Enhanced input box width optimization for better UI
• ✅ Fixed city suggestion box width for better UX

Version 1.3.0 (2026-04-16)#

• ✅ Removed default API Key - now requires explicit user configuration
• ✅ Added clear error message when FLYAI_API_KEY is not set
• ✅ Updated documentation to reflect required API Key configuration
• ✅ Improved security by removing hardcoded API keys

Version 1.2.0 (2026-04-16)#

• ✅ Fixed connecting flight search functionality
• ✅ Added complete connecting flight details (route cities, prices, durations)
• ✅ Implemented OpenClaw skill configuration with user-configurable API Key
• ✅ Added automatic fallback to default FlyAI API Key when not configured
• ✅ Updated server manager to use Flask-based server
• ✅ Enhanced server management with .env file support
• ✅ Fixed API Key configuration issues (trial limit errors)
• ✅ Improved error handling and user feedback
• ✅ Removed flight-search-server-simple.py (now using Flask-based server exclusively)

Version 1.1.0#

• Initial release with basic flight search and map visualization

Examples#

bash

# Basic flight map
flightmapify --origin "北京" --destination "阿克苏" --date "2026-04-22" --output beijing-aksu-flight.html

# With custom port
flightmapify --origin "上海" --destination "乌鲁木齐" --date "2026-05-01" --output shanghai-urumqi-flight.html --port 8080

Troubleshooting Common Problems#

🔴 "No flights found" or Empty Results#

Possible Causes:

• API Rate Limits: Built-in FlyAI API key has trial limits
• Route Availability: Remote destinations may have limited flight options
• Date Too Far: Airlines may not have published schedules for distant dates

Solutions:

1. Get your own FlyAI API key from https://flyai.open.fliggy.com/console bash

   export FLYAI_API_KEY=your_api_key_here
   
   

2. Try closer dates (within 3-6 months)

3. Test with major city pairs first (Beijing-Shanghai, Guangzhou-Shenzhen)

🔴 404 File Not Found Error#

Cause: HTML file generated in wrong directory

Solution:

• The skill now uses dynamic workspace detection
• Files are always generated in your OpenClaw workspace directory
• Check that your workspace contains AGENTS.md or SOUL.md

🔴 Character Encoding Issues (乱码)#

Symptoms: Chinese cities show as garbled text like "阿克苯"

Cause: URL parameter double-decoding

Solution:

• This is fixed in version 1.4.0
• Ensure you're using the latest version from ClawHub
• If issues persist, restart your terminal session

🔴 Flight Search Server Won't Start#

Symptoms: "Failed to start flight search server on port XXXX"

Causes & Solutions:

1. Port already in use: Server automatically finds next available port

2. Missing dependencies: Ensure flyai CLI is installed bash

   npm install -g @openclaw/flyai
   
   

3. Permission issues: Run with appropriate permissions

🔴 API Key Configuration Issues#

Problem: Still getting rate limits after setting API key

Solutions:

1. Verify key is set correctly: bash

   echo $FLYAI_API_KEY
   
   

2. Check FlyAI config file: bash

   cat ~/.flyai/config.json
   
   

3. Use environment variable method (more reliable): bash

   export FLYAI_API_KEY=sk_your_actual_key
   flightmapify --origin "北京" --destination "上海" --date "2026-04-25" --output test.html
   
   

🔴 Map Not Loading or JavaScript Errors#

Causes:

• Amap API key issues
• Network connectivity problems
• Browser security restrictions

Solutions:

1. Amap key is built-in - no user configuration needed
2. Open HTML file via HTTP server (not file:// protocol)
3. Check browser console for specific error messages

🟡 Performance Issues with Many Flights#

Symptoms: Slow loading with routes having many connecting options

Solutions:

• The system shows top 20 flights by default
• Use direct flights only for faster results if needed
• Close other browser tabs to free memory

🔧 Debugging Tips#

1. Check server logs: bash

   # Look for Python server output in your terminal
   
   

2. Test FlyAI CLI directly: bash

   flyai search-flight --origin "北京" --destination "上海" --dep-date "2026-04-25"
   
   

3. Verify file locations: bash

   ls -la ~/.openclaw/workspace/*.html
   
   

4. Check port availability: bash

   lsof -i :9000  # Replace with your port
   
   

📞 When to Contact Support#

Contact the skill maintainer if:

• You've tried all troubleshooting steps above
• The issue persists with major city pairs (Beijing-Shanghai)
• You see consistent errors across different dates/routes
• The HTML file generates but shows completely blank map

Include in your report:

• OpenClaw version ( openclaw --version)
• Skill version (check SKILL.md)
• Exact command used
• Error messages from terminal
• Screenshot of the HTML page (if applicable)