Metadata-Version: 2.4
Name: pyopensky
Version: 2.16
Summary: A Python interface for OpenSky database
Project-URL: Repository, https://github.com/open-aviation/pyopensky/
Author-email: Xavier Olive <git@xoolive.org>, Junzi Sun <j.sun-1@tudelft.nl>
License-Expression: MIT
Requires-Python: >=3.9
Requires-Dist: appdirs>=1.4.4
Requires-Dist: httpx>=0.27.2
Requires-Dist: minio>=7.2.8
Requires-Dist: numpy>=2.0.2
Requires-Dist: pandas>=2.2.2
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: pyjwt>=2.9.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: tqdm>=4.66.5
Requires-Dist: trino[sqlalchemy]>=0.329.0
Requires-Dist: typing-extensions>=4.12.2
Requires-Dist: tzdata>=2024.2
Provides-Extra: cartes
Requires-Dist: cartes>=0.8.5; (python_version >= '3.10') and extra == 'cartes'
Provides-Extra: pymodes
Requires-Dist: pymodes>=2.18; extra == 'pymodes'
Provides-Extra: rs1090
Requires-Dist: rs1090>=0.3.8; extra == 'rs1090'
Description-Content-Type: text/markdown

# pyopensky

The `pyopensky` Python library provides functions to download data from the OpenSky Network live API and historical databases. It aims at making ADS-B and Mode S data from OpenSky easily accessible in the Python programming environment.

**Key features:**

- Access to **live** aircraft state vectors and flight information via REST API
- Query **historical** ADS-B and Mode S data from the Trino database
- Decode and rebuild flight trajectories from raw messages
- Support for spatial and temporal filtering
- Built-in caching for efficient data retrieval
- Integration with pandas DataFrames for easy data analysis

Full documentation on <https://mode-s.org/pyopensky/>

## Installation

```sh
pip install pyopensky
```

or add it in your project with

```sh
uv add pyopensky
```

The library is also available on conda-forge, although this approach is no longer recommended:

```sh
conda install -c conda-forge pyopensky
```

## Credentials

Access to the OpenSky Network historical database requires authentication. See details in the [documentation](https://open-aviation.github.io/pyopensky/credentials.html) on how to:

- Apply an OpenSky Network account
- Configure your credentials for API access
- Set up authentication for the Trino database

## Usage

### 1. REST API

> [!IMPORTANT]
> Do NOT use REST API for historical data, use trino instead!

Access **live** and recent flight data.

#### Functions

```python
from pyopensky.rest import REST

rest = REST()

rest.states()
rest.tracks(icao24)
rest.routes(callsign)
rest.aircraft(icao24, begin, end)
rest.arrival(airport, begin, end)
rest.departure(airport, begin, end)
```

#### Examples

```python
from pyopensky.rest import REST

rest = REST()

# Get current state vectors for all aircraft
rest.states()

# Get trajectory for a specific aircraft
rest.tracks(icao24="3c6444")

# Get route information for a callsign
rest.routes(callsign="AFR292")

# Get flights for a specific aircraft in a time range
# NOTE: do NOT use REST for historical data, use trino instead!!
rest.aircraft(icao24="3c6444", begin="2024-01-01", end="2024-01-02")

# Get arrivals at an airport
# NOTE: do NOT use REST for historical data, use trino instead!!
rest.arrival(airport="EHAM", begin="2024-01-01 12:00", end="2024-01-01 13:00")

# Get departures from an airport
# NOTE: do NOT use REST for historical data, use trino instead!!
rest.departure(airport="LFPG", begin="2024-01-01 12:00", end="2024-01-01 13:00")
```

### 2. Trino Interface

Query **historical** ADS-B and Mode S data with advanced selection and processing.

Functions

```python
from pyopensky.trino import Trino

trino = Trino()
# full description of the whole set of parameters in the documentation
trino.flightlist(start, stop, *, airport, callsign, icao24)
trino.rawdata(start, stop, *, callsign, icao24, bounds)
trino.history(start, stop, *, callsign, icao24, bounds)
trino.rebuild(start, stop, *, icao24, bounds)
```

> [!IMPORTANT]
> Refer to the [documentation](https://mode-s.org/pyopensky) for advanced usage and parameter details.
