# Flughafensuche Flughäfen nach Text, Koordinaten oder IP suchen – nach Relevanz sortierte Ergebnisse für Autovervollständigung und Suche nach dem nächsten Flughafen. Drei Suchmodi helfen Benutzern, einen Flughafen zu finden, bevor Sie vollständige Datensätze über [Flughäfen](/docs/v31/airports) abrufen: Typeahead nach Name oder Code, nächstgelegene Flughäfen zu einer Kartenmarkierung oder GPS-Position und nächstgelegene Flughäfen, ermittelt aus der IP eines Besuchers. Alle drei liefern dasselbe Kernschema für Flughafeneinträge; die Standort- und IP-Modi ergänzen `distance_km`. | Endpoint | Einsatzzweck | | ------------------------------- | -------------------------------------------------------------------------------------- | | `GET /airports/search/text` | Autovervollständigung — der Benutzer tippt einen Namen, eine Stadt oder einen Teilcode | | `GET /airports/search/location` | Kartenmarkierung oder GPS-Koordinaten — Flughäfen innerhalb eines Radius | | `GET /airports/search/ip` | „Flughäfen in meiner Nähe“ ohne Berechtigung zur Standortbestimmung im Browser | Text Standort IP ## Suche nach Text [#search-by-text] Freitextsuche über ICAO-Codes, IATA-Codes, Flughafennamen und Städte. Die Ergebnisse werden nach `relevance_score` sortiert — exakte Code-Treffer erhalten die höchste Bewertung. ### Anfrage [#request] | Parameter | Typ | Erforderlich | Standard | Beschreibung | | --------- | ------- | ------------ | -------- | ------------------------------------------ | | `q` | string | Ja | - | Suchbegriff — mindestens **2** Zeichen | | `limit` | integer | Nein | `10` | Maximale Anzahl zurückgegebener Ergebnisse | ### Antwort [#response] ```json { "query": "jfk", "airports": [ { "id": 3622, "ident": "KJFK", "type": "large_airport", "name": "John F. Kennedy International Airport", "latitude_deg": 40.639447, "longitude_deg": -73.779317, "municipality": "New York", "iso_country": "US", "iata_code": "JFK", "relevance_score": 100 } ], "airports_found": 1 } ``` | Feld | Typ | Erforderlich | Beschreibung | | ---------------- | ------- | ------------ | ------------------------------------------------ | | `query` | string | **Ja** | Echo des Suchbegriffs | | `airports` | array | **Ja** | Nach Relevanz sortierte Treffer (kann leer sein) | | `airports_found` | integer | **Ja** | Anzahl der Einträge in `airports` | #### Flughafeneintrag (`airports[]`) [#airport-item-airports] | Feld | Typ | Erforderlich | Null? | Beschreibung | | ----------------- | -------------- | ------------ | ------ | ------------------------------------------------------------------------------------------- | | `ident` | string | **Ja** | Nie | Primäre Kennung (meist ICAO) | | `name` | string | **Ja** | Nie | Name des Flughafens | | `type` | string | **Ja** | Nie | Flughafenklasse (gleiche Werte wie bei [Flughäfen](/docs/v31/airports#airport-type-values)) | | `latitude_deg` | number | **Ja** | Nie | Breitengrad nach WGS-84 | | `longitude_deg` | number | **Ja** | Nie | Längengrad nach WGS-84 | | `municipality` | string \| null | Nein | **Ja** | Bediente Stadt | | `iso_country` | string \| null | Nein | **Ja** | ISO-Ländercode | | `iata_code` | string \| null | Nein | **Ja** | IATA-Code, sofern vergeben | | `relevance_score` | integer | **Ja** | Nie | Höher = bessere Übereinstimmung (`100` = exakter Code-Treffer) | ## Suche nach Standort [#search-by-location] Liefert Flughäfen innerhalb eines Radius um eine Koordinate, sortiert nach Entfernung (nächster zuerst). Jedes Ergebnis enthält `distance_km`. ### Anfrage [#request-1] | Parameter | Typ | Erforderlich | Standard | Beschreibung | | --------- | ------ | ------------ | ---------- | ---------------------------------------------------- | | `lat` | number | Ja | - | Breitengrad (`-90` bis `90`, Dezimalgrad WGS-84) | | `lon` | number | Ja | - | Längengrad (`-180` bis `180`, Dezimalgrad WGS-84) | | `radius` | number | Nein | `50` | Suchradius in **Kilometern** (muss > 0 sein) | | `type` | string | Nein | alle Typen | Nach Flughafen-`type` filtern, z. B. `large_airport` | Liefert bis zu **50** Flughäfen. In dicht besiedelten Stadtgebieten können Hubschrauberlandeplätze und geschlossene Flugplätze erscheinen, sofern Sie nicht `type` übergeben. ### Antwort [#response-1] ```json { "search_location": { "latitude": 40.64, "longitude": -73.78, "radius_km": 50.0, "type_filter": null }, "airports": [ { "ident": "KJFK", "name": "John F. Kennedy International Airport", "type": "large_airport", "latitude_deg": 40.639447, "longitude_deg": -73.779317, "municipality": "New York", "iso_country": "US", "iata_code": "JFK", "distance_km": 0.08 } ], "airports_found": 42 } ``` | Feld | Typ | Erforderlich | Beschreibung | | ----------------- | ------- | ------------ | ------------------------------------------ | | `search_location` | object | **Ja** | Echo der Abfrageparameter | | `airports` | array | **Ja** | Nach Entfernung sortierte Treffer | | `airports_found` | integer | **Ja** | Anzahl der zurückgegebenen Einträge (≤ 50) | #### Flughafeneintrag (`airports[]`) [#airport-item-airports-1] Dieselben Kernfelder wie bei der Textsuche, zusätzlich `distance_km` ([Großkreisentfernung](https://en.wikipedia.org/wiki/Great-circle_distance) vom Abfragepunkt in Kilometern). ## Suche nach IP [#search-by-ip] Ermittelt den Standort einer IP-Adresse und liefert nahegelegene Flughäfen in derselben nach Entfernung sortierten Liste wie die [Standortsuche](#search-by-location). ### Anfrage [#request-2] | Parameter | Typ | Erforderlich | Standard | Beschreibung | | --------- | ------ | ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `ip` | string | Nein | IP des Aufrufers | IPv4/IPv6-Adresse für die Standortbestimmung. Weglassen, um die IP des Anfragenden zu verwenden (RapidAPI leitet die Client-Adresse weiter) | | `radius` | number | Nein | `50` | Suchradius in Kilometern | Lassen Sie `ip` für serverseitiges „Flughäfen in meiner Nähe“ weg, wenn RapidAPI die IP des Endbenutzers erhält. Übergeben Sie die IP des Besuchers explizit, wenn Ihr Backend Anfragen weiterleitet. ### Antwort [#response-2] ```json { "ip_address": "203.0.113.10", "location": { "latitude": 40.7128, "longitude": -74.006, "city": "New York", "region": "New York", "country": "United States", "country_code": "US" }, "search_radius_km": 50.0, "airports": [ { "ident": "KJFK", "name": "John F. Kennedy International Airport", "distance_km": 20.5 } ], "airports_found": 38 } ``` | Feld | Typ | Erforderlich | Null? | Beschreibung | | ------------------ | -------------- | ------------ | ------ | -------------------------------------------------------------------------------- | | `ip_address` | string | **Ja** | Nie | IP, deren Standort bestimmt wurde | | `location` | object \| null | Nein | **Ja** | Ermittelter Standort; `null`, wenn die Abfrage fehlschlägt | | `search_radius_km` | number | **Ja** | Nie | Angewendeter Suchradius | | `airports` | array | **Ja** | Nie | Nach Entfernung sortierte Flughäfen (gleiche Struktur wie bei der Standortsuche) | | `airports_found` | integer | **Ja** | Nie | Anzahl der zurückgegebenen Einträge | | `error` | string \| null | Nein | **Ja** | Fehlermeldung, wenn die Standortbestimmung fehlschlägt | **Hinweis zur Genauigkeit.** IP-Adressen von Privatanschlüssen werden auf Stadtebene aufgelöst; VPN- und Rechenzentrums-IPs können ungenau sein. Zeigen Sie die ermittelte Stadt an und lassen Sie den Benutzer sie überschreiben. ## Client-Typen [#client-types] ## Integration [#integration] Betreiben Sie ein Autovervollständigungsfeld für Flughäfen mit nach Relevanz sortierten Ergebnissen der Textsuche. Das folgende Beispiel cacht Antworten der Textsuche eine Stunde lang und verwendet Verbindungs-/Lese-Timeouts, damit die Eingabe in einem Suchfeld Ihre UI nicht blockieren kann. ### Hinweise zur Implementierung [#implementation-notes] **Benutzereingaben entprellen (Debounce).** Warten Sie nach dem letzten Tastendruck \~300 ms, bevor Sie die API aufrufen. Verlangen Sie mindestens 2 Zeichen, um 422-Validierungsfehler zu vermeiden. **Relevanz-Ranking.** `relevance_score: 100` kennzeichnet eine exakte ICAO-/IATA-Übereinstimmung — heften Sie diese oben an Autovervollständigungslisten an. **Flughafentypen filtern.** Filtern Sie für Airline-Apps nach dem Abruf auf `large_airport` / `medium_airport` oder übergeben Sie `type=large_airport` bei der Standortsuche. **Mit der vollständigen Abfrage verketten.** Rufen Sie nach der Auswahl [Flughäfen](/docs/v31/airports) mit `icao` auf, um Start- und Landebahnen sowie Frequenzen zu erhalten. **Datenschutz bei der IP-Suche.** Legen Sie die IP-Geolokalisierung in Ihrer Datenschutzerklärung offen. Bevorzugen Sie die Standortbestimmung im Browser + [Standortsuche](#search-by-location), wenn der Benutzer die Berechtigung erteilt. ## Fehlerantworten [#error-responses] Gemeinsame Validierungs- und Plattformfehler: [Fehlerbehandlung](/docs/errors). Endpoint-spezifisch: ### 422 - Suchbegriff zu kurz [#422---text-query-too-short] ```json { "detail": [ { "type": "string_too_short", "loc": ["query", "q"], "msg": "String should have at least 2 characters" } ] } ``` ### GeoIP-Abfrage fehlgeschlagen (IP-Suche) [#geoip-lookup-failed-ip-search] Wenn die IP-Geolokalisierung fehlschlägt, liefert die API HTTP `200` mit `location: null`, `airports: []` und einem befüllten `error`-String. Behandeln Sie dies als weichen Fehler — fordern Sie eine manuelle Eingabe an oder greifen Sie auf die Standortbestimmung im Browser zurück. ```json { "ip_address": "203.0.113.10", "location": null, "search_radius_km": 50.0, "airports": [], "airports_found": 0, "error": "Unable to geolocate IP address" } ``` *** Siehe auch: [Flughäfen](/docs/v31/airports) · [METAR](/docs/v31/weather-metar) · [Länder](/docs/v31/countries)