### Setup Development Environment

Source: https://github.com/flightradar24/fr24api-sdk-python/blob/main/CONTRIBUTING.md

Commands to create a virtual environment, activate it, and install the project with development dependencies. This ensures a clean workspace for local development.

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
```

--------------------------------

### Install Flightradar24 Python SDK

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Instructions for installing the fr24sdk library using pip or uv.

```bash
pip install fr24sdk
```

```bash
uv pip install fr24sdk
```

--------------------------------

### Install fr24sdk using pip or uv

Source: https://github.com/flightradar24/fr24api-sdk-python/blob/main/README.md

Instructions for installing the fr24sdk package using either pip or uv package managers. Ensure you have Python installed.

```bash
uv pip install fr24sdk
```

```bash
pip install fr24sdk
```

--------------------------------

### Get API Usage

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieve API usage statistics for your account over different time periods using the `get` method.

```APIDOC
## Get API Usage

### Description
Retrieve API usage statistics for your account over different time periods.

### Method
GET

### Endpoint
`/usage` (Conceptual - SDK handles this)

### Parameters
#### Query Parameters
- **period** (str) - Optional - The time period for usage statistics. Available options: `"24h"` (default), `"7d"`, `"30d"`, `"1y"`.

### Request Example
```python
from fr24sdk import Client

with Client() as client:
    # Get usage for last 24 hours (default)
    usage = client.usage.get()

    # Get usage for last 7 days
    usage_7d = client.usage.get(period="7d")
```

### Response
#### Success Response (200)
- **data** (list[UsageData]) - A list of usage data objects for each endpoint.
  - **endpoint** (str) - The API endpoint.
  - **request_count** (int) - The number of requests made to the endpoint.
  - **credits** (float) - The number of credits consumed by requests to the endpoint.

#### Response Example
```json
{
  "data": [
    {
      "endpoint": "/flights/live",
      "request_count": 150,
      "credits": 0.3
    },
    {
      "endpoint": "/airports/lookup",
      "request_count": 50,
      "credits": 0.1
    }
  ]
}
```
```

--------------------------------

### Get Live Flight Positions (Light)

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieve real-time lightweight flight position data including coordinates, altitude, speed, and heading. Requires at least one filter parameter.

```APIDOC
## Get Live Flight Positions (Light)

### Description
Retrieve real-time lightweight flight position data including coordinates, altitude, speed, and heading. Requires at least one filter parameter.

### Method
GET

### Endpoint
/live/flightPositions/get_light

### Parameters
#### Query Parameters
- **flights** (list[str]) - Optional - Filter by flight numbers.
- **callsigns** (list[str]) - Optional - Filter by flight callsigns.
- **registrations** (list[str]) - Optional - Filter by aircraft registrations.
- **bounds** (str or Boundary object) - Optional - Filter by geographic boundary (e.g., "north,south,west,east").
- **altitude_ranges** (list[str or AltitudeRange object]) - Optional - Filter by altitude ranges (e.g., "min_altitude-max_altitude").
- **operating_as** (list[str]) - Optional - Filter by airline IATA codes.
- **limit** (int) - Optional - Maximum number of results to return.

### Request Example
```python
from fr24sdk import Client
from fr24sdk.models.geographic import Boundary, AltitudeRange

with Client() as client:
    # Get live positions by flight number
    response = client.live.flight_positions.get_light(flights=["SK2752"])
    for flight in response.data:
        print(f"Flight ID: {flight.fr24_id}")
        print(f"Position: {flight.lat}, {flight.lon}")
        print(f"Altitude: {flight.alt} ft, Speed: {flight.gspeed} kts")
        print(f"Track: {flight.track}°, Vertical speed: {flight.vspeed} ft/min")
        print(f"Squawk: {flight.squawk}, Source: {flight.source}")

    # Get flights within geographic bounds using Boundary object
    bounds = Boundary(north=55.6, south=55.5, west=12.5, east=12.6)
    response = client.live.flight_positions.get_light(bounds=bounds)
    print(f"Found {len(response.data)} flights in the area")

    # Get flights by callsign
    response = client.live.flight_positions.get_light(callsigns=["SAS2752", "DLH123"])

    # Get flights by registration
    response = client.live.flight_positions.get_light(registrations=["SE-ROA", "D-AIBL"])

    # Filter by altitude range
    alt_range = AltitudeRange(min_altitude=30000, max_altitude=40000)
    response = client.live.flight_positions.get_light(
        bounds="60,50,0,20",  # String format also supported
        altitude_ranges=[alt_range, "10000-20000"]
    )

    # Filter by airline
    response = client.live.flight_positions.get_light(
        operating_as=["SAS", "DLH"],
        limit=100
    )
```

### Response
#### Success Response (200)
- **data** (list[FlightPositionLight]) - List of flight position data.
  - **fr24_id** (str) - FlightRadar24 unique identifier.
  - **lat** (float) - Latitude.
  - **lon** (float) - Longitude.
  - **alt** (int) - Altitude in feet.
  - **gspeed** (float) - Ground speed in knots.
  - **track** (int) - Heading in degrees.
  - **vspeed** (float) - Vertical speed in feet per minute.
  - **squawk** (str) - Squawk code.
  - **source** (str) - Data source.

#### Response Example
```json
{
  "data": [
    {
      "fr24_id": "123456",
      "lat": 40.7128,
      "lon": -74.0060,
      "alt": 35000,
      "gspeed": 450.5,
      "track": 270,
      "vspeed": 150,
      "squawk": "1234",
      "source": "ADS-B"
    }
  ]
}
```
```

--------------------------------

### GET /live/flight_positions/get_light

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves real-time flight position data filtered by geographic boundaries and altitude ranges.

```APIDOC
## GET /live/flight_positions/get_light

### Description
Fetches a lightweight list of flight positions within a specified bounding box and altitude range.

### Method
GET

### Endpoint
client.live.flight_positions.get_light

### Parameters
#### Query Parameters
- **bounds** (Boundary object or string) - Required - Geographic area defined as 'north,south,west,east' or a Boundary instance.
- **altitude_ranges** (List[AltitudeRange] or List[str]) - Optional - List of altitude ranges defined as 'min-max' or AltitudeRange instances.

### Request Example
{
  "bounds": "55.6,55.5,12.5,12.6",
  "altitude_ranges": ["30000-40000"]
}

### Response
#### Success Response (200)
- **data** (List) - A list of flight position objects containing coordinates, callsigns, and altitude information.

#### Response Example
{
  "flights": [
    {"id": "12345", "lat": 55.55, "lon": 12.55, "alt": 35000}
  ]
}
```

--------------------------------

### Get Flight Summary (Light) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves lightweight flight summary data, which can be filtered by flight IDs, time ranges, callsigns, or airports. Requires the 'fr24sdk' library. Either flight_ids or a time range (flight_datetime_from and flight_datetime_to) must be provided.

```python
from datetime import datetime
from fr24sdk import Client

with Client() as client:
    # Get flight summaries by time range and flight number
    response = client.flight_summary.get_light(
        flights=["KL1316"],
        flight_datetime_from=datetime(2025, 5, 13, 12, 0, 0),
        flight_datetime_to=datetime(2025, 5, 14, 17, 10, 0)
    )

    for flight in response.data:
        print(f"FR24 ID: {flight.fr24_id}")
        print(f"Flight: {flight.flight}, Callsign: {flight.callsign}")
        print(f"Aircraft: {flight.type}, Reg: {flight.reg}")
        print(f"Route: {flight.orig_icao} -> {flight.dest_icao}")
        print(f"Takeoff: {flight.datetime_takeoff}")
        print(f"Landed: {flight.datetime_landed}")
        print(f"Flight ended: {flight.flight_ended}")

    # Get by flight IDs directly
    response = client.flight_summary.get_light(
        flight_ids=["3a55c027", "3a55c028"]
    )

    # Get by callsigns with time range
    response = client.flight_summary.get_light(
        callsigns=["SAS2752", "DLH456"],
        flight_datetime_from=datetime(2025, 5, 1, 0, 0, 0),
        flight_datetime_to=datetime(2025, 5, 31, 23, 59, 59),
        limit=100
    )

    # Filter by airports
    response = client.flight_summary.get_light(
        airports=["arr:EGLL"],  # Arrivals at Heathrow
        flight_datetime_from=datetime(2025, 5, 14, 0, 0, 0),
        flight_datetime_to=datetime(2025, 5, 14, 23, 59, 59),
        sort="-datetime_takeoff",  # Sort descending by takeoff time
        limit=50
    )
```

--------------------------------

### Get Live Flight Positions (Light) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves real-time lightweight flight position data. Requires at least one filter parameter such as flight number, geographic bounds, callsign, registration, altitude range, or airline. Returns coordinates, altitude, speed, and heading.

```python
from fr24sdk import Client
from fr24sdk.models.geographic import Boundary, AltitudeRange

with Client() as client:
    # Get live positions by flight number
    response = client.live.flight_positions.get_light(flights=["SK2752"])
    for flight in response.data:
        print(f"Flight ID: {flight.fr24_id}")
        print(f"Position: {flight.lat}, {flight.lon}")
        print(f"Altitude: {flight.alt} ft, Speed: {flight.gspeed} kts")
        print(f"Track: {flight.track}°, Vertical speed: {flight.vspeed} ft/min")
        print(f"Squawk: {flight.squawk}, Source: {flight.source}")

    # Get flights within geographic bounds using Boundary object
    bounds = Boundary(north=55.6, south=55.5, west=12.5, east=12.6)
    response = client.live.flight_positions.get_light(bounds=bounds)
    print(f"Found {len(response.data)} flights in the area")

    # Get flights by callsign
    response = client.live.flight_positions.get_light(callsigns=["SAS2752", "DLH123"])

    # Get flights by registration
    response = client.live.flight_positions.get_light(registrations=["SE-ROA", "D-AIBL"])

    # Filter by altitude range
    alt_range = AltitudeRange(min_altitude=30000, max_altitude=40000)
    response = client.live.flight_positions.get_light(
        bounds="60,50,0,20",  # String format also supported
        altitude_ranges=[alt_range, "10000-20000"]  # Mix objects and strings
    )

    # Filter by airline
    response = client.live.flight_positions.get_light(
        operating_as=["SAS", "DLH"],
        limit=100
    )
