Metadata-Version: 2.4
Name: pyfr24
Version: 0.1.7
Summary: A Python client for the Flightradar24 API with CLI support
Home-page: https://github.com/stiles/pyfr24
Author: Matt Stiles
Author-email: mattstiles@gmail.com
Keywords: flightradar24,flight,tracking,aviation,api,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: matplotlib
Requires-Dist: geopandas
Requires-Dist: contextily
Requires-Dist: shapely
Requires-Dist: pandas
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Pyfr24

[![Documentation Status](https://readthedocs.org/projects/pyfr24/badge/?version=latest)](https://pyfr24.readthedocs.io/en/latest/?badge=latest)

A Python client for the [Flightradar24 API](https://fr24api.flightradar24.com/) 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/](https://pyfr24.readthedocs.io/)

## Installation

```bash
# 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

```python
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
output_dir = api.export_flight_data(
    "39bebe6e",
    background='osm',        # OpenStreetMap background
    orientation='horizontal'  # 16:9 aspect ratio
)
```

**Full Python docs:** [https://pyfr24.readthedocs.io/en/latest/usage/api/](https://pyfr24.readthedocs.io/en/latest/usage/api/)

### Command-line interface

```bash
# 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
pyfr24 smart-export --flight UA2151 --date 2025-04-22
```

**Full CLI reference:** [https://pyfr24.readthedocs.io/en/latest/usage/cli/](https://pyfr24.readthedocs.io/en/latest/usage/cli/)

## API token

Your Flightradar24 API token can be provided:

1. Via environment variable:
   ```bash
   export FLIGHTRADAR_API_KEY="your_api_token"
   ```

2. As a command-line argument:
   ```bash
   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:

```bash
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)
- Data export in multiple formats (CSV, GeoJSON and KML)
- Customizable map visualizations with multiple background options
- Speed and altitude profile charts
- Robust error handling and logging
- Comprehensive testing
- Interactive CLI export by flight number and date (`smart-export` command)
- Topline summary output (`toplines.json`)

## 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.
