# Luftfahrzeugabfrage Luftfahrzeuge per Kennzeichen oder ICAO24-Hex abfragen – Typ, Betreiber, Seriennummer und optionale Community-Fotos aus über 600.000 Registereinträgen. Ermitteln Sie Typ, Betreiber und Fotos eines Luftfahrzeugs anhand des **Kennzeichens** (national registrierte Luftfahrzeugkennung, z. B. `G-STBC`, `N12345`) oder der **[ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)** (sechsstellige hexadezimale Transponderadresse, die per [ADS-B](https://www.faa.gov/air_traffic/technology/adsb) ausgestrahlt wird, z. B. `40621D`). Das SkyLink-Luftfahrzeugregister umfasst über 615.000 Datensätze und wird täglich aktualisiert — neue Registrierungen und Halterwechsel können den offiziellen Behördenregistern hinterherhinken. Nutzen Sie die Kennzeichenabfrage, wenn Ihre UI oder Flugplanzeile bereits ein Kennzeichen enthält. Nutzen Sie die [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)-Abfrage, wenn Sie Hex-Codes aus einem Live-[ADS-B](/docs/v31/adsb)-Feed erhalten und diese um Typ- und Betreiber-Metadaten anreichern müssen. Nachdem Sie `icao_type` (vierstelliger Luftfahrzeugtypcode aus Flugplänen, z. B. `B738`) ermittelt haben, fahren Sie mit [Flugzeugleistung](/docs/v31/aircraft-performance) fort, um Reisegeschwindigkeit, Reichweite und Wirbelschleppenkategorie abzurufen. | Endpoint | Einsatzzweck | | ------------------------------------------- | ---------------------------------------------------------------------------------- | | `GET /aircraft/registration/{registration}` | Kennzeichenabfrage für Flugkarten, Flottenseiten oder Fotogalerien | | `GET /aircraft/icao24/{icao24}` | Live-ADS-B-Hex-Adressen aus Tracker-Feeds anreichern | | `GET /aircraft/database/stats` | Health Check — prüfen, ob das Register geladen ist, und Datensatzanzahlen einsehen | **Wichtig:** Kennzeichen- und [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)-Abfragen liefern HTTP **200** mit `found: false` und `aircraft: null`, wenn kein Treffer existiert — niemals 404. Prüfen Sie `found` im JSON-Body; behandeln Sie dies nicht als HTTP-Fehler. **Wichtig:** `photos` ist der Einfachheit halber standardmäßig `true`, erhöht aber die Latenz. Übergeben Sie `photos=false` in Listenansichten, Batch-Anreicherungsjobs und Kartenoverlays, in denen keine Vorschaubilder benötigt werden. Kennzeichen [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) Datenbankstatistik ## Abfrage per Kennzeichen [#lookup-by-registration] Fragen Sie ein Luftfahrzeug anhand seines Kennzeichens ab. v3.1 ergänzt das Luftfahrzeugobjekt um die Felder `manufacturer_and_model`, `airline_code`, `serial_number` und `is_private_operator`. ### Anfrage [#request] | Parameter | Typ | Erforderlich | Standard | Beschreibung | | -------------- | ------- | ------------ | -------- | --------------------------------------------------------------- | | `registration` | string | Ja (Pfad) | - | Kennzeichen, z. B. `G-STBC`, `N12345` (2–10 Zeichen) | | `photos` | boolean | Nein | `true` | Community-Fotos des Luftfahrzeugs einbeziehen, sofern verfügbar | ### Antwort [#response] ```json { "query": "G-STBC", "found": true, "aircraft": { "registration": "G-STBC", "icao24": "40621D", "icao_type": "B77W", "type_name": "BOEING 777-36NER", "manufacturer": "Boeing Company", "manufacturer_and_model": "Boeing Company BOEING 777-36NER", "owner_operator": "British Airways", "airline_code": null, "is_private_operator": false, "serial_number": "38287", "year_built": null, "photos": [ { "image": "https://image.airport-data.com/aircraft/001912010.jpg", "link": "https://airport-data.com/aircraft/photo/001912010", "photographer": "Roberto Cassar" } ] } } ``` | Feld | Typ | Erforderlich | Null? | Beschreibung | | ---------- | -------------- | ------------ | ------ | -------------------------------------------------------------------------------- | | `query` | string | **Ja** | Nie | Echo des gesuchten Kennzeichens | | `found` | boolean | **Ja** | Nie | Ob ein Treffer im Register existiert | | `aircraft` | object \| null | Nein | **Ja** | Luftfahrzeugdetails, wenn `found` `true` ist; `null`, wenn nichts gefunden wurde | #### Luftfahrzeugobjekt (`aircraft`) [#aircraft-object-aircraft] | Feld | Typ | Erforderlich | Null? | Beschreibung | | ------------------------ | --------------- | ------------ | ------ | ------------------------------------------------------------------------ | | `registration` | string \| null | Nein | **Ja** | Kennzeichen | | `icao24` | string \| null | Nein | **Ja** | ICAO-24-Bit-Transponderadresse in Hex (in der Praxis in Großbuchstaben) | | `icao_type` | string \| null | Nein | **Ja** | ICAO-Luftfahrzeugtypbezeichnung, z. B. `B77W` | | `type_name` | string \| null | Nein | **Ja** | Modellbezeichnung, z. B. `BOEING 777-36NER` | | `manufacturer` | string \| null | Nein | **Ja** | Name des Herstellers | | `manufacturer_and_model` | string \| null | Nein | **Ja** | Kombinierte Zeichenkette aus Hersteller + Modell | | `owner_operator` | string \| null | Nein | **Ja** | Eingetragener Halter oder Betreiber | | `airline_code` | string \| null | Nein | **Ja** | Airline-Code des Betreibers, sofern bekannt | | `is_private_operator` | boolean \| null | Nein | **Ja** | `true` bei privaten Betreibern | | `serial_number` | string \| null | Nein | **Ja** | Seriennummer des Herstellers | | `year_built` | string \| null | Nein | **Ja** | Baujahr | | `photos` | array | Nein | Nie | Vorhanden bei `photos=true`; kann `[]` sein, wenn keine Fotos existieren | #### Fotoeintrag (`aircraft.photos[]`) [#photo-item-aircraftphotos] | Feld | Typ | Erforderlich | Beschreibung | | -------------- | ------ | ------------ | -------------------------------------------- | | `image` | string | **Ja** | URL des Fotos in voller Größe | | `link` | string | **Ja** | URL der externen Fotoseite, sofern angegeben | | `photographer` | string | **Ja** | Fotografennachweis | ## Abfrage per ICAO24 [#lookup-by-icao24] Fragen Sie ein Luftfahrzeug anhand seiner hexadezimalen [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)-Transponderadresse ab — derselben Kennung, die per [ADS-B](https://www.faa.gov/air_traffic/technology/adsb) ausgestrahlt wird (z. B. `40621D`). Liefert dieselbe Struktur des `aircraft`-Objekts wie die Kennzeichenabfrage. ### Anfrage [#request-1] | Parameter | Typ | Erforderlich | Standard | Beschreibung | | --------- | ------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `icao24` | string | Ja (Pfad) | - | Sechsstellige ICAO-24-Bit-Hex-Adresse (ohne Beachtung der Groß-/Kleinschreibung), z. B. `40621D`. Ergänzen Sie führende Nullen, wenn Ihre ADS-B-Quelle sie weglässt | | `photos` | boolean | Nein | `true` | Community-Fotos des Luftfahrzeugs einbeziehen, sofern verfügbar | ### Antwort [#response-1] Gleiche Antwortstruktur wie bei der [Kennzeichenabfrage](#lookup-by-registration). `query` enthält das Echo der [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)-Adresse. ## Datenbankstatistik [#database-statistics] Liefert Datensatzanzahlen und Ladestatus des In-Memory-Luftfahrzeugregisters. Keine Parameter erforderlich — nützlich für Health Checks beim Start und für Monitoring-Dashboards. ### Anfrage [#request-2] Keine Query- oder Pfadparameter. ### Antwort [#response-2] ```json { "loaded": true, "total_icao_entries": 612678, "total_registration_entries": 608905, "source_url": "https://api.skylinkapi.com/internal/aircraft.json" } ``` | Feld | Typ | Erforderlich | Beschreibung | | ---------------------------- | ------- | ------------ | -------------------------------------------------------------- | | `loaded` | boolean | **Ja** | Ob das Register vollständig geladen ist | | `total_icao_entries` | integer | **Ja** | Nach ICAO24 indizierte Datensätze | | `total_registration_entries` | integer | **Ja** | Nach Kennzeichen indizierte Datensätze | | `source_url` | string | **Ja** | Von der API zurückgegebene, opake Referenz-URL des Datensatzes | ## Client-Typen [#client-types] ## Integration [#integration] Lösen Sie ein Kennzeichen in eine kompakte Luftfahrzeugkarte für Flugverfolgung oder Flottenanzeigen auf. Das folgende Beispiel speichert erfolgreiche Abfragen 24 Stunden lang im Cache, da sich Registermetadaten selten ändern. Jede Anfrage verwendet explizite Timeouts (10 s Verbindungsaufbau / 15 s Lesen), damit ein langsamer Upstream-Aufruf Ihren Worker nicht blockieren kann. Der Helper normalisiert die Antwort in ein UI-freundliches Modell und behandelt `found: false`, ohne es als HTTP-Fehler zu werten. ### Hinweise zur Implementierung [#implementation-notes] **Foto-Schalter.** Der Standardwert `photos=true` ist für Galerien praktisch, aber langsamer. Übergeben Sie `photos=false` in Listenansichten und Batch-Anreicherungsjobs. **Verkettung mit Leistungsdaten.** Wenn `icao_type` vorhanden ist, rufen Sie [Flugzeugleistung](/docs/v31/aircraft-performance) für Reisegeschwindigkeit, Reichweite und Wirbelschleppenkategorie auf. **[ADS-B](https://www.faa.gov/air_traffic/technology/adsb)-Anreicherung.** Bevorzugen Sie für Live-Tracks die [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)-Abfrage, nachdem Sie Hex-Codes von [ADS-B](/docs/v31/adsb) erhalten haben. ## Fehlerantworten [#error-responses] Informationen zu plattformweiten Fehlern (Authentifizierung, Rate Limits, Serverfehler) finden Sie unter [Fehlerbehandlung](/docs/errors). Endpoint-spezifisches Verhalten: ### 200 — Luftfahrzeug nicht gefunden (Kennzeichen / ICAO24) [#200--aircraft-not-found-registration--icao24] ```json { "query": "ZZZZNOT", "found": false, "aircraft": null } ``` Behandeln Sie `found: false` als normales leeres Ergebnis — wiederholen Sie die Anfrage nicht. ### 422 — ungültiges Kennzeichen oder ungültige ICAO24 [#422--invalid-registration-or-icao24] ```json { "detail": [ { "type": "string_too_short", "loc": ["path", "registration"], "msg": "String should have at least 2 characters" } ] } ``` Tritt auf, wenn der Pfadparameter zu kurz ist oder die Validierung nicht besteht. *** Siehe auch: [Flugzeugleistung](/docs/v31/aircraft-performance) · [ADS-B](/docs/v31/adsb) · [Historische ADS-B-Positionen](/docs/v31/historical-adsb-positions)