```

--------------------------------

### Get Historic Flight Events (Full)

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieve comprehensive historical flight events with additional flight and aircraft details using the `get_full` method.

```APIDOC
## Get Historic Flight Events (Full)

### Description
Retrieve comprehensive historical flight events with additional flight and aircraft details.

### Method
GET

### Endpoint
`/historic/flight_events/full` (Conceptual - SDK handles this)

### Parameters
#### Query Parameters
- **flight_ids** (list[str]) - Required - A list of flight IDs to retrieve events for.
- **event_types** (list[str]) - Required - A list of event types to filter by (e.g., `["all"]`).

### Request Example
```python
from fr24sdk import Client

with Client() as client:
    response = client.historic.flight_events.get_full(
        flight_ids=["3a55c027"],
        event_types=["all"]
    )
```

### Response
#### Success Response (200)
- **data** (list[FlightEventData]) - A list of flight event data objects.
  - **fr24_id** (str) - The Flightradar24 flight ID.
  - **callsign** (str) - The flight callsign.
  - **hex** (str) - The aircraft's hexadecimal ICAO address.
  - **operating_as** (str) - The airline operating the flight.
  - **painted_as** (str) - The airline whose livery is painted on the aircraft.
  - **orig_iata** (str) - Origin airport IATA code.
  - **orig_icao** (str) - Origin airport ICAO code.
  - **dest_iata** (str) - Destination airport IATA code.
  - **dest_icao** (str) - Destination airport ICAO code.
  - **events** (list[Event]) - A list of events associated with the flight.
    - **type** (str) - The type of event (e.g., 'departure', 'arrival').
    - **timestamp** (str) - The timestamp of the event.
    - **lat** (float) - Latitude of the event location (if applicable).
    - **lon** (float) - Longitude of the event location (if applicable).
    - **alt** (float) - Altitude of the event location (if applicable).
    - **gspeed** (float) - Ground speed at the event time (if applicable).
    - **details** (object) - Event-specific details (e.g., gate, runway).

#### Response Example
```json
{
  "data": [
    {
      "fr24_id": "3a55c027",
      "callsign": "BAW286",
      "hex": "401083",
      "operating_as": "British Airways",
      "painted_as": "British Airways",
      "orig_iata": "LHR",
      "orig_icao": "EGLL",
      "dest_iata": "JFK",
      "dest_icao": "KJFK",
      "events": [
        {
          "type": "departure",
          "timestamp": "2023-10-27T10:30:00Z",
          "lat": 51.4700,
          "lon": -0.4543,
          "alt": 1500,
          "gspeed": 250,
          "details": {
            "takeoff_runway": "09L"
          }
        },
        {
          "type": "arrival",
          "timestamp": "2023-10-27T13:45:00Z",
          "lat": 40.6413,
          "lon": -73.7781,
          "alt": 50,
          "gspeed": 180,
          "details": {
            "landed_runway": "22R"
          }
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Get Live Flight Positions (Full)

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieve comprehensive real-time flight position data with additional details like origin, destination, aircraft type, and airline information.

```APIDOC
## Get Live Flight Positions (Full)

### Description
Retrieve comprehensive real-time flight position data with additional details like origin, destination, aircraft type, and airline information.

### Method
GET

### Endpoint
/live/flightPositions/get_full

### Parameters
#### Query Parameters
- **bounds** (str or Boundary object) - Optional - Filter by geographic boundary (e.g., "north,south,west,east").
- **airports** (list[str]) - Optional - Filter by origin or destination airports (e.g., "dep:JFK", "arr:LAX").
- **routes** (list[str]) - Optional - Filter by flight routes (e.g., "JFK-LAX").
- **squawks** (list[str]) - Optional - Filter by squawk codes.
- **limit** (int) - Optional - Maximum number of results to return.

