OpenSky Network Pet

Track aircraft and helicopters in real-time using the OpenSky Network's open ADS-B receiver network.

Features

• Real-time flight tracking - Monitor aircraft positions globally
• Geographic search - Find flights in specific areas (perfect for Athens helicopter monitoring)
• Helicopter filtering - Easily identify helicopters vs. other aircraft
• Flight path tracking - Get full flight routes with waypoints
• Anonymous or authenticated - Works without API key, better with authentication

Setup

No API Key Required!

The OpenSky Network is completely free and open. You can use it anonymously:

cd pets/opensky
bun test:pet opensky --query "find helicopters over Athens"

Optional: Authentication for Better Limits

Sign up at opensky-network.org for:

• 10x higher rate limits (4000 vs 400 credits/day)
• Access to historical flight data (up to 30 days)
• Flight track API access

Add to your .env:

OPENSKY_USERNAME=your_username
OPENSKY_PASSWORD=your_password

Usage Examples

Find Helicopters Over Athens

opencode run "find all helicopters flying over Athens Greece right now"

The AI will use the opensky-search-area tool with Athens coordinates:

• Latitude: 37.8 to 38.1
• Longitude: 23.5 to 24.0
• Filter: Helicopters only (category 7)

Monitor Air Traffic in a Region

opencode run "show all aircraft between coordinates 37.8,23.5 and 38.1,24.0"

Track a Specific Aircraft

opencode run "track aircraft with ICAO24 code abc123"

(Requires authentication)

Available Tools

opensky-test-connection

Test connection and show authentication status.

opencode run "test opensky connection"

opensky-search-area

Search for aircraft in a bounding box. Returns positions, velocities, and categories.

Parameters:

• lamin - Southern boundary latitude (e.g., 37.8)
• lomin - Western boundary longitude (e.g., 23.5)
• lamax - Northern boundary latitude (e.g., 38.1)
• lomax - Eastern boundary longitude (e.g., 24.0)
• extended - Include category data (identifies helicopters)
• filterHelicopters - Show only helicopters

opensky-get-all-states

Get current positions of all aircraft. Can filter by ICAO24 codes.

Parameters:

• icao24 - Filter by transponder address (optional)
• time - Historical timestamp (authenticated only)

opensky-track-aircraft

Get full flight path for a specific aircraft.

Parameters:

• icao24 - Aircraft transponder address (required)
• time - Timestamp for historical track (0 = live)

Requires authentication

Aircraft Categories

When using extended: true, aircraft are categorized:

• Category 1: Light aircraft (< 15,500 lbs)
• Category 2: Small aircraft (15,500 - 75,000 lbs)
• Category 3: Large aircraft (75,000 - 300,000 lbs)
• Category 4: High vortex large aircraft
• Category 5: Heavy aircraft (> 300,000 lbs)
• Category 6: High performance (>5g acceleration)
• Category 7: Helicopter
• Category 8: Rotorcraft (not helicopter)
• Category 9: Glider/sailplane
• Category 10: Lighter-than-air
• Category 11: Parachutist/skydiver
• Category 12: Ultralight/hang-glider
• Category 13: Reserved
• Category 14: Unmanned aerial vehicle (UAV)
• Category 15: Space/trans-atmospheric vehicle
• Category 16: Surface vehicle (emergency/service)
• Category 17: Surface vehicle (ground obstruction)

Athens Coordinates Reference

For monitoring Athens air traffic:

{
  "lamin": 37.8,
  "lomin": 23.5,
  "lamax": 38.1,
  "lomax": 24.0
}

This covers:

• Athens city center
• Eleftherios Venizelos Airport
• Piraeus port
• Surrounding Attica region

Rate Limits

| Mode | Credits/Day | Resolution | Historical Data | |------|-------------|------------|-----------------| | Anonymous | 400 | 10 seconds | No | | Authenticated | 4000 | 10 seconds | Yes (30 days) |

API Reference

• OpenSky Network Documentation
• REST API Docs
• Sign Up

Troubleshooting

"Too many requests" error

You've hit your rate limit. Wait a few minutes, or sign up for authentication to get 10x more credits.

No aircraft found

• Check your coordinates are correct
• Ensure latitude/longitude ranges are valid
• Try a larger bounding box
• Some areas have less ADS-B coverage

Track data requires authentication

The /tracks endpoint requires a free OpenSky Network account. Sign up at opensky-network.org and add your credentials to .env.

Example Queries

# Test connection
opencode run "test opensky connection"

# Find helicopters over Athens
opencode run "find helicopters flying over Athens right now"

# Monitor all aircraft in Athens area
opencode run "show all flights over Athens Greece"

# Get specific aircraft details
opencode run "get current position of aircraft abc123"

# Track flight path (requires auth)
opencode run "show flight path for aircraft abc123"

Contributing

Found a bug or want to add features? Open an issue or PR at the OpenPets repository.

License

MIT