# FlightTracer: Tracking ADS-B Exchange flights
[](https://pypi.org/project/flight-tracer/)
[](https://creativecommons.org/publicdomain/zero/1.0/)
FlightTracer is a Python package for fetching, processing, storing and plotting flight trace data from [ADS-B Exchange](https://globe.adsbexchange.com/). It provides tools for managing flight data and offers flexible options for users. The project is new and under development.
---
## Features
- Fetches flight trace data from ADS-B Exchange
- Identifies flight legs by detecting time gaps and handling Zulu day transitions
- Converts raw flight trace data into GeoDataFrames for easy analysis
- Saves processed flight data in CSV, GeoJSON or shapefile formats
- Visualizes flight paths with customizable basemaps and clear leg differentiation
- Supports AWS S3 uploads for cloud storage
- Offers customization options for file formats and filtering
- **Now includes a command-line interface (CLI) for easy execution**
---
## Installation
FlightTracer is available on PyPI and can be installed using:
```bash
pip install flight-tracer
```
Alternatively, install the latest development version from GitHub:
```bash
pip install git+https://github.com/stiles/flight_tracer.git
```
### Dependencies
FlightTracer requires the following Python packages:
- `requests`
- `pandas`
- `geopandas`
- `boto3`
- `matplotlib`
- `contextily`
- `shapely`
- `click` (for CLI support)
These dependencies will be installed automatically with `pip`.
---
## Using FlightTracer via CLI
With the new CLI support, FlightTracer can be run directly from the command line.
### **CLI options overview**
| Option | Description |
|------------------|-------------|
| `--icao` | ICAO aircraft ID (required, can be multiple) |
| `--start` | Start date (YYYY-MM-DD) |
| `--end` | End date (YYYY-MM-DD) |
| `--output` | Directory for saving fetched data |
| `--input` | Path to input file for processing/exporting/uploading |
| `--format` | Output format: `csv`, `geojson`, `shp` |
| `--filter-ground` | Filter out ground-level points (default: True) |
| `--plot` | Generate a visualization of the flight trace |
| `--bucket` | AWS S3 bucket name for uploads |
| `--aws-profile` | AWS profile for authentication when uploading |
These commands ensure seamless of FlightTracer's features via the command line.
### **Basic command: Fetch raw flight trace data**
```bash
flight-tracer fetch --icao A11F59 --start 2025-02-07 --end 2025-02-08 --output data/
```
This fetches flight data for aircraft `A11F59` for the given date range and saves it as a CSV file.
### **Processing fetched data**
```bash
flight-tracer process --input data/raw_A11F59_2025-02-07_2025-02-08.csv --filter-ground
```
This processes the fetched flight trace data, filtering out ground-level points and saving the result in a structured format.
### **Exporting processed data**
```bash
flight-tracer export --input data/processed_A11F59_2025-02-07_2025-02-08.geojson --format geojson
```
This exports the processed flight data in GeoJSON format (CSV and shapefile options are also available).
### **Plotting the flight trace**
```bash
flight-tracer plot --input data/processed_A11F59_2025-02-07_2025-02-08.geojson --output visuals/flight_map_A11F59_2025-02-07_2025-02-08.png
```
This generates a visualization of the flight trace and saves it as an image file.
### **Uploading processed data to AWS S3**
```bash
flight-tracer upload --input data/processed_A11F59_2025-02-07_2025-02-08.geojson --bucket my-bucket --aws-profile my-profile
```
This uploads the processed flight trace data to the specified AWS S3 bucket using the provided AWS profile.
---
## Using FlightTracer in Python
FlightTracer can also be used as a Python library for more flexibility.
### **Basic example**
```python
from flight_tracer import FlightTracer
from datetime import date
# Initialize the FlightTracer with an aircraft ID
tracer = FlightTracer(aircraft_ids=["A11F59"])
# Define the date range for fetching trace data
start = date(2025, 2, 7)
end = date(2025, 2, 8)
# Fetch flight data
raw_df = tracer.get_traces(start, end)
# Process the raw data into a GeoDataFrame
if not raw_df.empty:
gdf = tracer.process_flight_data(raw_df)
print(gdf.head())
```
---
---
## Using FlightTracer in Python
FlightTracer can also be used as a Python library for more flexibility.
### **Basic example**
```python
from flight_tracer import FlightTracer
from datetime import date
# Initialize the FlightTracer with an aircraft ID
tracer = FlightTracer(aircraft_ids=["A11F59"])
# Define the date range for fetching trace data
start = date(2025, 2, 7)
end = date(2025, 2, 8)
# Fetch flight data
raw_df = tracer.get_traces(start, end)
# Process the raw data into a GeoDataFrame
if not raw_df.empty:
gdf = tracer.process_flight_data(raw_df)
print(gdf.head())
```
### **Converting to a Specific Time Zone**
By default, ADS-B times are in UTC. Users can convert `point_time` to their local time zone as needed:
```python
import pytz
# Convert to US/Pacific Time
gdf["point_time_pacific"] = gdf["point_time"].dt.tz_localize("UTC").dt.tz_convert("US/Pacific")
# Convert to Eastern Time
gdf["point_time_eastern"] = gdf["point_time"].dt.tz_localize("UTC").dt.tz_convert("America/New_York")
```
To see all available time zones:
```python
import pytz
print(pytz.all_timezones)
```
---
### Customizing output
FlightTracer provides options to save data in different formats and configure the output directory:
#### **Supported file formats**
- CSV
- GeoJSON
- Esri shapefile
#### **Example: Exporting data**
```python
# Save processed data locally
tracer.export_flight_data(gdf, base_path="data/flight_traces", export_format="geojson") # or "shp"
```
---
### **AWS S3 integration**
Easily upload processed data to AWS S3 for cloud storage. Provide your AWS credentials or use an AWS profile:
#### **Example: Uploading to S3**
```python
aws_creds = {
"aws_access_key_id": "your-access-key",
"aws_secret_access_key": "your-secret-key"
}
tracer.upload_to_s3(
gdf,
bucket_name="your-bucket",
csv_object_name="flight_data.csv",
geojson_object_name="flight_data.geojson"
)
```
---
## **Advanced features**
### **Metadata mapping**
Enrich your flight data with custom metadata using mapping options.
#### **Example: Adding metadata**
```python
meta_df = pd.DataFrame({
"flight": ["AAL124", "UAL1053"],
"airline": ["American Airlines", "United Airlines"]
})
mapping_info = (meta_df, "flight", "airline", "airline")
# Pass mapping_info to process_flight_data
gdf = tracer.process_flight_data(raw_df, mapping_info=mapping_info)
```
### **Custom time thresholds for legs**
Customize the time gap threshold for detecting new flight legs:
#### **Example: Adjusting time gap threshold**
```python
tracer.set_time_gap_threshold(minutes=45)
```
---
## Outputs
The example above would output two GeoJSON files: One with point features for each moment captured during the aircraft's flight and another with lines representing the overall route(s). Legs of the flights are differentiated in the `flight_leg` item. The script also outputs a CSV and a simple map plot.
```json
"features": [
{
"type": "Feature",
"properties": {
"point_time": "2025-02-08T02:38:02.920",
"flight_date_pst": "2025-02-07",
"altitude": "30000",
"ground_speed": 408.4,
"heading": 253.2,
"lat": 35.968307,
"lon": -97.348509,
"icao": "a11f59",
"call_sign": "UAL333",
"leg_id": 1,
"flight_leg": "UAL333_leg1"
},
"geometry": {
"type": "Point",
"coordinates": [
-97.348509,
35.968307
]
}
}
]
```
**Notes:**
- Values such as altitude and ground speed are raw and uncorrected
- ADS-B datetimes are UTC, or Zulu, but FlightTracer users can concert that to a local time zone.
The plot has different colors for the various legs that day to help you identify them more clearly as you use the data for more advanced visualizations using QGIS or other tools.
---
## **Roadmap**
- **CLI option**: Add a command-line interface for easier usage
- **Improved metadata integration**: Automatically enrich flight data with external sources (e.g., FAA, ICAO)
- **Parallel processing**: Optimize for large datasets
- **Better visualizations**: Add support for tools like Altair or Plotly
- **Analysis tools**: Better understand a flight's speed and altitude changes
---
## **Credits**
Thanks to [ADS-B Exchange](https://globe.adsbexchange.com/) for providing open flight data. Please consider supporting their service by [subscribing](https://store.adsbexchange.com/collections/subscriptions) or [contributing data](https://www.adsbexchange.com/ways-to-join-the-exchange/).
---
## **License**
This project is licensed under the **Creative Commons CC0 1.0 Universal** Public Domain Dedication.
[](https://creativecommons.org/publicdomain/zero/1.0/legalcode)
Raw data
{
"_id": null,
"home_page": "https://github.com/stiles/flight-tracer",
"name": "flight-tracer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Matt Stiles",
"author_email": "mattstiles@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/28/8b/0ff0aec9418b75327573c5252db0ba042b296bbeda7580a96f3d6cfa6d77/flight_tracer-0.1.7.tar.gz",
"platform": null,
"description": "# FlightTracer: Tracking ADS-B Exchange flights\n\n[](https://pypi.org/project/flight-tracer/)\n[](https://creativecommons.org/publicdomain/zero/1.0/)\n\nFlightTracer is a Python package for fetching, processing, storing and plotting flight trace data from [ADS-B Exchange](https://globe.adsbexchange.com/). It provides tools for managing flight data and offers flexible options for users. The project is new and under development.\n\n---\n\n## Features\n\n- Fetches flight trace data from ADS-B Exchange\n- Identifies flight legs by detecting time gaps and handling Zulu day transitions\n- Converts raw flight trace data into GeoDataFrames for easy analysis\n- Saves processed flight data in CSV, GeoJSON or shapefile formats\n- Visualizes flight paths with customizable basemaps and clear leg differentiation\n- Supports AWS S3 uploads for cloud storage\n- Offers customization options for file formats and filtering\n- **Now includes a command-line interface (CLI) for easy execution**\n\n---\n\n## Installation\n\nFlightTracer is available on PyPI and can be installed using:\n\n```bash\npip install flight-tracer\n```\n\nAlternatively, install the latest development version from GitHub:\n\n```bash\npip install git+https://github.com/stiles/flight_tracer.git\n```\n\n### Dependencies\n\nFlightTracer requires the following Python packages:\n- `requests`\n- `pandas`\n- `geopandas`\n- `boto3`\n- `matplotlib`\n- `contextily`\n- `shapely`\n- `click` (for CLI support)\n\nThese dependencies will be installed automatically with `pip`.\n\n---\n\n## Using FlightTracer via CLI\n\nWith the new CLI support, FlightTracer can be run directly from the command line.\n\n### **CLI options overview**\n\n| Option | Description |\n|------------------|-------------|\n| `--icao` | ICAO aircraft ID (required, can be multiple) |\n| `--start` | Start date (YYYY-MM-DD) |\n| `--end` | End date (YYYY-MM-DD) |\n| `--output` | Directory for saving fetched data |\n| `--input` | Path to input file for processing/exporting/uploading |\n| `--format` | Output format: `csv`, `geojson`, `shp` |\n| `--filter-ground` | Filter out ground-level points (default: True) |\n| `--plot` | Generate a visualization of the flight trace |\n| `--bucket` | AWS S3 bucket name for uploads |\n| `--aws-profile` | AWS profile for authentication when uploading |\n\nThese commands ensure seamless of FlightTracer's features via the command line.\n\n### **Basic command: Fetch raw flight trace data**\n```bash\nflight-tracer fetch --icao A11F59 --start 2025-02-07 --end 2025-02-08 --output data/\n```\nThis fetches flight data for aircraft `A11F59` for the given date range and saves it as a CSV file.\n\n### **Processing fetched data**\n```bash\nflight-tracer process --input data/raw_A11F59_2025-02-07_2025-02-08.csv --filter-ground\n```\nThis processes the fetched flight trace data, filtering out ground-level points and saving the result in a structured format.\n\n### **Exporting processed data**\n```bash\nflight-tracer export --input data/processed_A11F59_2025-02-07_2025-02-08.geojson --format geojson\n```\nThis exports the processed flight data in GeoJSON format (CSV and shapefile options are also available).\n\n### **Plotting the flight trace**\n```bash\nflight-tracer plot --input data/processed_A11F59_2025-02-07_2025-02-08.geojson --output visuals/flight_map_A11F59_2025-02-07_2025-02-08.png\n```\nThis generates a visualization of the flight trace and saves it as an image file.\n\n### **Uploading processed data to AWS S3**\n```bash\nflight-tracer upload --input data/processed_A11F59_2025-02-07_2025-02-08.geojson --bucket my-bucket --aws-profile my-profile\n```\nThis uploads the processed flight trace data to the specified AWS S3 bucket using the provided AWS profile.\n\n---\n\n## Using FlightTracer in Python\n\nFlightTracer can also be used as a Python library for more flexibility.\n\n### **Basic example**\n\n```python\nfrom flight_tracer import FlightTracer\nfrom datetime import date\n\n# Initialize the FlightTracer with an aircraft ID\ntracer = FlightTracer(aircraft_ids=[\"A11F59\"])\n\n# Define the date range for fetching trace data\nstart = date(2025, 2, 7)\nend = date(2025, 2, 8)\n\n# Fetch flight data\nraw_df = tracer.get_traces(start, end)\n\n# Process the raw data into a GeoDataFrame\nif not raw_df.empty:\n gdf = tracer.process_flight_data(raw_df)\n print(gdf.head())\n```\n\n---\n\n---\n\n## Using FlightTracer in Python\n\nFlightTracer can also be used as a Python library for more flexibility.\n\n### **Basic example**\n\n```python\nfrom flight_tracer import FlightTracer\nfrom datetime import date\n\n# Initialize the FlightTracer with an aircraft ID\ntracer = FlightTracer(aircraft_ids=[\"A11F59\"])\n\n# Define the date range for fetching trace data\nstart = date(2025, 2, 7)\nend = date(2025, 2, 8)\n\n# Fetch flight data\nraw_df = tracer.get_traces(start, end)\n\n# Process the raw data into a GeoDataFrame\nif not raw_df.empty:\n gdf = tracer.process_flight_data(raw_df)\n print(gdf.head())\n```\n\n### **Converting to a Specific Time Zone**\nBy default, ADS-B times are in UTC. Users can convert `point_time` to their local time zone as needed:\n\n```python\nimport pytz\n\n# Convert to US/Pacific Time\ngdf[\"point_time_pacific\"] = gdf[\"point_time\"].dt.tz_localize(\"UTC\").dt.tz_convert(\"US/Pacific\")\n\n# Convert to Eastern Time\ngdf[\"point_time_eastern\"] = gdf[\"point_time\"].dt.tz_localize(\"UTC\").dt.tz_convert(\"America/New_York\")\n```\n\nTo see all available time zones:\n```python\nimport pytz\nprint(pytz.all_timezones)\n```\n\n---\n\n### Customizing output\n\nFlightTracer provides options to save data in different formats and configure the output directory:\n\n#### **Supported file formats**\n- CSV\n- GeoJSON\n- Esri shapefile\n\n#### **Example: Exporting data**\n```python\n# Save processed data locally\ntracer.export_flight_data(gdf, base_path=\"data/flight_traces\", export_format=\"geojson\") # or \"shp\"\n```\n---\n\n### **AWS S3 integration**\n\nEasily upload processed data to AWS S3 for cloud storage. Provide your AWS credentials or use an AWS profile:\n\n#### **Example: Uploading to S3**\n```python\naws_creds = {\n \"aws_access_key_id\": \"your-access-key\",\n \"aws_secret_access_key\": \"your-secret-key\"\n}\n\ntracer.upload_to_s3(\n gdf,\n bucket_name=\"your-bucket\",\n csv_object_name=\"flight_data.csv\",\n geojson_object_name=\"flight_data.geojson\"\n)\n```\n\n---\n\n## **Advanced features**\n\n### **Metadata mapping**\nEnrich your flight data with custom metadata using mapping options.\n\n#### **Example: Adding metadata**\n```python\nmeta_df = pd.DataFrame({\n \"flight\": [\"AAL124\", \"UAL1053\"],\n \"airline\": [\"American Airlines\", \"United Airlines\"]\n})\nmapping_info = (meta_df, \"flight\", \"airline\", \"airline\")\n\n# Pass mapping_info to process_flight_data\ngdf = tracer.process_flight_data(raw_df, mapping_info=mapping_info)\n```\n\n### **Custom time thresholds for legs**\nCustomize the time gap threshold for detecting new flight legs:\n\n#### **Example: Adjusting time gap threshold**\n```python\ntracer.set_time_gap_threshold(minutes=45)\n```\n\n---\n\n## Outputs\n\nThe example above would output two GeoJSON files: One with point features for each moment captured during the aircraft's flight and another with lines representing the overall route(s). Legs of the flights are differentiated in the `flight_leg` item. The script also outputs a CSV and a simple map plot.\n\n```json\n\"features\": [\n {\n \"type\": \"Feature\",\n \"properties\": {\n \"point_time\": \"2025-02-08T02:38:02.920\",\n \"flight_date_pst\": \"2025-02-07\",\n \"altitude\": \"30000\",\n \"ground_speed\": 408.4,\n \"heading\": 253.2,\n \"lat\": 35.968307,\n \"lon\": -97.348509,\n \"icao\": \"a11f59\",\n \"call_sign\": \"UAL333\",\n \"leg_id\": 1,\n \"flight_leg\": \"UAL333_leg1\"\n },\n \"geometry\": {\n \"type\": \"Point\",\n \"coordinates\": [\n -97.348509,\n 35.968307\n ]\n }\n }\n]\n```\n\n**Notes:**\n\n- Values such as altitude and ground speed are raw and uncorrected\n- ADS-B datetimes are UTC, or Zulu, but FlightTracer users can concert that to a local time zone.\n\nThe plot has different colors for the various legs that day to help you identify them more clearly as you use the data for more advanced visualizations using QGIS or other tools.\n\n\n\n---\n\n## **Roadmap**\n\n- **CLI option**: Add a command-line interface for easier usage\n- **Improved metadata integration**: Automatically enrich flight data with external sources (e.g., FAA, ICAO)\n- **Parallel processing**: Optimize for large datasets\n- **Better visualizations**: Add support for tools like Altair or Plotly\n- **Analysis tools**: Better understand a flight's speed and altitude changes\n\n---\n\n## **Credits**\nThanks to [ADS-B Exchange](https://globe.adsbexchange.com/) for providing open flight data. Please consider supporting their service by [subscribing](https://store.adsbexchange.com/collections/subscriptions) or [contributing data](https://www.adsbexchange.com/ways-to-join-the-exchange/).\n\n---\n\n## **License**\nThis project is licensed under the **Creative Commons CC0 1.0 Universal** Public Domain Dedication.\n\n[](https://creativecommons.org/publicdomain/zero/1.0/legalcode)\n",
"bugtrack_url": null,
"license": "CC0-1.0",
"summary": "A package to fetch, process, store and plot aircraft trace data from ADS-B Exchange",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/stiles/flight-tracer"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "261f6789b778b9ef0907dab2a32a51f6250ce9348852bdcce1cd1c98bc1f93b7",
"md5": "8b9b080fd6564ffaaa68e57291b378cb",
"sha256": "51a41e9cfdc74258568868cac13b3ae880ec8cac6306859c67c97e1780ecf67b"
},
"downloads": -1,
"filename": "flight_tracer-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b9b080fd6564ffaaa68e57291b378cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15219,
"upload_time": "2025-02-09T23:10:26",
"upload_time_iso_8601": "2025-02-09T23:10:26.973835Z",
"url": "https://files.pythonhosted.org/packages/26/1f/6789b778b9ef0907dab2a32a51f6250ce9348852bdcce1cd1c98bc1f93b7/flight_tracer-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "288b0ff0aec9418b75327573c5252db0ba042b296bbeda7580a96f3d6cfa6d77",
"md5": "88ae46cc52b3e71b2548b2d9d0ed8021",
"sha256": "af935cc141208d0280ba45b0c5f1616b6f90ffa4e05ed3c66ba035d67a4956e5"
},
"downloads": -1,
"filename": "flight_tracer-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "88ae46cc52b3e71b2548b2d9d0ed8021",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18056,
"upload_time": "2025-02-09T23:10:28",
"upload_time_iso_8601": "2025-02-09T23:10:28.818910Z",
"url": "https://files.pythonhosted.org/packages/28/8b/0ff0aec9418b75327573c5252db0ba042b296bbeda7580a96f3d6cfa6d77/flight_tracer-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-09 23:10:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stiles",
"github_project": "flight-tracer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "flight-tracer"
}
JSON