### Request Example
```python
from fr24sdk import Client
from fr24sdk.models.geographic import Boundary

with Client() as client:
    # Get full flight details within bounds
    response = client.live.flight_positions.get_full(
        bounds=Boundary(north=60.0, south=50.0, west=5.0, east=20.0),
        limit=50
    )

    for flight in response.data:
        print(f"Flight: {flight.flight} ({flight.callsign})")
        print(f"  FR24 ID: {flight.fr24_id}")
        print(f"  Aircraft: {flight.type}, Reg: {flight.reg}")
        print(f"  Airline: {flight.operating_as} (painted as {flight.painted_as})")
        print(f"  Route: {flight.orig_iata}/{flight.orig_icao} -> {flight.dest_iata}/{flight.dest_icao}")
        print(f"  Position: {flight.lat}, {flight.lon}")
        print(f"  Altitude: {flight.alt} ft, Speed: {flight.gspeed} kts")
        print(f"  ETA: {flight.eta}")

    # Filter by airports (origin or destination)
    response = client.live.flight_positions.get_full(
        airports=["arr:EGLL", "dep:KJFK"],  # Arrivals at Heathrow, departures from JFK
        limit=100
    )

    # Filter by route
    response = client.live.flight_positions.get_full(
        routes=["EGLL-KJFK", "KJFK-EGLL"]
    )

    # Filter by squawk codes
    response = client.live.flight_positions.get_full(
        squawks=["7700", "7600"],  # Emergency codes
        limit=50
    )
```

### Response
#### Success Response (200)
- **data** (list[FlightPositionFull]) - List of detailed flight position data.
  - **flight** (str) - Flight number.
  - **callsign** (str) - Flight callsign.
  - **fr24_id** (str) - FlightRadar24 unique identifier.
  - **type** (str) - Aircraft type.
  - **reg** (str) - Aircraft registration.
  - **operating_as** (str) - Airline operating the flight (IATA code).
  - **painted_as** (str) - Airline painted on the aircraft (IATA code).
  - **orig_iata** (str) - Origin airport IATA code.
  - **orig_icao** (str) - Origin airport ICAO code.
  - **dest_iata** (str) - Destination airport IATA code.
  - **dest_icao** (str) - Destination airport ICAO code.
  - **lat** (float) - Latitude.
  - **lon** (float) - Longitude.
  - **alt** (int) - Altitude in feet.
  - **gspeed** (float) - Ground speed in knots.
  - **eta** (str) - Estimated time of arrival.

#### Response Example
```json
{
  "data": [
    {
      "flight": "BA286",
      "callsign": "BAW123",
      "fr24_id": "789012",
      "type": "B777",
      "reg": "G-XXXX",
      "operating_as": "BA",
      "painted_as": "BA",
      "orig_iata": "LHR",
      "orig_icao": "EGLL",
      "dest_iata": "JFK",
      "dest_icao": "KJFK",
      "lat": 40.7128,
      "lon": -74.0060,
      "alt": 36000,
      "gspeed": 480.0,
      "eta": "2023-10-27T14:30:00Z"
    }
  ]
}
```
```

--------------------------------

### Get API Usage - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves API usage statistics for your account over different time periods using the fr24sdk. It allows fetching usage for the last 24 hours (default), 7 days, 30 days, or the last year.

```python
from fr24sdk import Client

with Client() as client:
    # Get usage for last 24 hours (default)
    usage = client.usage.get()

    print("API Usage (last 24 hours):")
    for endpoint_usage in usage.data:
        print(f"  {endpoint_usage.endpoint}:")
        print(f"    Requests: {endpoint_usage.request_count}")
        print(f"    Credits: {endpoint_usage.credits}")

    # Get usage for different periods
    usage_7d = client.usage.get(period="7d")    # Last 7 days
    usage_30d = client.usage.get(period="30d")  # Last 30 days
    usage_1y = client.usage.get(period="1y")    # Last year

    # Available periods: "24h", "7d", "30d", "1y"
```

--------------------------------

### Get Airline Information

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieve basic airline information by ICAO code. Returns airline name, ICAO code, and optional IATA code.

```APIDOC
## Get Airline Information

Retrieve basic airline information by ICAO code. Returns airline name, ICAO code, and optional IATA code.

```python
from fr24sdk import Client

with Client() as client:
    # Get airline info by ICAO code
    airline = client.airlines.get_light(icao="SAS")
    print(f"Name: {airline.name}")  # Output: Scandinavian Airlines
    print(f"ICAO: {airline.icao}")  # Output: SAS
    print(f"IATA: {airline.iata}")  # Output: SK

    # Get Lufthansa
    airline = client.airlines.get_light(icao="DLH")
    print(f"Name: {airline.name}")  # Output: Lufthansa
```
```

--------------------------------

### Get Airline Information - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves basic airline information, including name, ICAO code, and optional IATA code, using the airline's ICAO code.

```python
from fr24sdk import Client

with Client() as client:
    # Get airline info by ICAO code
    airline = client.airlines.get_light(icao="SAS")
    print(f"Name: {airline.name}")  # Output: Scandinavian Airlines
    print(f"ICAO: {airline.icao}")  # Output: SAS
    print(f"IATA: {airline.iata}")  # Output: SK

    # Get Lufthansa
    airline = client.airlines.get_light(icao="DLH")
    print(f"Name: {airline.name}")  # Output: Lufthansa
