# Positionsverlauf

Historische ADS-B-Positionsdaten nach ICAO24-Hex-Code oder Kennzeichen — neueste zuerst, mit zugeordneten Flugfenstern.



Rufen Sie eine Zeitleiste des Rohpositionsverlaufs für ein Luftfahrzeug anhand des Kennzeichens oder des [ICAO24](/docs/v31/adsb)-Hex-Codes ab — ohne vorherigen Suchschritt. Anders als der Endpoint für den [Flug-Track](/docs/v31/historical-adsb-flight-detail#flight-track) ist der Positionsverlauf nicht auf einen einzelnen Flug beschränkt und kann in einem Zeitfenster mehrere Flüge umfassen.

**Wahl des Pfads:** Für den Track eines einzelnen archivierten Flugs von Gate zu Gate verwenden Sie Kennzeichen → [Flugsuche](/docs/v31/historical-adsb-flight-search) → `flight_id` → [Track](/docs/v31/historical-adsb-flight-detail#flight-track). Für eine Rohzeitleiste über mehrere Flüge hinweg oder wenn Ihnen die Flugabgrenzungen nicht bekannt sind, verwenden Sie direkt Kennzeichen → [Positionen](/docs/v31/historical-adsb-positions).

Tarifstufen: [Hub für historische ADS-B-Daten](/docs/v31/historical-adsb).

<DocRequirements>
  <DocRequirementAuth />

  <DocRequirement label="Tarif" href="/docs/rate-limits#historical-adsb-path-tiers">
    <strong>Pro</strong>, <strong>Ultra</strong> oder <strong>Mega</strong> — verwenden Sie das Pfadpräfix, das zum benötigten Zeitfenster passt.
  </DocRequirement>
</DocRequirements>

<DocJumpNav>
  <DocJumpLink href="#aircraft-position-history-by-icao24" icon="solar:transmission-bold-duotone">
    Nach 

    [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)
  </DocJumpLink>

  <DocJumpLink href="#aircraft-position-history-by-registration" icon="solar:plate-bold-duotone">
    Nach Kennzeichen
  </DocJumpLink>
</DocJumpNav>

<a id="aircraft-position-history-by-icao24" />

## Nach ICAO24 [#by-icao24]

### Anfrage [#request]

<DocApiPath method="GET" path="/ultra/history/positions/{icao24}" />

| Parameter | Typ     | Erforderlich | Standard | Beschreibung                                                        |
| --------- | ------- | ------------ | -------- | ------------------------------------------------------------------- |
| `icao24`  | string  | Ja           | -        | ICAO24-Hex-Code des Luftfahrzeugs (6 Zeichen)                       |
| `start`   | string  | Nein         | vor 24 h | Beginn des Zeitfensters — ISO 8601                                  |
| `end`     | string  | Nein         | jetzt    | Ende des Zeitfensters — ISO 8601                                    |
| `limit`   | integer | Nein         | `1000`   | Max. Anzahl der Positionszeilen (max. **5.000** auf dem ULTRA-Pfad) |

Das Abfragefenster darf bei `/ultra/history/...` **90 Tage** nicht überschreiten.

<DocDetails title="MEGA-Pfad — nach [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) (`/mega/history/...`)">
  <DocApiPath method="GET" path="/mega/history/positions/{icao24}" />

  | Parameter | Typ     | Erforderlich | Standard | Beschreibung                                                                    |
  | --------- | ------- | ------------ | -------- | ------------------------------------------------------------------------------- |
  | `icao24`  | string  | Ja           | -        | ICAO24-Hex-Code des Luftfahrzeugs                                               |
  | `start`   | string  | Nein         | vor 24 h | Beginn des Zeitfensters — ISO 8601 (max. **365 Tage** Spanne auf dem MEGA-Pfad) |
  | `end`     | string  | Nein         | jetzt    | Ende des Zeitfensters                                                           |
  | `limit`   | integer | Nein         | `1000`   | Max. Anzahl der Positionen (max. **10.000** auf dem MEGA-Pfad)                  |

  Erfordert den Tarif **Ultra** oder **Mega**. Gleiche Antwortstruktur wie bei ULTRA.
</DocDetails>

<a id="aircraft-position-history-by-registration" />

## Nach Kennzeichen [#by-registration]

Gleiche Antwortstruktur wie [nach ICAO24](#aircraft-position-history-by-icao24), akzeptiert jedoch ein [Kennzeichen](/docs/v31/aircraft-lookup) (z. B. `N12345`, `G-XWBA`), das serverseitig in einen [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)-Code aufgelöst wird. Gibt `404` zurück, wenn das Kennzeichen nicht im Luftfahrzeugregister enthalten ist.

### Anfrage [#request-1]

<DocApiPath method="GET" path="/ultra/history/positions/registration/{registration}" />

| Parameter      | Typ     | Erforderlich | Standard | Beschreibung                                                        |
| -------------- | ------- | ------------ | -------- | ------------------------------------------------------------------- |
| `registration` | string  | Ja           | -        | Kennzeichen des Luftfahrzeugs                                       |
| `start`        | string  | Nein         | vor 24 h | Beginn des Zeitfensters — ISO 8601                                  |
| `end`          | string  | Nein         | jetzt    | Ende des Zeitfensters — ISO 8601                                    |
| `limit`        | integer | Nein         | `1000`   | Max. Anzahl der Positionszeilen (max. **5.000** auf dem ULTRA-Pfad) |

<DocDetails title="MEGA-Pfad — nach Kennzeichen (`/mega/history/...`)">
  <DocApiPath method="GET" path="/mega/history/positions/registration/{registration}" />

  | Parameter      | Typ     | Erforderlich | Standard | Beschreibung                                                                    |
  | -------------- | ------- | ------------ | -------- | ------------------------------------------------------------------------------- |
  | `registration` | string  | Ja           | -        | Kennzeichen                                                                     |
  | `start`        | string  | Nein         | vor 24 h | Beginn des Zeitfensters — ISO 8601 (max. **365 Tage** Spanne auf dem MEGA-Pfad) |
  | `end`          | string  | Nein         | jetzt    | Ende des Zeitfensters                                                           |
  | `limit`        | integer | Nein         | `1000`   | Max. Anzahl der Positionen (max. **10.000** auf dem MEGA-Pfad)                  |

  Erfordert den Tarif **Ultra** oder **Mega**. Gleiche Antwortstruktur wie bei ULTRA.
</DocDetails>

## Antwort [#response]

```json
{
  "icao24": "40621d",
  "count": 864,
  "positions": [
    {
      "timestamp": "2026-05-13T03:08:05Z",
      "icao24": "40621d",
      "latitude": 40.6413,
      "longitude": -73.7781,
      "altitude_baro": 0,
      "ground_speed": 12,
      "track": 90,
      "vertical_rate": 0,
      "callsign": "BAW178",
      "is_on_ground": true,
      "registration": "G-XWBA",
      "aircraft_type": "B77W",
      "gps_spoofed": false
    }
  ],
  "flights": [
    {
      "flight_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "callsign": "BAW178",
      "flight_number": "BAW178",
      "departure_airport_icao": "EGLL",
      "departure_airport_iata": "LHR",
      "departure_airport_name": "London Heathrow Airport",
      "arrival_airport_icao": "KJFK",
      "arrival_airport_iata": "JFK",
      "arrival_airport_name": "John F Kennedy International Airport",
      "takeoff_time": "2026-05-12T19:45:00Z",
      "landing_time": "2026-05-13T03:08:00Z",
      "flight_start": "2026-05-12T19:42:05Z",
      "flight_end": "2026-05-13T03:11:10Z",
      "flight_state": "ARCHIVED"
    }
  ]
}
```

| Feld        | Typ     | Erforderlich | Null? | Beschreibung                                                                                          |
| ----------- | ------- | ------------ | ----- | ----------------------------------------------------------------------------------------------------- |
| `icao24`    | string  | **Ja**       | Nie   | Hex-Code des abgefragten Luftfahrzeugs                                                                |
| `count`     | integer | **Ja**       | Nie   | Anzahl der Elemente in `positions`                                                                    |
| `positions` | array   | **Ja**       | Nie   | [Positionsdaten](/docs/v31/historical-adsb-flight-detail#position-snapshot-positions), neueste zuerst |
| `flights`   | array   | **Ja**       | Nie   | Archivierte Flüge, die sich mit dem Zeitfenster überschneiden                                         |

Der Endpoint für Kennzeichen ergänzt ein `registration`-Feld auf oberster Ebene, das das aufgelöste Kennzeichen wiedergibt; `icao24` wird nach der serverseitigen Abfrage befüllt.

### Flugfenster (`flights[]`) [#flight-window-flights]

| Feld                     | Typ            | Erforderlich | Null?  | Beschreibung                                      |
| ------------------------ | -------------- | ------------ | ------ | ------------------------------------------------- |
| `flight_id`              | string         | **Ja**       | Nie    | UUID für Detail- und Track-Abfragen               |
| `callsign`               | string \| null | Nein         | **Ja** | Rufzeichen während dieses Flugs                   |
| `flight_number`          | string \| null | Nein         | **Ja** | Normalisierte Flugnummer, sofern ermittelt        |
| `departure_airport_icao` | string \| null | Nein         | **Ja** | Abflughafen, sofern ermittelt                     |
| `departure_airport_iata` | string \| null | Nein         | **Ja** | IATA-Code des Abflughafens                        |
| `departure_airport_name` | string \| null | Nein         | **Ja** | Name des Abflughafens                             |
| `arrival_airport_icao`   | string \| null | Nein         | **Ja** | Zielflughafen, sofern ermittelt                   |
| `arrival_airport_iata`   | string \| null | Nein         | **Ja** | IATA-Code des Zielflughafens                      |
| `arrival_airport_name`   | string \| null | Nein         | **Ja** | Name des Zielflughafens                           |
| `takeoff_time`           | string \| null | Nein         | **Ja** | Startzeit dieses Flugs (ISO 8601)                 |
| `landing_time`           | string \| null | Nein         | **Ja** | Landezeit dieses Flugs (ISO 8601)                 |
| `flight_start`           | string         | **Ja**       | Nie    | Erste archivierte Position in diesem Flugfenster  |
| `flight_end`             | string         | **Ja**       | Nie    | Letzte archivierte Position in diesem Flugfenster |
| `flight_state`           | string \| null | Nein         | **Ja** | Archivstatus (z. B. `ARCHIVED`)                   |

## Client-Typen [#client-types]

<DocClientTypes id="v31/historical-adsb/history-types" />

## Integration [#integration]

Erstellen Sie einen Wiedergabe-Track anhand des Kennzeichens eines Luftfahrzeugs. Das folgende Beispiel ruft den Positionsverlauf über das Kennzeichen ab, kehrt die Positionen für die Wiedergabe auf der Karte in chronologische Reihenfolge um und behandelt sowohl den Fehlerfall `404` (unbekanntes Kennzeichen) als auch `422` (Zeitfenster zu groß). Erweitern Sie es auf den Pfad `/mega/history/...`, wenn ein Rückblick von 90 Tagen nicht ausreicht.

<DocExample id="v31/historical-adsb/positions-fetch" />

### Hinweise zur Implementierung [#implementation-notes]

**Kennzeichen oder Hex-Code.** Verwenden Sie bevorzugt `registration`, wenn Ihre Nutzer die Kennzeichen kennen; verwenden Sie `icao24`, wenn Sie rohe [ADS-B](https://www.faa.gov/air_traffic/technology/adsb)-Feeds verarbeiten. Die Endpoints für Kennzeichen geben `404` zurück, wenn das Kennzeichen unbekannt ist.

**Wichtig:** Der Positionsverlauf gibt `positions` mit den neuesten Einträgen zuerst zurück. Kehren Sie die Reihenfolge für die Wiedergabe auf der Karte chronologisch um.

**Größe des Zeitfensters.** Bei einer Abtastung im 5-Sekunden-Takt erzeugt ein einzelner Flug etwa 700–1.500 Positionszeilen. Erhöhen Sie bei Anfragen über mehrere Tage `limit` (bis 5.000 bei ULTRA, 10.000 bei MEGA) oder verkleinern Sie das Zeitfenster und führen Sie die Ergebnisse clientseitig zusammen.

## Fehlerantworten [#error-responses]

`401`/`403` durch Tarifbeschränkungen: [Hub für historische ADS-B-Daten](/docs/v31/historical-adsb#error-responses). Endpoint-spezifisch:

### 404 — Kennzeichen nicht gefunden [#404--registration-not-found]

```json
{
  "detail": "Registration 'N00000' not found"
}
```

Wird von `/history/positions/registration/{registration}` zurückgegeben, wenn das Kennzeichen nicht im Luftfahrzeugregister enthalten ist.

### 422 — Zeitfenster zu groß [#422--window-too-wide]

Wird zurückgegeben, wenn die Spanne zwischen `start` und `end` das Maximum des Pfads überschreitet — **90 Tage** bei `/ultra/history/...` oder **365 Tage** bei `/mega/history/...`:

```json
{
  "detail": "Query window exceeds maximum of 90 days for your plan on /ultra/history/..."
}
```

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/ultra/history/positions/{icao24}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ultra/history/positions/registration/{registration}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/mega/history/positions/{icao24}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/mega/history/positions/registration/{registration}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />