Tutorial: OpenSky Network (Aircraft Tracking)

Transport

Data source: OpenSky Network API

Overview

OpenSky Network (Aircraft Tracking) wraps OpenSky Network API, handling authentication, pagination, and rate limits for you. This tutorial covers all 4 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-opensky": {
      "url": "https://context.gnist.ai/mcp/opensky/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (4)

`get_aircraft_states`

Get live aircraft positions from the OpenSky Network. Returns real-time ADS-B state vectors for aircraft currently in the air. Filter by geographic bounding box or specific ICAO24 transponder addresses. Data includes position, altitude, speed, heading, and country of origin. Tip: Use a bounding box to focus on a region (e.g. lamin=40, lamax=50, lomin=-5, lomax=10 for Western Europe). Args: lamin: Lower latitude bound. All 4 bbox params required together. lamax: Upper latitude bound. lomin: Lower longitude bound. lomax: Upper longitude bound. icao24: ICAO24 hex addresses to filter by. Max 10. limit: Maximum aircraft to return (1-2000, default 200). Returns: Live aircraft with position, altitude, speed, heading, callsign.

Parameter	Type	Required	Description
`lamin`	any	optional	Lower latitude bound (WGS-84 degrees, e.g. 45.0). All four bbox params required together.
`lamax`	any	optional	Upper latitude bound (e.g. 50.0).
`lomin`	any	optional	Lower longitude bound (e.g. -5.0).
`lomax`	any	optional	Upper longitude bound (e.g. 5.0).
`icao24`	any	optional	ICAO24 hex addresses to filter (e.g. ["3c6444", "a1b2c3"]). Max 10.
`limit`	integer	optional	Maximum aircraft to return (1-2000, default 200). (default: `200`)

curl -X POST "https://context.gnist.ai/mcp/opensky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_aircraft_states", "arguments": {"lamin": "45.0"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/opensky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'lamin': '45.0'}, 'name': 'get_aircraft_states'}},
)
print(resp.json())

`get_flight_track`

Get the flight trajectory (waypoints) for an aircraft. Returns the path an aircraft has taken, with latitude, longitude, altitude, and heading at each waypoint. Use time_value=0 for the current live track, or a specific Unix timestamp for a historical flight (up to 30 days back). Args: icao24: ICAO24 hex address (6 hex characters, e.g. "3c6444"). time_value: Unix timestamp within the flight. 0 for live track. Returns: Flight path with callsign, start/end times, and waypoints (time, lat, lon, altitude, heading, on_ground).

Parameter	Type	Required	Description
`icao24`	string	required	ICAO24 hex address of the aircraft (e.g. "3c6444"). Use search_aircraft to find addresses.
`time_value`	integer	optional	Unix timestamp within the flight. Use 0 for current/live track. (default: `0`)

curl -X POST "https://context.gnist.ai/mcp/opensky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_flight_track", "arguments": {"icao24": "3c6444"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/opensky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'icao24': '3c6444'}, 'name': 'get_flight_track'}},
)
print(resp.json())

`search_aircraft`

Search for a specific aircraft by ICAO24 address or callsign. Two search modes: - By ICAO24: directly queries for the aircraft (no bbox needed). - By callsign: searches within a bounding box region and filters by callsign match. Bounding box is required for callsign search. Args: icao24: ICAO24 hex address to look up directly. callsign: Callsign to search for (requires bounding box). lamin: Lower latitude bound (for callsign search). lamax: Upper latitude bound. lomin: Lower longitude bound. lomax: Upper longitude bound. limit: Maximum results (1-200, default 50). Returns: Matching aircraft with position, altitude, speed, heading.

Parameter	Type	Required	Description
`icao24`	any	optional	ICAO24 hex address to look up (e.g. "3c6444"). Directly queries the aircraft.
`callsign`	any	optional	Callsign to search for (e.g. "DLH9MT", "RYR1234"). Requires bounding box.
`lamin`	any	optional	Lower latitude bound (required for callsign search).
`lamax`	any	optional	Upper latitude bound.
`lomin`	any	optional	Lower longitude bound.
`lomax`	any	optional	Upper longitude bound.
`limit`	integer	optional	Maximum results (1-200, default 50). (default: `50`)

curl -X POST "https://context.gnist.ai/mcp/opensky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_aircraft", "arguments": {"icao24": "3c6444"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/opensky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'icao24': '3c6444'}, 'name': 'search_aircraft'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/opensky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/opensky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_aircraft to find items, then get_aircraft_states to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does OpenSky Network (Aircraft Tracking) provide?

Live aircraft tracking via ADS-B — real-time positions, flight trajectories, and aircraft search. Covers global airspace with position, altitude, speed, heading, and callsign data. It exposes 4 tools: get_aircraft_states, get_flight_track, search_aircraft, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the OpenSky Network (Aircraft Tracking) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.