```

--------------------------------

### Get Live Flight Positions (Full) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves comprehensive real-time flight position data with additional details. Filters can be applied using geographic bounds, airports (origin/destination), routes, or squawk codes. Includes origin, destination, aircraft type, and airline information.

```python
from fr24sdk import Client
from fr24sdk.models.geographic import Boundary

with Client() as client:
    # Get full flight details within bounds
    response = client.live.flight_positions.get_full(
        bounds=Boundary(north=60.0, south=50.0, west=5.0, east=20.0),
        limit=50
    )

    for flight in response.data:
        print(f"Flight: {flight.flight} ({flight.callsign})")
        print(f"  FR24 ID: {flight.fr24_id}")
        print(f"  Aircraft: {flight.type}, Reg: {flight.reg}")
        print(f"  Airline: {flight.operating_as} (painted as {flight.painted_as})")
        print(f"  Route: {flight.orig_iata}/{flight.orig_icao} -> {flight.dest_iata}/{flight.dest_icao}")
        print(f"  Position: {flight.lat}, {flight.lon}")
        print(f"  Altitude: {flight.alt} ft, Speed: {flight.gspeed} kts")
        print(f"  ETA: {flight.eta}")

    # Filter by airports (origin or destination)
    response = client.live.flight_positions.get_full(
        airports=["arr:EGLL", "dep:KJFK"],  # Arrivals at Heathrow, departures from JFK
        limit=100
    )

    # Filter by route
    response = client.live.flight_positions.get_full(
        routes=["EGLL-KJFK", "KJFK-EGLL"]
    )

    # Filter by squawk codes
    response = client.live.flight_positions.get_full(
        squawks=["7700", "7600"],  # Emergency codes
        limit=50
    )
```

--------------------------------

### Get Airport Information (Full)

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieve detailed airport information including coordinates, timezone, country details, city, and runway information.

```APIDOC
## Get Airport Information (Full)

Retrieve detailed airport information including coordinates, timezone, country details, city, and runway information.

```python
from fr24sdk import Client

with Client() as client:
    # Get full airport details
    airport = client.airports.get_full(code="WAW")

    print(f"Name: {airport.name}")  # Output: Warsaw Chopin Airport
    print(f"ICAO: {airport.icao}")  # Output: EPWA
    print(f"IATA: {airport.iata}")  # Output: WAW
    print(f"City: {airport.city}")  # Output: Warsaw
    print(f"Country: {airport.country.name} ({airport.country.code})")  # Output: Poland (PL)
    print(f"Coordinates: {airport.lat}, {airport.lon}")  # Output: 52.1657, 20.9671
    print(f"Elevation: {airport.elevation} ft")
    print(f"Timezone: {airport.timezone.name} (UTC{airport.timezone.offset:+d})")

    # Access runway information
    if airport.runways:
        for runway in airport.runways:
            print(f"Runway {runway.designator}: {runway.length}m x {runway.width}m")
            print(f"  Surface: {runway.surface.description}")
            print(f"  Heading: {runway.heading}°")
```
```

--------------------------------

### Fetch Airport Details using fr24sdk

Source: https://github.com/flightradar24/fr24api-sdk-python/blob/main/README.md

Example of fetching detailed information for a specific airport (e.g., WAW) using the Flightradar24 Python SDK. It demonstrates accessing attributes like name, ICAO, city, country, latitude, and longitude from the response object.

```python
from fr24sdk.client import Client
from fr24sdk.exceptions import ApiError

client = Client()
airport_iata = "WAW"
print(f"Fetching full details for airport: {airport_iata}")

airport_details = client.airports.get_full(airport_iata)

if airport_details:
    print(f"  Name: {airport_details.name}")
    print(f"  ICAO: {airport_details.icao}")
    print(f"  City: {airport_details.city}")
    print(f"  Country: {airport_details.country_name}")
    print(f"  Latitude: {airport_details.lat}")
    print(f"  Longitude: {airport_details.lon}")
```

--------------------------------

### Get Live Flight Position Count

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Get the count of live flights matching specified filters without retrieving full position data.

```APIDOC
## Get Live Flight Position Count

### Description
Get the count of live flights matching specified filters without retrieving full position data.

### Method
GET

### Endpoint
/live/flightPositions/get_count

### Parameters
#### Query Parameters
- **bounds** (str or Boundary object) - Optional - Filter by geographic boundary (e.g., "north,south,west,east").
- **operating_as** (list[str]) - Optional - Filter by airline IATA codes.
- **altitude_ranges** (list[str or AltitudeRange object]) - Optional - Filter by altitude ranges (e.g., "min_altitude-max_altitude").

