# Flight Tracking API
> Real-time aircraft positions from live ADS-B data (OpenSky Network). Query all aircraft inside a geographic bounding box or track a single aircraft by its ICAO24 transponder address — returns position, barometric & geometric altitude, ground speed, heading, vertical rate, squawk and country of registration. Ideal for live maps, flight dashboards and proximity alerts.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/flights-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 2 req/s
- **Starter** ($15/Mo) — 50,000 calls/Mo, 5 req/s
- **Pro** ($49/Mo) — 500,000 calls/Mo, 20 req/s
- **Enterprise** ($199/Mo) — 5,000,000 calls/Mo, 50 req/s

## Endpoints

### Live

#### `GET /v1/aircraft` — Current state of one aircraft by ICAO24

**Parameters:**
- `icao24` (query, required, string) — 6-character hex transponder address, e.g. 3c6444

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flights-api/v1/aircraft"
```

#### `GET /v1/states` — Live aircraft inside a bounding box

**Parameters:**
- `lamin` (query, required, string) — Lower-bound latitude (-90..90) Example: `47`
- `lomin` (query, required, string) — Lower-bound longitude (-180..180) Example: `5`
- `lamax` (query, required, string) — Upper-bound latitude (-90..90) Example: `55`
- `lomax` (query, required, string) — Upper-bound longitude (-180..180) Example: `15`
- `on_ground` (query, optional, string) — Filter by on-ground state (true/false) Example: `false`
- `country` (query, optional, string) — Filter by country of registration (substring) Example: `Germany`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flights-api/v1/states?lamin=47&lomin=5&lamax=55&lomax=15&on_ground=false&country=Germany"
```

**Response:**
```json
{
    "data": {
        "bbox": {
            "lamax": 55,
            "lamin": 47,
            "lomax": 15,
            "lomin": 5
        },
        "time": 1780182639,
        "count": 7,
        "aircraft": [
            {
                "spi": false,
                "icao24": "3e557d",
                "squawk": "1000",
                "callsign": "FSE1D",
                "latitude": 47.9428,
                "longitude": 11.9568,
                "on_ground": false,
                "velocity_ms": 194.85,
                "last_contact": 1780182639,
                "velocity_kmh": 701.46,
                "time_position": 1780182639,
                "geo_altitude_m": 12496.8,
                "origin_country": "Germany",
                "true_track_deg": 257.65,
                "velocity_knots": 378.76,
                "baro_altitude_m": 12192,
                "position_source": "ADS-B",
                "vertical_rate_ms": 0
            },
            {
                "spi": false,
                "icao24": "3cbdeb",
                "squawk": "1000",
                "callsign": "BFD65H",
                "latitude": 49.3405,
                "longitude": 6.6647,
                "on_ground": false,
                "velocity_ms": 212.92,
                "last_contact": 1780182639,
                "velocity_kmh": 766.51,
                "time_position": 1780182639,
                "geo_altitude_m": 12710.16,
                "origin_country": "Germany",
                "true_track
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Field reference & data source

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flights-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "fields": {
            "icao24": "Unique 24-bit transponder address (hex)",
            "squawk": "Transponder code",
            "callsign": "Flight callsign (8 chars)",
            "latitude": "WGS-84 latitude (deg)",
            "longitude": "WGS-84 longitude (deg)",
            "on_ground": "Aircraft is on the ground",
            "velocity_ms": "Ground speed (m/s)",
            "velocity_kmh": "Ground speed (km/h)",
            "geo_altitude_m": "Geometric altitude (m)",
            "origin_country": "Country of registration",
            "true_track_deg": "Heading clockwise from north (deg)",
            "velocity_knots": "Ground speed (knots)",
            "baro_altitude_m": "Barometric altitude (m)",
            "position_source": "ADS-B | ASTERIX | MLAT | FLARM",
            "vertical_rate_ms": "Climb (+) / descent (−) rate (m/s)"
        },
        "source": "OpenSky Network",
        "endpoints": {
            "/v1/states": "Live aircraft in a bounding box (lamin, lomin, lamax, lomax; each side ≤ 30°). Optional on_ground, country filter.",
            "/v1/aircraft": "Current state of one aircraft by icao24 (6-hex transponder address)."
        },
        "description": "Live ADS-B aircraft state vectors"
    },
    "meta": {
        "timestamp": "2026-05-30T23:10:49.095Z",
        "request_id": "79e5c54a-40d9-48b3-aeb0-8e71d87e47d8"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/flights-api
OpenAPI spec: https://www.oanor.com/api/flights-api/openapi.json