flight-tracer 0.1.0__tar.gz

flight_tracer-0.1.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

flight_tracer-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

flight_tracer-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.2
+Name: flight_tracer
+Version: 0.1.0
+Summary: A package to fetch, process, store and plot aircraft trace data from ADS-B Exchange.
+Home-page: https://github.com/stiles/flight_tracer
+Author: Matt Stiles
+Author-email: mattstiles@gmail.com
+License: CC0-1.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: pandas
+Requires-Dist: geopandas
+Requires-Dist: boto3
+Requires-Dist: matplotlib
+Requires-Dist: contextily
+Requires-Dist: shapely
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Tracking ADS-B Exchange flights
+
+FlightTracer is a Python package to fetch and process aircraft trace data from ADS-B Exchange. It supports a single ICAO code or a list of codes — and it has an option to upload processed data as CSV and GeoJSON to Amazon S3. FlightTracer also detects separate flight legs based on significant time gaps and creates a combined flight leg identifier (call_sign, date, leg) for easier differentiation in GIS tools. In addition, the package also provides plotting capabilities with a basemap and an option to save the plot as a PNG.
+
+This project is in the early stages of development. Contributions and feedback welcome. 
+
+## Installation
+
+1. Clone the repository or download the source code  
+2. Install the required dependencies using pip
+
+~~~bash
+pip install requests pandas geopandas boto3 contextily matplotlib
+~~~
+
+## Usage
+
+FlightTracer can be used with either a list of aircraft IDs or a metadata URL that contains aircraft information. You can also configure AWS credentials if you wish to upload the output to S3. In addition, you can pass an AWS profile name if you have multiple sets of credentials in your environment.
+
+### Example
+
+Below is an example of how to use FlightTracer:
+
+~~~python
+#!/usr/bin/env python
+"""
+fetch_example.py
+
+This example fetches real flight trace data, processes it (computing the continuous ping_time
+and inferring separate flight legs based on time gaps), saves the results locally
+with a filename that includes the ICAO code(s) and today's date, and optionally
+uploads the CSV and GeoJSON files to S3 using a specified AWS profile.
+It also shows how to generate a plot of the flight activity and save the plot as a PNG.
+"""
+
+import os
+from datetime import date, datetime
+from flight_tracer import FlightTracer
+import geopandas as gpd
+
+# Option 1: Use explicit AWS credentials (via environment variables or directly)
+aws_credentials = {
+    "aws_access_key_id": os.getenv("MY_AWS_ACCESS_KEY_ID"),
+    "aws_secret_access_key": os.getenv("MY_AWS_SECRET_ACCESS_KEY")
+}
+
+# Option 2: Alternatively, use an AWS profile from your environment
+aws_profile = os.getenv("MY_AWS_PROFILE")  # e.g., "my_profile_name"
+
+# Initialize flight_tracer with either explicit credentials or an AWS profile.
+# For example, to use explicit credentials:
+# tracer = flight_tracer(aircraft_ids=["a97753"], aws_creds=aws_credentials)
+# Or, to use an AWS profile:
+tracer = FlightTracer(aircraft_ids=["a97753"], aws_profile=aws_profile)
+
+# Define the date range for trace data
+start = date(2025, 1, 28)
+end = date(2025, 2, 1)
+
+# Fetch raw flight trace data from ADS-B Exchange
+print("Fetching raw flight trace data...")
+raw_df = tracer.get_traces(start, end)
+if raw_df.empty:
+    print("No valid data to process.")
+else:
+    print("Raw data sample:")
+    print(raw_df.head())
+
+    # Process trace data into a GeoDataFrame (computing continuous ping_time in UTC
+    # and detecting flight leg changes based on time gaps). A new 'flight_leg' column is
+    # created that combines call_sign, flight_date, and leg_id.
+    print("\nProcessing flight data into a GeoDataFrame...")
+    gdf = tracer.process_flight_data(raw_df)
+
+    # Optionally, retain ground points: 
+    # gdf = tracer.process_flight_data(raw_df, filter_ground=False)
+    
+    print("Processed GeoDataFrame sample:")
+    print(gdf.head())
+    
+    # Optionally, inspect the unique flight legs detected in the data.
+    print("\nUnique flight legs detected:")
+    print(gdf["flight_leg"].unique())
+
+    # Build dynamic filenames that include the ICAO code(s) and today's date
+    icao_str = "_".join(tracer.aircraft_ids)
+    date_str = datetime.today().strftime("%Y%m%d")
+    csv_filename = f"data/flight_traces_{icao_str}_{date_str}.csv"
+    geojson_filename = f"data/flight_traces_{icao_str}_{date_str}.geojson"
+
+    # Save the processed data locally as CSV and GeoJSON
+    gdf.to_csv(csv_filename, index=False)
+    gdf.to_file(geojson_filename, driver="GeoJSON")
+    print(f"\nSaved processed data locally as '{csv_filename}' and '{geojson_filename}'.")
+
+    # Export linestring geometry for each flight leg
+    linestring_geojson_filename = f"data/flight_traces_lines_{icao_str}_{date_str}.geojson"
+    tracer.export_linestring_geojson(gdf, linestring_geojson_filename)
+
+    # Optionally upload the processed files to S3
+    bucket_name = "your-bucket-name"  # replace with your bucket name
+    csv_object_name = f"flight_tracer/flight_traces_{icao_str}_{date_str}.csv"
+    geojson_object_name = f"flight_tracer/flight_traces_{icao_str}_{date_str}.geojson"
+    print("\nUploading files to S3 (if AWS credentials or profile are configured)...")
+    tracer.upload_to_s3(gdf, bucket_name, csv_object_name, geojson_object_name)
+    print("Upload process completed.")
+
+    # Plot the points with a basemap and optionally save the plot as a PNG
+    fig_filename = f"visuals/flight_map_{icao_str}_{date_str}.png"
+    tracer.plot_flights(gdf, geometry_type='points', figsize=(12,10), fig_filename=fig_filename)
+~~~
+
+## Configuration
+
+The package supports the following configurations:
+
+- **Aircraft IDs or metadata URL**: Provide either a list of ICAO codes or a metadata URL to extract aircraft information.  
+- **AWS credentials or profile**: Pass AWS credentials as a dictionary, specify an AWS profile, or set them as environment variables.  
+- **Date range**: Define the start and end dates to fetch trace data.
+
+## Notes
+
+- Ensure that your AWS credentials or profile are configured correctly if you wish to use the S3 upload feature.  
+- The package fetches data from ADS-B Exchange so the availability of data depends on the public API.  
+- Flight leg detection is based on a configurable time gap threshold (default is 15 minutes). Adjust as needed for your data.  
+- Plotting functionality includes an option to expand the plotted extent (via `pad_factor`) for broader context and to save the plot as a PNG.
+
+## Roadmap for Enhancements
+
+#### Enrich with external metadata:
+- Build tools to “hydrate” your flight data with additional aircraft metadata from external sources such as FAA, ICAO, or other databases (e.g., aircraft type, operator, age, etc.).
+
+#### Package distribution:
+- Finalize the code structure (including tests, documentation, and a setup script) and publish the package to PyPI for installation via pip.
+
+#### Enhanced documentation and examples:
+- Update the README with comprehensive, end-to-end examples for various scenarios (e.g., pulling all flights for a month of a particular aircraft, processing a list of aircraft from a metadata URL, etc.), including usage examples for linestring export, leg splitting, and metadata enrichment.
+
+#### Configurable thresholds and options:
+- Allow users to adjust parameters like the time-gap threshold for determining new flight legs, output formats, and which metadata fields to hydrate.
+
+#### Performance and error handling improvements:
+- Add caching or parallel processing options to improve performance when fetching data over a long date range or for multiple aircraft.
+- Improve error handling to gracefully skip problematic dates or flights while logging issues.
+
+## License
+
+This project is licensed under the **Creative Commons CC0 1.0 Universal (CC0 1.0) Public Domain Dedication**.  
+
+This means that to the extent possible under law, the creator has waived all copyright and related or neighboring rights to this work. 
+
+You can copy, modify, distribute, and perform the work, even for commercial purposes, all without asking permission.
+
+For more details, refer to the full [CC0 1.0 Universal License](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
+
+![CC0 Badge](https://licensebuttons.net/p/zero/1.0/88x31.png)

flight_tracer-0.1.0/README.md

@@ -0,0 +1,156 @@
+# Tracking ADS-B Exchange flights
+
+FlightTracer is a Python package to fetch and process aircraft trace data from ADS-B Exchange. It supports a single ICAO code or a list of codes — and it has an option to upload processed data as CSV and GeoJSON to Amazon S3. FlightTracer also detects separate flight legs based on significant time gaps and creates a combined flight leg identifier (call_sign, date, leg) for easier differentiation in GIS tools. In addition, the package also provides plotting capabilities with a basemap and an option to save the plot as a PNG.
+
+This project is in the early stages of development. Contributions and feedback welcome. 
+
+## Installation
+
+1. Clone the repository or download the source code  
+2. Install the required dependencies using pip
+
+~~~bash
+pip install requests pandas geopandas boto3 contextily matplotlib
+~~~
+
+## Usage
+
+FlightTracer can be used with either a list of aircraft IDs or a metadata URL that contains aircraft information. You can also configure AWS credentials if you wish to upload the output to S3. In addition, you can pass an AWS profile name if you have multiple sets of credentials in your environment.
+
+### Example
+
+Below is an example of how to use FlightTracer:
+
+~~~python
+#!/usr/bin/env python
+"""
+fetch_example.py
+
+This example fetches real flight trace data, processes it (computing the continuous ping_time
+and inferring separate flight legs based on time gaps), saves the results locally
+with a filename that includes the ICAO code(s) and today's date, and optionally
+uploads the CSV and GeoJSON files to S3 using a specified AWS profile.
+It also shows how to generate a plot of the flight activity and save the plot as a PNG.
+"""
+
+import os
+from datetime import date, datetime
+from flight_tracer import FlightTracer
+import geopandas as gpd
+
+# Option 1: Use explicit AWS credentials (via environment variables or directly)
+aws_credentials = {
+    "aws_access_key_id": os.getenv("MY_AWS_ACCESS_KEY_ID"),
+    "aws_secret_access_key": os.getenv("MY_AWS_SECRET_ACCESS_KEY")
+}
+
+# Option 2: Alternatively, use an AWS profile from your environment
+aws_profile = os.getenv("MY_AWS_PROFILE")  # e.g., "my_profile_name"
+
+# Initialize flight_tracer with either explicit credentials or an AWS profile.
+# For example, to use explicit credentials:
+# tracer = flight_tracer(aircraft_ids=["a97753"], aws_creds=aws_credentials)
+# Or, to use an AWS profile:
+tracer = FlightTracer(aircraft_ids=["a97753"], aws_profile=aws_profile)
+
+# Define the date range for trace data
+start = date(2025, 1, 28)
+end = date(2025, 2, 1)
+
+# Fetch raw flight trace data from ADS-B Exchange
+print("Fetching raw flight trace data...")
+raw_df = tracer.get_traces(start, end)
+if raw_df.empty:
+    print("No valid data to process.")
+else:
+    print("Raw data sample:")
+    print(raw_df.head())
+
+    # Process trace data into a GeoDataFrame (computing continuous ping_time in UTC
+    # and detecting flight leg changes based on time gaps). A new 'flight_leg' column is
+    # created that combines call_sign, flight_date, and leg_id.
+    print("\nProcessing flight data into a GeoDataFrame...")
+    gdf = tracer.process_flight_data(raw_df)
+
+    # Optionally, retain ground points: 
+    # gdf = tracer.process_flight_data(raw_df, filter_ground=False)
+    
+    print("Processed GeoDataFrame sample:")
+    print(gdf.head())
+    
+    # Optionally, inspect the unique flight legs detected in the data.
+    print("\nUnique flight legs detected:")
+    print(gdf["flight_leg"].unique())
+
+    # Build dynamic filenames that include the ICAO code(s) and today's date
+    icao_str = "_".join(tracer.aircraft_ids)
+    date_str = datetime.today().strftime("%Y%m%d")
+    csv_filename = f"data/flight_traces_{icao_str}_{date_str}.csv"
+    geojson_filename = f"data/flight_traces_{icao_str}_{date_str}.geojson"
+
+    # Save the processed data locally as CSV and GeoJSON
+    gdf.to_csv(csv_filename, index=False)
+    gdf.to_file(geojson_filename, driver="GeoJSON")
+    print(f"\nSaved processed data locally as '{csv_filename}' and '{geojson_filename}'.")
+
+    # Export linestring geometry for each flight leg
+    linestring_geojson_filename = f"data/flight_traces_lines_{icao_str}_{date_str}.geojson"
+    tracer.export_linestring_geojson(gdf, linestring_geojson_filename)
+
+    # Optionally upload the processed files to S3
+    bucket_name = "your-bucket-name"  # replace with your bucket name
+    csv_object_name = f"flight_tracer/flight_traces_{icao_str}_{date_str}.csv"
+    geojson_object_name = f"flight_tracer/flight_traces_{icao_str}_{date_str}.geojson"
+    print("\nUploading files to S3 (if AWS credentials or profile are configured)...")
+    tracer.upload_to_s3(gdf, bucket_name, csv_object_name, geojson_object_name)
+    print("Upload process completed.")
+
+    # Plot the points with a basemap and optionally save the plot as a PNG
+    fig_filename = f"visuals/flight_map_{icao_str}_{date_str}.png"
+    tracer.plot_flights(gdf, geometry_type='points', figsize=(12,10), fig_filename=fig_filename)
+~~~
+
+## Configuration
+
+The package supports the following configurations:
+
+- **Aircraft IDs or metadata URL**: Provide either a list of ICAO codes or a metadata URL to extract aircraft information.  
+- **AWS credentials or profile**: Pass AWS credentials as a dictionary, specify an AWS profile, or set them as environment variables.  
+- **Date range**: Define the start and end dates to fetch trace data.
+
+## Notes
+
+- Ensure that your AWS credentials or profile are configured correctly if you wish to use the S3 upload feature.  
+- The package fetches data from ADS-B Exchange so the availability of data depends on the public API.  
+- Flight leg detection is based on a configurable time gap threshold (default is 15 minutes). Adjust as needed for your data.  
+- Plotting functionality includes an option to expand the plotted extent (via `pad_factor`) for broader context and to save the plot as a PNG.
+
+## Roadmap for Enhancements
+
+#### Enrich with external metadata:
+- Build tools to “hydrate” your flight data with additional aircraft metadata from external sources such as FAA, ICAO, or other databases (e.g., aircraft type, operator, age, etc.).
+
+#### Package distribution:
+- Finalize the code structure (including tests, documentation, and a setup script) and publish the package to PyPI for installation via pip.
+
+#### Enhanced documentation and examples:
+- Update the README with comprehensive, end-to-end examples for various scenarios (e.g., pulling all flights for a month of a particular aircraft, processing a list of aircraft from a metadata URL, etc.), including usage examples for linestring export, leg splitting, and metadata enrichment.
+
+#### Configurable thresholds and options:
+- Allow users to adjust parameters like the time-gap threshold for determining new flight legs, output formats, and which metadata fields to hydrate.
+
+#### Performance and error handling improvements:
+- Add caching or parallel processing options to improve performance when fetching data over a long date range or for multiple aircraft.
+- Improve error handling to gracefully skip problematic dates or flights while logging issues.
+
+## License
+
+This project is licensed under the **Creative Commons CC0 1.0 Universal (CC0 1.0) Public Domain Dedication**.  
+
+This means that to the extent possible under law, the creator has waived all copyright and related or neighboring rights to this work. 
+
+You can copy, modify, distribute, and perform the work, even for commercial purposes, all without asking permission.
+
+For more details, refer to the full [CC0 1.0 Universal License](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
+
+![CC0 Badge](https://licensebuttons.net/p/zero/1.0/88x31.png)

flight_tracer-0.1.0/flight_tracer/__init__.py

@@ -0,0 +1 @@
+from .core import FlightTracer

flight_tracer-0.1.0/flight_tracer/core.py

@@ -0,0 +1,303 @@
+# flight_tracer/core.py
+import requests
+import pandas as pd
+import geopandas as gpd
+import boto3
+import os
+from datetime import date, timedelta
+from io import BytesIO
+from shapely.geometry import LineString
+import matplotlib.pyplot as plt
+import contextily as ctx
+
+class FlightTracer:
+    # Default columns from the ADSB trace data (we’ll drop the extra ones)
+    DEFAULT_COLUMNS = [
+        "time", "lat", "lon", "altitude", "ground_speed", "heading",
+        "unknown1", "baro_rate", "details", "code", "alt_geom",
+        "unknown2", "unknown3", "unknown4",
+    ]
+    DROP_COLUMNS = ["unknown1", "code", "baro_rate", "unknown2", "unknown3", "unknown4"]
+
+    def __init__(self, aircraft_ids=None, meta_url=None, aws_creds=None, aws_profile=None):
+        """
+        Initialize with a list of aircraft_ids or a metadata URL.
+        Optionally pass aws_creds as a dict with keys:
+          'aws_access_key_id' and 'aws_secret_access_key'.
+        Alternatively, pass aws_profile to use a specific AWS CLI profile.
+        """
+        if meta_url:
+            meta_df = pd.read_json(meta_url)
+            # Clean up and extract ICAO codes from metadata
+            self.aircraft_ids = meta_df["icao"].str.strip().str.lower().tolist()
+            self.meta_df = meta_df
+        elif aircraft_ids:
+            self.aircraft_ids = [ac.strip().lower() for ac in aircraft_ids]
+            self.meta_df = None
+        else:
+            raise ValueError("Either aircraft_ids or meta_url must be provided")
+
+        # Set up S3 client using aws_profile if provided, else explicit credentials if provided
+        if aws_profile:
+            session = boto3.Session(profile_name=aws_profile)
+            self.s3_client = session.client('s3')
+        elif aws_creds:
+            self.s3_client = boto3.client(
+                's3',
+                aws_access_key_id=aws_creds.get('aws_access_key_id'),
+                aws_secret_access_key=aws_creds.get('aws_secret_access_key')
+            )
+        else:
+            self.s3_client = None
+
+    def generate_urls(self, start_date, end_date):
+        """Generate ADSBExchange URLs for each aircraft over a date range."""
+        base_url = "https://globe.adsbexchange.com/globe_history/"
+        delta = timedelta(days=1)
+        urls = []
+        for icao in self.aircraft_ids:
+            # Use last 2 chars to build the URL path
+            icao_suffix = icao[-2:]
+            current_date = start_date
+            while current_date <= end_date:
+                year = current_date.strftime("%Y")
+                month = current_date.strftime("%m")
+                day = current_date.strftime("%d")
+                url = f"{base_url}{year}/{month}/{day}/traces/{icao_suffix}/trace_full_{icao}.json"
+                urls.append((url, icao))
+                current_date += delta
+        return urls
+
+    def fetch_trace_data(self, url, icao):
+        """Fetch and return a trace DataFrame from a given URL."""
+        headers = {"Referer": f"https://globe.adsbexchange.com/?icao={icao}"}
+        response = requests.get(url, headers=headers)
+        if response.status_code == 200:
+            data = response.json()
+            if data and "trace" in data:
+                trace_df = pd.DataFrame(data["trace"], columns=self.DEFAULT_COLUMNS)
+                trace_df = trace_df.drop(columns=self.DROP_COLUMNS, errors='ignore')
+                # Add additional metadata
+                trace_df["nnumber"] = data["r"]
+                trace_df["model"] = data["t"]
+                trace_df["desc"] = data["desc"]
+                # Convert the initial timestamp to a datetime
+                trace_df["timestamp"] = pd.to_datetime(data["timestamp"], unit="s")
+                # Compute the actual ping time by adding the offset
+                trace_df["ping_time"] = trace_df["timestamp"] + pd.to_timedelta(trace_df["time"], unit="s")
+                trace_df["icao"] = icao  # Add the aircraft id to the DataFrame
+                return trace_df
+        return None
+
+
+    def get_traces(self, start_date, end_date):
+        """
+        Loop through generated URLs to fetch trace data.
+        Returns a concatenated DataFrame of all valid traces.
+        """
+        urls = self.generate_urls(start_date, end_date)
+        traces = []
+        for url, icao in urls:
+            trace_df = self.fetch_trace_data(url, icao)
+            if trace_df is not None and not trace_df.empty:
+                traces.append(trace_df)
+                # Print a friendly message using the first timestamp
+                ts = pd.to_datetime(trace_df["timestamp"].iloc[0]).strftime('%b %-d, %Y')
+                print(f"Yay! {icao} flew on {ts}.")
+            else:
+                print(f"No data for {icao} on {url}.")
+        if traces:
+            return pd.concat(traces).reset_index(drop=True).sort_values("timestamp")
+        else:
+            print("No valid trace data collected.")
+            return pd.DataFrame()
+
+    def process_flight_data(self, df, mapping_info=None, filter_ground=True):
+        """
+        Process the raw trace data:
+        - Compute point_time (UTC) and convert to US/Pacific.
+        - Detect flight leg changes by looking at time gaps.
+        - Normalize JSON details into columns.
+        - Optionally map a flight column to additional info (like owner).
+        - Create a combined flight_leg column.
+        - Optionally filter out ground-level data.
+        - Return a GeoDataFrame.
+
+        Parameters:
+        df (DataFrame): Raw flight trace data.
+        mapping_info (tuple or None): If provided, maps flight details to additional metadata.
+        filter_ground (bool): If True (default), removes rows where altitude is "ground".
+
+        Returns:
+        GeoDataFrame: Processed flight data with spatial points.
+        """
+        # First sort and compute the continuous ping time
+        df = df.sort_values(['timestamp', 'time'])
+        df["point_time"] = df["timestamp"] + pd.to_timedelta(df["time"], unit="s")
+        df["timestamp_pst"] = df["point_time"].dt.tz_localize("UTC").dt.tz_convert("US/Pacific")
+        df["point_time_pst_clean"] = df["timestamp_pst"].dt.strftime("%H:%M:%S")
+        df["flight_date_pst"] = df["timestamp_pst"].dt.strftime("%Y-%m-%d")
+        
+        # --- Begin leg detection ---
+        df = df.sort_values(['icao', 'point_time'])
+        df['time_diff'] = df.groupby(['icao', 'flight_date_pst'])['point_time'].diff()
+        threshold = pd.Timedelta(minutes=15)
+        df['new_leg'] = (df['time_diff'] > threshold).fillna(0).astype(int)
+        df['leg_id'] = df.groupby(['icao', 'flight_date_pst'])['new_leg'].cumsum() + 1
+        # --- End leg detection ---
+        
+        # Extract the call sign from the 'details' column and fill forward missing values
+        df["call_sign"] = pd.json_normalize(df['details'])['flight'].str.strip()
+        df["call_sign"] = df["call_sign"].ffill()
+        
+        # Create a combined flight_leg field: call_sign + "_" + flight_date_pst + "_leg" + leg_id
+        df["flight_leg"] = df["call_sign"] + "_" + df["flight_date_pst"] + "_leg" + df["leg_id"].astype(str)
+        
+        # Flatten the 'details' JSON column (drop alt_geom if present)
+        details_df = pd.json_normalize(df["details"]).drop(columns=["alt_geom"], errors='ignore')
+        df = df.join(details_df)
+        
+        # Optionally apply a mapping (e.g. flight -> owner) if mapping_info is provided
+        if mapping_info and "flight" in df.columns:
+            meta_df, key_col, value_col, target_col = mapping_info
+            mapping = meta_df.set_index(key_col)[value_col].to_dict()
+            df[target_col] = df["flight"].map(mapping)
+        
+        # Select a common set of columns, explicitly including point_time for later sorting.
+        cols = ["flight", "point_time", "flight_date_pst", "point_time_pst_clean", "altitude",
+                "ground_speed", "heading", "lat", "lon", "icao", "call_sign", "leg_id", "flight_leg"]
+        if mapping_info:
+            cols.append(target_col)
+
+        # Apply altitude filter based on user preference
+        if filter_ground:
+            df = df.query('altitude != "ground"').copy()
+        
+        # Create and return a GeoDataFrame with points from lon/lat
+        return gpd.GeoDataFrame(df[cols], geometry=gpd.points_from_xy(df.lon, df.lat))
+
+
+    def export_linestring_geojson(self, gdf, output_file):
+        """
+        Given a GeoDataFrame of flight trace points (which includes a 'flight_leg'
+        and a continuous 'point_time' column), group the data by flight_leg,
+        create a LineString for each leg, and export the result as a GeoJSON file.
+        
+        Parameters:
+        gdf (GeoDataFrame): The GeoDataFrame of flight points.
+        output_file (str): Path to the output GeoJSON file.
+        """
+        legs = []
+        # Group by the unique flight_leg identifier
+        for flight_leg, group in gdf.groupby("flight_leg"):
+            # Sort the group by point_time so the points are in order
+            group = group.sort_values("point_time")
+            points = list(group.geometry)
+            # If more than one point, create a LineString; otherwise, use the single point.
+            if len(points) > 1:
+                geometry = LineString(points)
+            else:
+                geometry = points[0]
+            # Capture representative attributes from the first row.
+            legs.append({
+                "flight_leg": flight_leg,
+                "icao": group["icao"].iloc[0],
+                "call_sign": group["call_sign"].iloc[0],
+                "flight_date_pst": group["flight_date_pst"].iloc[0],
+                "leg_id": group["leg_id"].iloc[0],
+                "geometry": geometry
+            })
+        
+        gdf_lines = gpd.GeoDataFrame(legs, crs=gdf.crs)
+        gdf_lines.to_file(output_file, driver="GeoJSON")
+        print(f"Linestring GeoJSON exported to {output_file}")
+
+
+
+    def plot_flights(self, gdf, geometry_type='points', figsize=(10,10), pad_factor=0.2, zoom=None, fig_filename=None):
+        """
+        Plot flight activity from a GeoDataFrame with a basemap.
+        
+        Parameters:
+        gdf (GeoDataFrame): The GeoDataFrame containing flight trace points or lines.
+        geometry_type (str): 'points' or 'lines' – determines what geometry to plot.
+        figsize (tuple): Figure size for the plot.
+        pad_factor (float): Fraction by which to expand the bounds for additional context.
+        zoom (int or None): Optional zoom level override for the basemap.
+        fig_filename (str or None): If provided, the plot will be saved to this PNG file.
+        
+        This method reprojects the GeoDataFrame to EPSG:3857, computes a padded extent, plots
+        the data with a basemap, and optionally saves the figure.
+        """
+        # Ensure the GeoDataFrame has a CRS; assume EPSG:4326 if not set.
+        if gdf.crs is None:
+            gdf = gdf.set_crs(epsg=4326)
+        # Reproject to Web Mercator for basemap compatibility.
+        gdf_plot = gdf.to_crs(epsg=3857)
+        
+        fig, ax = plt.subplots(figsize=figsize)
+        
+        # Plot based on the desired geometry type.
+        if geometry_type == 'points':
+            gdf_plot.plot(ax=ax, marker='o', color='#f18851', markersize=5, label='Flight points')
+        elif geometry_type == 'lines':
+            gdf_plot.plot(ax=ax, linewidth=2, color='#f18851', label='Flight path')
+        else:
+            raise ValueError("geometry_type must be either 'points' or 'lines'")
+        
+        # Get the total bounds: [xmin, ymin, xmax, ymax]
+        xmin, ymin, xmax, ymax = gdf_plot.total_bounds
+        # Calculate padding based on the pad_factor.
+        x_pad = (xmax - xmin) * pad_factor
+        y_pad = (ymax - ymin) * pad_factor
+        extent = [xmin - x_pad, ymin - y_pad, xmax + x_pad, ymax + y_pad]
+        
+        # Set the axis limits to the padded extent.
+        ax.set_xlim(extent[0], extent[2])
+        ax.set_ylim(extent[1], extent[3])
+        
+        # Add a basemap using CartoDB Positron.
+        if zoom is not None:
+            ctx.add_basemap(ax, source=ctx.providers.CartoDB.Positron, zoom=zoom, reset_extent=False)
+        else:
+            ctx.add_basemap(ax, source=ctx.providers.CartoDB.Positron, reset_extent=False)
+        
+        # Clean up the plot aesthetics.
+        ax.set_axis_off()
+        ax.legend()
+        plt.tight_layout()
+        plt.title("Flight sketch")
+        
+        # If a figure filename is provided, save the figure as a PNG.
+        if fig_filename:
+            # Create the directory if it doesn't exist.
+            os.makedirs(os.path.dirname(fig_filename), exist_ok=True)
+            plt.savefig(fig_filename, dpi=300, bbox_inches='tight')
+            print(f"Figure saved as {fig_filename}")
+        
+        plt.show()
+
+
+    def upload_to_s3(self, gdf, bucket_name, csv_object_name, geojson_object_name):
+        """Upload the GeoDataFrame as both CSV and GeoJSON to S3 (if configured)."""
+        if not self.s3_client:
+            print("S3 client not configured; skipping upload.")
+            return
+        
+        # Save CSV in memory and upload
+        csv_buffer = BytesIO()
+        gdf.to_csv(csv_buffer, index=False)
+        csv_buffer.seek(0)
+        self.s3_client.put_object(Bucket=bucket_name, Key=csv_object_name, Body=csv_buffer.getvalue())
+        print(f"CSV uploaded to s3://{bucket_name}/{csv_object_name}")
+        
+        # Remove non-serializable columns (e.g., 'point_time') before exporting to GeoJSON.
+        # Alternatively, you could convert it to a string using .astype(str)
+        gdf_json = gdf.drop(columns=["point_time"], errors="ignore")
+        geojson_str = gdf_json.to_json()
+        self.s3_client.put_object(
+            Bucket=bucket_name, 
+            Key=geojson_object_name, 
+            Body=geojson_str.encode('utf-8')
+        )
+        print(f"GeoJSON uploaded to s3://{bucket_name}/{geojson_object_name}")

flight_tracer-0.1.0/flight_tracer.egg-info/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.2
+Name: flight_tracer
+Version: 0.1.0
+Summary: A package to fetch, process, store and plot aircraft trace data from ADS-B Exchange.
+Home-page: https://github.com/stiles/flight_tracer
+Author: Matt Stiles
+Author-email: mattstiles@gmail.com
+License: CC0-1.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: pandas
+Requires-Dist: geopandas
+Requires-Dist: boto3
+Requires-Dist: matplotlib
+Requires-Dist: contextily
+Requires-Dist: shapely
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Tracking ADS-B Exchange flights
+
+FlightTracer is a Python package to fetch and process aircraft trace data from ADS-B Exchange. It supports a single ICAO code or a list of codes — and it has an option to upload processed data as CSV and GeoJSON to Amazon S3. FlightTracer also detects separate flight legs based on significant time gaps and creates a combined flight leg identifier (call_sign, date, leg) for easier differentiation in GIS tools. In addition, the package also provides plotting capabilities with a basemap and an option to save the plot as a PNG.
+
+This project is in the early stages of development. Contributions and feedback welcome. 
+
+## Installation
+
+1. Clone the repository or download the source code  
+2. Install the required dependencies using pip
+
+~~~bash
+pip install requests pandas geopandas boto3 contextily matplotlib
+~~~
+
+## Usage
+
+FlightTracer can be used with either a list of aircraft IDs or a metadata URL that contains aircraft information. You can also configure AWS credentials if you wish to upload the output to S3. In addition, you can pass an AWS profile name if you have multiple sets of credentials in your environment.
+
+### Example
+
+Below is an example of how to use FlightTracer:
+
+~~~python
+#!/usr/bin/env python
+"""
+fetch_example.py
+
+This example fetches real flight trace data, processes it (computing the continuous ping_time
+and inferring separate flight legs based on time gaps), saves the results locally
+with a filename that includes the ICAO code(s) and today's date, and optionally
+uploads the CSV and GeoJSON files to S3 using a specified AWS profile.
+It also shows how to generate a plot of the flight activity and save the plot as a PNG.
+"""
+
+import os
+from datetime import date, datetime
+from flight_tracer import FlightTracer
+import geopandas as gpd
+
+# Option 1: Use explicit AWS credentials (via environment variables or directly)
+aws_credentials = {
+    "aws_access_key_id": os.getenv("MY_AWS_ACCESS_KEY_ID"),
+    "aws_secret_access_key": os.getenv("MY_AWS_SECRET_ACCESS_KEY")
+}
+
+# Option 2: Alternatively, use an AWS profile from your environment
+aws_profile = os.getenv("MY_AWS_PROFILE")  # e.g., "my_profile_name"
+
+# Initialize flight_tracer with either explicit credentials or an AWS profile.
+# For example, to use explicit credentials:
+# tracer = flight_tracer(aircraft_ids=["a97753"], aws_creds=aws_credentials)
+# Or, to use an AWS profile:
+tracer = FlightTracer(aircraft_ids=["a97753"], aws_profile=aws_profile)
+
+# Define the date range for trace data
+start = date(2025, 1, 28)
+end = date(2025, 2, 1)
+
+# Fetch raw flight trace data from ADS-B Exchange
+print("Fetching raw flight trace data...")
+raw_df = tracer.get_traces(start, end)
+if raw_df.empty:
+    print("No valid data to process.")
+else:
+    print("Raw data sample:")
+    print(raw_df.head())
+
+    # Process trace data into a GeoDataFrame (computing continuous ping_time in UTC
+    # and detecting flight leg changes based on time gaps). A new 'flight_leg' column is
+    # created that combines call_sign, flight_date, and leg_id.
+    print("\nProcessing flight data into a GeoDataFrame...")
+    gdf = tracer.process_flight_data(raw_df)
+
+    # Optionally, retain ground points: 
+    # gdf = tracer.process_flight_data(raw_df, filter_ground=False)
+    
+    print("Processed GeoDataFrame sample:")
+    print(gdf.head())
+    
+    # Optionally, inspect the unique flight legs detected in the data.
+    print("\nUnique flight legs detected:")
+    print(gdf["flight_leg"].unique())
+
+    # Build dynamic filenames that include the ICAO code(s) and today's date
+    icao_str = "_".join(tracer.aircraft_ids)
+    date_str = datetime.today().strftime("%Y%m%d")
+    csv_filename = f"data/flight_traces_{icao_str}_{date_str}.csv"
+    geojson_filename = f"data/flight_traces_{icao_str}_{date_str}.geojson"
+
+    # Save the processed data locally as CSV and GeoJSON
+    gdf.to_csv(csv_filename, index=False)
+    gdf.to_file(geojson_filename, driver="GeoJSON")
+    print(f"\nSaved processed data locally as '{csv_filename}' and '{geojson_filename}'.")
+
+    # Export linestring geometry for each flight leg
+    linestring_geojson_filename = f"data/flight_traces_lines_{icao_str}_{date_str}.geojson"
+    tracer.export_linestring_geojson(gdf, linestring_geojson_filename)
+
+    # Optionally upload the processed files to S3
+    bucket_name = "your-bucket-name"  # replace with your bucket name
+    csv_object_name = f"flight_tracer/flight_traces_{icao_str}_{date_str}.csv"
+    geojson_object_name = f"flight_tracer/flight_traces_{icao_str}_{date_str}.geojson"
+    print("\nUploading files to S3 (if AWS credentials or profile are configured)...")
+    tracer.upload_to_s3(gdf, bucket_name, csv_object_name, geojson_object_name)
+    print("Upload process completed.")
+
+    # Plot the points with a basemap and optionally save the plot as a PNG
+    fig_filename = f"visuals/flight_map_{icao_str}_{date_str}.png"
+    tracer.plot_flights(gdf, geometry_type='points', figsize=(12,10), fig_filename=fig_filename)
+~~~
+
+## Configuration
+
+The package supports the following configurations:
+
+- **Aircraft IDs or metadata URL**: Provide either a list of ICAO codes or a metadata URL to extract aircraft information.  
+- **AWS credentials or profile**: Pass AWS credentials as a dictionary, specify an AWS profile, or set them as environment variables.  
+- **Date range**: Define the start and end dates to fetch trace data.
+
+## Notes
+
+- Ensure that your AWS credentials or profile are configured correctly if you wish to use the S3 upload feature.  
+- The package fetches data from ADS-B Exchange so the availability of data depends on the public API.  
+- Flight leg detection is based on a configurable time gap threshold (default is 15 minutes). Adjust as needed for your data.  
+- Plotting functionality includes an option to expand the plotted extent (via `pad_factor`) for broader context and to save the plot as a PNG.
+
+## Roadmap for Enhancements
+
+#### Enrich with external metadata:
+- Build tools to “hydrate” your flight data with additional aircraft metadata from external sources such as FAA, ICAO, or other databases (e.g., aircraft type, operator, age, etc.).
+
+#### Package distribution:
+- Finalize the code structure (including tests, documentation, and a setup script) and publish the package to PyPI for installation via pip.
+
+#### Enhanced documentation and examples:
+- Update the README with comprehensive, end-to-end examples for various scenarios (e.g., pulling all flights for a month of a particular aircraft, processing a list of aircraft from a metadata URL, etc.), including usage examples for linestring export, leg splitting, and metadata enrichment.
+
+#### Configurable thresholds and options:
+- Allow users to adjust parameters like the time-gap threshold for determining new flight legs, output formats, and which metadata fields to hydrate.
+
+#### Performance and error handling improvements:
+- Add caching or parallel processing options to improve performance when fetching data over a long date range or for multiple aircraft.
+- Improve error handling to gracefully skip problematic dates or flights while logging issues.
+
+## License
+
+This project is licensed under the **Creative Commons CC0 1.0 Universal (CC0 1.0) Public Domain Dedication**.  
+
+This means that to the extent possible under law, the creator has waived all copyright and related or neighboring rights to this work. 
+
+You can copy, modify, distribute, and perform the work, even for commercial purposes, all without asking permission.
+
+For more details, refer to the full [CC0 1.0 Universal License](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
+
+![CC0 Badge](https://licensebuttons.net/p/zero/1.0/88x31.png)

flight_tracer-0.1.0/flight_tracer.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+setup.cfg
+setup.py
+flight_tracer/__init__.py
+flight_tracer/core.py
+flight_tracer.egg-info/PKG-INFO
+flight_tracer.egg-info/SOURCES.txt
+flight_tracer.egg-info/dependency_links.txt
+flight_tracer.egg-info/requires.txt
+flight_tracer.egg-info/top_level.txt
+tests/__init__.py
+tests/test_core.py

flight_tracer-0.1.0/flight_tracer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flight_tracer-0.1.0/flight_tracer.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests
+pandas
+geopandas
+boto3
+matplotlib
+contextily
+shapely

flight_tracer-0.1.0/flight_tracer.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+flight_tracer
+tests

flight_tracer-0.1.0/setup.cfg

@@ -0,0 +1,32 @@
+[metadata]
+name = flight_tracer
+version = 0.1.0
+description = A package to fetch, process, store and plot aircraft trace data from ADS-B Exchange.
+author = Matt Stiles
+author_email = mattstiles@gmail.com
+license = CC0-1.0
+license_files = LICENSE  # This is OK
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/stiles/flight_tracer
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+	Operating System :: OS Independent
+
+[options]
+packages = find:
+install_requires = 
+	requests
+	pandas
+	geopandas
+	boto3
+	matplotlib
+	contextily
+	shapely
+python_requires = >=3.7
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

flight_tracer-0.1.0/setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="flight_tracer",
+    version="0.1.0",
+    author="Matt Stiles",
+    author_email="mattstiles@gmail.com",
+    description="A package to fetch, process, store and plot aircraft trace data from ADS-B Exchange.",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/stiles/flight_tracer",
+    packages=find_packages(),
+    install_requires=[
+        "requests",
+        "pandas",
+        "geopandas",
+        "boto3",
+        "matplotlib",
+        "contextily",
+        "shapely"
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
+        "Operating System :: OS Independent",
+    ],
+    license="CC0-1.0",
+    python_requires='>=3.7',
+)

flight_tracer-0.1.0/tests/test_core.py

@@ -0,0 +1,25 @@
+import unittest
+from datetime import date
+from flight_tracer import FlightTracer
+
+class TestFlightTracer(unittest.TestCase):
+    def test_generate_urls_single_day(self):
+        # Create a FlightTracer instance with a dummy ICAO list
+        tracer = FlightTracer(aircraft_ids=["0d086e"])
+        # Using a single day: Jan 1, 2025 to Jan 1, 2025
+        urls = tracer.generate_urls(date(2025, 1, 1), date(2025, 1, 1))
+        # Expect 1 URL for a single day
+        self.assertEqual(len(urls), 1)
+        # Verify that the URL contains the correct date parts and ICAO code
+        expected_url = "https://globe.adsbexchange.com/globe_history/2025/01/01/traces/6e/trace_full_0d086e.json"
+        self.assertEqual(urls[0][0], expected_url)
+    
+    def test_generate_urls_multiple_days(self):
+        tracer = FlightTracer(aircraft_ids=["0d086e"])
+        # Using two days: Jan 1, 2025 to Jan 2, 2025
+        urls = tracer.generate_urls(date(2025, 1, 1), date(2025, 1, 2))
+        # Expect 2 URLs (one for each day)
+        self.assertEqual(len(urls), 2)
+
+if __name__ == '__main__':
+    unittest.main()