ha-opensky-core

Standalone Python library for accessing the OpenSky Network API using OAuth authentication and for performing aircraft, airport and approach analysis.

The library is designed to be usable independently of Home Assistant. Home Assistant-specific functionality is implemented separately in the ha-opensky-oauth integration.

Features

• OpenSky Network OAuth authentication
• Search aircraft within a geographic area
• Aircraft data models using metric units
• Aircraft metadata lookup
• Aircraft photo lookup and fallback providers
• Airport and runway database
• Airport and runway analysis
• Aircraft approach detection and tracking
• Approach entry and exit transitions
• Reusable ApproachService boundary for frontend applications

Installation

pip install ha-opensky-core

Basic usage

from opensky.client import OpenSkyClient
from opensky.models import SearchArea

area = SearchArea(
    latitude=50.901,
    longitude=4.484,
    radius_km=20,
)

client = OpenSkyClient(...)

aircraft = client.get_aircraft(area)

for item in aircraft:
    print(item.icao24, item.callsign)

The exact authentication and client configuration depends on the OpenSky OAuth credentials available to the application.

Airport database

The package contains the airport and runway databases required by the airport analysis functionality.

from opensky.airport import AirportDatabase

db = AirportDatabase()

print(db.count())

airport = db.require("EBBR")
print(airport.name)

Architecture

ha-opensky-core contains the reusable OpenSky functionality and has no dependency on Home Assistant.

The architecture is intentionally split into two layers:

┌──────────────────────────────────────┐
│       Home Assistant integration     │
│        ha-opensky-oauth              │
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│          ha-opensky-core             │
│                                      │
│  OAuth / API / Aircraft / Metadata   │
│  Airports / Runways / Approaches     │
└──────────────────┬───────────────────┘
                   │
                   ▼
          OpenSky Network API

This allows the core library to be tested and used independently of Home Assistant.

Development

Clone the repository and create a virtual environment:

python -m venv .venv

Activate the environment and install the package in editable mode:

python -m pip install -e .

Run the available test and diagnostic scripts with:

python -m scripts.test_oauth
python -m scripts.test_metadata
python -m scripts.test_airports

Requirements

• Python 3.13 or newer
• OpenSky Network OAuth credentials for authenticated API access

Status

This project is currently in alpha development.

The API may change between releases.

License

MIT License.