### Request Example
```python
from fr24sdk import Client
from fr24sdk.models.geographic import Boundary

with Client() as client:
    # Count flights in European airspace
    count = client.live.flight_positions.get_count(
        bounds=Boundary(north=72.0, south=35.0, west=-25.0, east=45.0)
    )
    print(f"Total flights in Europe: {count.record_count}")

    # Count flights by airline
    count = client.live.flight_positions.get_count(
        operating_as=["UAL", "AAL", "DAL"]
    )
    print(f"US major carriers in the air: {count.record_count}")

    # Count high-altitude flights
    count = client.live.flight_positions.get_count(
        bounds="90,-90,-180,180",  # Worldwide
        altitude_ranges=["35000-45000"]
    )
    print(f"Flights above FL350: {count.record_count}")
```

### Response
#### Success Response (200)
- **record_count** (int) - The number of flights matching the criteria.

#### Response Example
```json
{
  "record_count": 1500
}
```
```

--------------------------------

### Get Airport Information (Light) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves basic airport information (ICAO, IATA, name) using the airport's IATA or ICAO code. This method returns minimal data.

```python
from fr24sdk import Client

with Client() as client:
    # Get basic airport info by IATA code
    airport_light = client.airports.get_light(code="LHR")
    print(f"ICAO: {airport_light.icao}")  # Output: EGLL
    print(f"IATA: {airport_light.iata}")  # Output: LHR
    print(f"Name: {airport_light.name}")  # Output: London Heathrow Airport

    # Get by ICAO code
    airport_light = client.airports.get_light(code="KJFK")
    print(f"IATA: {airport_light.iata}")  # Output: JFK
```

--------------------------------

### Get Positional Flight Tracks with Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Accesses the breadcrumb trail of a flight using its unique FR24 ID. Returns timestamped latitude, longitude, altitude, and speed data points.

```python
from fr24sdk import Client

with Client() as client:
    response = client.flight_tracks.get(flight_id="3a55c027")

    for flight in response.data:
        print(f"Flight ID: {flight.fr24_id}")
        print(f"Number of track points: {len(flight.tracks)}")

        if flight.tracks:
            first = flight.tracks[0]
            last = flight.tracks[-1]

            print(f"\nFirst position:")
            print(f"  Time: {first.timestamp}")
            print(f"  Position: {first.lat}, {first.lon}")
            print(f"  Altitude: {first.alt} ft, Speed: {first.gspeed} kts")

            print(f"\nLast position:")
            print(f"  Time: {last.timestamp}")
            print(f"  Position: {last.lat}, {last.lon}")
            print(f"  Altitude: {last.alt} ft, Speed: {last.gspeed} kts")

            for point in flight.tracks:
                print(f"{point.timestamp}: {point.lat},{point.lon} @ {point.alt}ft")
```

--------------------------------

### Get Airport Information (Light)

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieve basic airport information by IATA or ICAO code. Returns minimal airport data including ICAO code, IATA code, and name.

```APIDOC
## Get Airport Information (Light)

Retrieve basic airport information by IATA or ICAO code. Returns minimal airport data including ICAO code, IATA code, and name.

```python
from fr24sdk import Client

with Client() as client:
    # Get basic airport info by IATA code
    airport_light = client.airports.get_light(code="LHR")
    print(f"ICAO: {airport_light.icao}")  # Output: EGLL
    print(f"IATA: {airport_light.iata}")  # Output: LHR
    print(f"Name: {airport_light.name}")  # Output: London Heathrow Airport

    # Get by ICAO code
    airport_light = client.airports.get_light(code="KJFK")
    print(f"IATA: {airport_light.iata}")  # Output: JFK
```
```

--------------------------------

### Get Historic Flight Position Count - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Fetches the count of historical flight positions for a specific timestamp, optionally filtered by geographical boundaries. Requires the 'fr24sdk' library.

```python
from datetime import datetime, timezone
from fr24sdk import Client

with Client() as client:
    timestamp = datetime(2025, 1, 15, 12, 0, 0, tzinfo=timezone.utc)

    # Count historic flights in a region
    count = client.historic.flight_positions.get_count(
        timestamp=timestamp,
        bounds="60,50,0,20"
    )
    print(f"Flights at timestamp: {count.record_count}")
```

--------------------------------

### Get Live Flight Position Count - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves the count of live flights matching specified filters without returning full position data. Filters include geographic bounds, airlines, and altitude ranges. Returns the total number of matching flights.

```python
from fr24sdk import Client
from fr24sdk.models.geographic import Boundary

with Client() as client:
    # Count flights in European airspace
    count = client.live.flight_positions.get_count(
        bounds=Boundary(north=72.0, south=35.0, west=-25.0, east=45.0)
    )
    print(f"Total flights in Europe: {count.record_count}")

    # Count flights by airline
    count = client.live.flight_positions.get_count(
        operating_as=["UAL", "AAL", "DAL"]
    )
    print(f"US major carriers in the air: {count.record_count}")

    # Count high-altitude flights
    count = client.live.flight_positions.get_count(
        bounds="90,-90,-180,180",  # Worldwide
        altitude_ranges=["35000-45000"]
    )
    print(f"Flights above FL350: {count.record_count}")
