API Documentation
=================

Main Function
-------------

get_beluga
~~~~~~~~~~

.. autofunction:: tracker.get_beluga

**Parameters:**

- ``registration`` (str, optional): Filter by aircraft registration (e.g., "F-GXLJ")
- ``status`` (str, optional): Filter by flight status - either "enroute" or "on_ground"
- ``from_airport_icao`` (str, optional): Filter by departure airport ICAO code (e.g., "LFBO")
- ``to_airport_icao`` (str, optional): Filter by destination airport ICAO code

**Returns:**

A list of :class:`BelugaState` objects containing detailed flight information.

**Raises:**

- ``ValueError``: If invalid parameters are provided (invalid registration format, invalid ICAO codes, or invalid status)

Data Models
-----------

BelugaState
~~~~~~~~~~~

.. autoclass:: _models.BelugaState
   :members:
   :undoc-members:

**Attributes:**

- ``id`` (str): Unique flight identifier
- ``registration`` (str): Aircraft registration number (e.g., "F-GXLJ")
- ``from_airport`` (str): Departure airport name
- ``to_airport`` (str): Destination airport name
- ``scheduled_departure`` (int): Scheduled departure time (Unix timestamp)
- ``scheduled_arrival`` (int): Scheduled arrival time (Unix timestamp)
- ``real_departure`` (int): Actual departure time (Unix timestamp)
- ``real_arrival`` (int): Actual arrival time (Unix timestamp, None if not landed)
- ``eta`` (int): Estimated time of arrival (Unix timestamp)
- ``altitude`` (int): Current altitude in feet
- ``ground_speed`` (int): Current ground speed in knots
- ``heading`` (int): Current heading in degrees (0-360)
- ``position`` (tuple): Current position as (latitude, longitude)
- ``status`` (str): Flight status - "enroute", "on_ground", or "unknown"
- ``last_update`` (int): Last data update time (Unix timestamp)

Status Determination
~~~~~~~~~~~~~~~~~~~~

The flight status is automatically determined based on altitude and ground speed:

- **enroute**: Altitude > 1000 ft AND ground speed > 100 kt
- **on_ground**: Altitude < 100 ft AND ground speed < 10 kt
- **unknown**: Does not meet either criteria