🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

Flightmapify

by @rudy2steiner

Find cheapest flights and create interactive flight route maps with real-time flight search.

Versionv1.4.6
Downloads718
TERMINAL
clawhub install flightmapify

πŸ“– About This Skill


name: flightmapify version: 1.4.6 description: Find cheapest flights and create interactive flight route maps with real-time flight search. author: rudy2steiner license: MIT tags: [flights, maps, routing, flyai, travel, interactive]

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

       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

    # 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

    # 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

       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

       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:

       echo $FLYAI_API_KEY
       
    2. Check FlyAI config file:
       cat ~/.flyai/config.json
       
    3. Use environment variable method (more reliable):
       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:

       # Look for Python server output in your terminal
       

    2. Test FlyAI CLI directly:

       flyai search-flight --origin "εŒ—δΊ¬" --destination "上桷" --dep-date "2026-04-25"
       

    3. Verify file locations:

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

    4. Check port availability:

       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)
  • πŸ’‘ Examples

    # 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