```

--------------------------------

### Get Airport Information (Full) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves detailed airport information, including coordinates, timezone, country, city, and runway details. Requires the airport's IATA or ICAO code.

```python
from fr24sdk import Client

with Client() as client:
    # Get full airport details
    airport = client.airports.get_full(code="WAW")

    print(f"Name: {airport.name}")  # Output: Warsaw Chopin Airport
    print(f"ICAO: {airport.icao}")  # Output: EPWA
    print(f"IATA: {airport.iata}")  # Output: WAW
    print(f"City: {airport.city}")  # Output: Warsaw
    print(f"Country: {airport.country.name} ({airport.country.code})")  # Output: Poland (PL)
    print(f"Coordinates: {airport.lat}, {airport.lon}")  # Output: 52.1657, 20.9671
    print(f"Elevation: {airport.elevation} ft")
    print(f"Timezone: {airport.timezone.name} (UTC{airport.timezone.offset:+d})")

    # Access runway information
    if airport.runways:
        for runway in airport.runways:
            print(f"Runway {runway.designator}: {runway.length}m x {runway.width}m")
            print(f"  Surface: {runway.surface.description}")
            print(f"  Heading: {runway.heading}°")
```

--------------------------------

### Get Historic Flight Positions (Light) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves lightweight historical flight position data for a specified timestamp. Supports filtering by altitude ranges, flight numbers, or geographical boundaries. Data is available from May 11, 2016 onwards. Requires the 'fr24sdk' library.

```python
from datetime import datetime, timezone
from fr24sdk import Client
from fr24sdk.models.geographic import AltitudeRange, Boundary

with Client() as client:
    # Get historic positions at specific timestamp
    timestamp = datetime(2025, 5, 14, 18, 15, 0, tzinfo=timezone.utc)

    # Filter by altitude ranges (can mix objects and strings)
    response = client.historic.flight_positions.get_light(
        timestamp=timestamp,
        altitude_ranges=[
            AltitudeRange(min_altitude=1000, max_altitude=10000),
            "10000-20000"  # String format also works
        ]
    )

    for flight in response.data:
        print(f"Flight ID: {flight.fr24_id}")
        print(f"Position at {flight.timestamp}: {flight.lat}, {flight.lon}")
        print(f"Altitude: {flight.alt} ft")

    # Get historic positions by flight number
    response = client.historic.flight_positions.get_light(
        timestamp=timestamp,
        flights=["SK2752", "BA123"]
    )

    # Using UNIX timestamp instead of datetime
    response = client.historic.flight_positions.get_light(
        timestamp=1715710500,  # UNIX timestamp
        bounds=Boundary(north=55.0, south=54.0, west=12.0, east=13.0)
    )
```

--------------------------------

### Get Historic Flight Positions (Full) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves comprehensive historical flight position data, including full flight and aircraft details, for a given timestamp. Supports filtering by flight numbers or aircraft registrations. Requires the 'fr24sdk' library.

```python
from datetime import datetime, timezone
from fr24sdk import Client

with Client() as client:
    timestamp = datetime(2025, 5, 14, 18, 15, 0, tzinfo=timezone.utc)

    # Get full historic flight data
    response = client.historic.flight_positions.get_full(
        timestamp=timestamp,
        flights=["SK2752"]
    )

    for flight in response.data:
        print(f"Flight: {flight.flight} ({flight.callsign})")
        print(f"Aircraft: {flight.type}, Registration: {flight.reg}")
        print(f"Route: {flight.orig_icao} -> {flight.dest_icao}")
        print(f"Position: {flight.lat}, {flight.lon} at {flight.alt} ft")
        print(f"Speed: {flight.gspeed} kts, Heading: {flight.track}°")

    # Get historic data for specific registrations
    response = client.historic.flight_positions.get_full(
        timestamp=timestamp,
        registrations=["SE-ROA", "G-XLEA"],
        limit=100
    )
```

--------------------------------

### Get Historic Flight Events (Full) - Python

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Retrieves comprehensive historical flight events with additional flight and aircraft details using the fr24sdk. This function requires flight IDs and event types as input and outputs detailed flight and event information, including position, altitude, and speed.

```python
from fr24sdk import Client

