Pyfr24

A Python client for the Flightradar24 API that provides an interface to fetch, plot and analyze flight data. The package includes both a Python API and a command-line interface for accessing flight data.

Full documentation: https://pyfr24.readthedocs.io/

Installation

# Install from PyPI
pip install pyfr24

# Or from source
git clone https://github.com/stiles/pyfr24.git
cd pyfr24
pip install -e .

Basic usage

Python API

from pyfr24 import FR24API

# Initialize the client
api = FR24API("your_api_token")

# Get flight tracks for a specific flight ID
tracks = api.get_flight_tracks("39bebe6e")

# Export flight data with enhanced features
output_dir = api.export_flight_data(
    "39bebe6e",
    background='esri-satellite',  # Satellite background
    aspect='16:9',                # Fixed 16:9 output
    timezone='America/New_York'   # Convert to Eastern Time
)

Full Python docs: https://pyfr24.readthedocs.io/en/latest/usage/api/

Command-line interface

# Export flight data
pyfr24 export-flight --flight-id 39a84c3c --output-dir data/flight_39a84c3c

# Get live flights for an aircraft registration
pyfr24 live-flights --registration N12345

# Get flight positions within a bounding box (Los Angeles area)
pyfr24 flight-positions --bounds "33.5,-118.8,34.5,-117.5"

# Smart export with enhanced features
pyfr24 smart-export --flight UA2151 --date 2025-04-22 \
                    --timezone "America/New_York" \
                    --background esri-satellite \
                    --aspect 3:2

Full CLI reference: https://pyfr24.readthedocs.io/en/latest/usage/cli/

API token

Your Flightradar24 API token can be provided:

1. Via environment variable:

   export FLIGHTRADAR_API_KEY="your_api_token"
   

2. As a command-line argument:

   pyfr24 --token "your_api_token" flight-summary --flight BA123
   

3. Through an interactive prompt when no token is provided

Smart export (new!)

Easily export all data for a flight when you know the flight number and date, but not the internal flight ID. This command is ideal for quickly investigating incidents or flights reported in the news, as it will look up all matching flights for the given number and date, prompt you to select if there are multiple, and export all relevant data and visualizations in one step.

Export all data for a flight by flight number and date, with interactive selection if there are multiple matches:

pyfr24 smart-export --flight UA2151 --date 2025-04-22

• If multiple flights are found, you'll be prompted to select the correct one.
• The output directory is named automatically (e.g., data/UA2151_2025-04-22_KEWR-KDEN_3a01b036).
• A toplines.json file is created with a summary of the exported flight.

Example output:

Multiple flights found for UA2151 on 2025-04-22:
[0] 3a00e15e | KPWM  KEWR | 2025-04-22T10:34–2025-04-22T11:46 | N37554 | B39M
[1] 3a01b036 | KEWR  KDEN | 2025-04-22T14:48–2025-04-22T18:53 | N28457 | B739
Select a flight to export [0-1]: 1
...
Export complete!

Features

• Flight data retrieval (live flights, historical tracks and detailed info)
• Publication-ready visualizations:
  • Headline, dek and source line laid out around every map and chart
  • Fixed aspect ratios (16:9, 3:2, 4:3, 1:1, 9:16) that the saved file matches exactly
  • Key-free map backgrounds from OpenStreetMap (default), Esri and OpenTopoMap, plus Mapbox with your own token
  • Timezone conversion with automatic DST handling
  • AP-style dates and time axes that don't collide
• Data export in multiple formats (CSV, GeoJSON and KML)
• Interactive CLI export by flight number and date (smart-export command)
• Comprehensive output including topline summaries (toplines.json)
• Robust error handling and logging
• Comprehensive testing

Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass with python run_tests.py
5. Submit a pull request

License

This project is licensed under the MIT License.