with Client() as client:
    response = client.historic.flight_events.get_full(
        flight_ids=["3a55c027"],
        event_types=["all"]
    )

    for flight in response.data:
        print(f"Flight ID: {flight.fr24_id}")
        print(f"Callsign: {flight.callsign}, Hex: {flight.hex}")
        print(f"Airline: Operating as {flight.operating_as}, Painted as {flight.painted_as}")
        print(f"Route: {flight.orig_iata}/{flight.orig_icao} -> {flight.dest_iata}/{flight.dest_icao}")

        print("\nEvents:")
        for event in flight.events:
            print(f"  [{event.type}] {event.timestamp}")
            if event.lat and event.lon:
                print(f"    Position: {event.lat}, {event.lon} @ {event.alt} ft")
            if event.gspeed:
                print(f"    Ground speed: {event.gspeed} kts")

            # Event-specific details
            if event.details:
                if hasattr(event.details, 'gate_ident'):
                    print(f"    Gate: {event.details.gate_ident}")
                if hasattr(event.details, 'takeoff_runway'):
                    print(f"    Runway: {event.details.takeoff_runway}")
                if hasattr(event.details, 'landed_runway'):
                    print(f"    Runway: {event.details.landed_runway}")
                if hasattr(event.details, 'entered_airspace'):
                    print(f"    Entered: {event.details.entered_airspace}")
```

--------------------------------

### Run Quality Assurance and Tests

Source: https://github.com/flightradar24/fr24api-sdk-python/blob/main/CONTRIBUTING.md

Commands to execute pre-commit hooks for linting and run the test suite with coverage reporting. These should be executed before submitting code.

```bash
pre-commit run --all-files
pytest --cov
```

--------------------------------

### Initialize Flightradar24 API Client

Source: https://github.com/flightradar24/fr24api-sdk-python/blob/main/README.md

Demonstrates different ways to initialize the Flightradar24 API client. It can be initialized using an environment variable, directly passing the API token, or using a context manager for proper resource handling.

```python
from fr24sdk.client import Client

client = Client()
```

```python
client = Client(api_token="your_actual_token_here")
```

```python
from fr24sdk.client import Client

with Client() as client:
    client.flight_summary(flight_ids="")
    pass
```

--------------------------------

### Execute Flight Position Requests with Filters

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Shows how to use the Client context manager to fetch flight positions. Filters can be passed as typed objects or as formatted strings.

```python
from fr24sdk import Client, Boundary, AltitudeRange

with Client() as client:
    # Using objects
    response = client.live.flight_positions.get_light(
        bounds=Boundary(north=55.6, south=55.5, west=12.5, east=12.6),
        altitude_ranges=[AltitudeRange(min_altitude=30000, max_altitude=40000)]
    )

    # Using strings (equivalent)
    response = client.live.flight_positions.get_light(
        bounds="55.6,55.5,12.5,12.6",
        altitude_ranges=["30000-40000"]
    )
```

--------------------------------

### Client Initialization

Source: https://context7.com/flightradar24/fr24api-sdk-python/llms.txt

Initialize the Flightradar24 API client to access all API resources. The client can read the API token from an environment variable or accept it directly. It is recommended to use the client as a context manager.

```APIDOC
## Client Initialization

Initialize the Flightradar24 API client to access all API resources. The client can read the API token from an environment variable or accept it directly.

```python
import os
from fr24sdk import Client

# Option 1: Using environment variable (set FR24_API_TOKEN)
os.environ["FR24_API_TOKEN"] = "your_api_token_here"
client = Client()

# Option 2: Pass token directly
client = Client(api_token="your_api_token_here")

# Option 3: Use as context manager (recommended)
with Client(api_token="your_api_token_here") as client:
    # API calls here
    airport = client.airports.get_full("JFK")
    print(f"Airport: {airport.name}")
# Client automatically closes when exiting the context

# Advanced configuration
client = Client(
    api_token="your_api_token_here",
    base_url="https://fr24api.flightradar24.com",  # Optional custom base URL
    api_version="v1",  # API version (default: v1)
    timeout=60.0  # Request timeout in seconds (default: 30)
)

# Don't forget to close when not using context manager
client.close()
```
```

--------------------------------

### Handle API Errors with Flightradar24 SDK

Source: https://github.com/flightradar24/fr24api-sdk-python/blob/main/README.md

Demonstrates how to handle various exceptions that can occur when using the Flightradar24 API SDK, including authentication failures, general API errors with detailed response information, and SDK-specific errors. It also includes a catch-all for unexpected exceptions.

```python
from fr24 import Client
from fr24.errors import AuthenticationError, ApiError, Fr24SdkError

# Assumes FR24_API_TOKEN is set, or pass it to Client()
try:
    with Client() as client:
        # Example: Intentionally try to get a non-existent airport
        airport = client.airports.get_full("INVALID_IATA")
        if airport:
            print(airport.name)

except AuthenticationError:
    print("Authentication failed. Please check your API token.")
except ApiError as e:
    print(f"API Error occurred: Status {e.status}, Message: {e.message}")
    print(f"Request URL: {e.request_url}")
    if e.body:
        print(f"Response body: {e.body}")
except Fr24SdkError as e:
    print(f"An SDK-specific error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```