# Regionen

Referenzdaten zu Regionen nach ISO 3166-2 (Bundesstaaten/Provinzen) für Flughafenformulare und Validierung, mit Listen- und Code-Abfrage.



Regionale Untergliederungen nach [ISO 3166-2](https://www.iso.org/iso-3166-2-codes.html) (Bundesstaaten, Provinzen, Territorien). Der wichtigste Integrationsweg ist die Auflösung von `iso_region` aus [Flughäfen](/docs/v31/airports) in eine lesbare Bezeichnung — zum Beispiel `US-NY` → `New York`. Zwei Operationen: Regionen auflisten (gefiltert nach Land oder Kontinent) und eine einzelne Region per Code abrufen.

**Filtern Sie, wann immer möglich.** Eine ungefilterte Liste liefert weltweit ca. 3.900 Zeilen. Übergeben Sie in produktiven UIs `country` oder `continent`.

| Endpoint              | Einsatzzweck                                       |
| --------------------- | -------------------------------------------------- |
| `GET /regions`        | Regionsauswahl, gefiltert nach Land oder Kontinent |
| `GET /regions/{code}` | `iso_region` aus einem Flughafendatensatz auflösen |

<DocJumpNav>
  <DocJumpLink href="#list-regions" icon="solar:list-bold-duotone">
    Liste
  </DocJumpLink>

  <DocJumpLink href="#get-region-by-code" icon="solar:map-point-bold-duotone">
    Per Code
  </DocJumpLink>
</DocJumpNav>

## Regionen auflisten [#list-regions]

Liefert Regionen, optional gefiltert nach Land und/oder Kontinent.

### Anfrage [#request]

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

<DocApiPath method="GET" path="/regions" />

| Parameter   | Typ    | Erforderlich | Standard        | Beschreibung                                             |
| ----------- | ------ | ------------ | --------------- | -------------------------------------------------------- |
| `country`   | string | Nein         | alle Länder     | Ländercode nach ISO 3166-1 alpha-2, z. B. `US`           |
| `continent` | string | Nein         | alle Kontinente | Kontinentcode (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`) |

### Antwort [#response]

```json
{
  "regions": [
    {
      "id": 306110,
      "code": "US-NY",
      "local_code": "NY",
      "name": "New York",
      "continent": null,
      "iso_country": "US",
      "wikipedia_link": "https://en.wikipedia.org/wiki/New_York",
      "keywords": "Airports in New York"
    }
  ],
  "total": 1
}
```

| Feld      | Typ     | Erforderlich | Null? | Beschreibung                        |
| --------- | ------- | ------------ | ----- | ----------------------------------- |
| `regions` | array   | **Ja**       | Nie   | Passende Regionsdatensätze          |
| `total`   | integer | **Ja**       | Nie   | Anzahl der zurückgegebenen Regionen |

#### Regionseintrag (`regions[]`) [#region-item-regions]

| Feld             | Typ            | Erforderlich | Null?  | Beschreibung                           |
| ---------------- | -------------- | ------------ | ------ | -------------------------------------- |
| `id`             | integer        | **Ja**       | Nie    | Numerische Datensatzkennung            |
| `code`           | string         | **Ja**       | Nie    | ISO-3166-2-Regionscode, z. B. `US-NY`  |
| `local_code`     | string \| null | Nein         | **Ja** | Landesinterner Kurzcode (z. B. `NY`)   |
| `name`           | string         | **Ja**       | Nie    | Name der Region                        |
| `continent`      | string \| null | Nein         | **Ja** | Kontinentcode, sofern zugeordnet       |
| `iso_country`    | string         | **Ja**       | Nie    | Alpha-2-Code des übergeordneten Landes |
| `wikipedia_link` | string \| null | Nein         | **Ja** | Referenz-URL                           |
| `keywords`       | string \| null | Nein         | **Ja** | Freitext-Tags                          |

## Region per Code abrufen [#get-region-by-code]

Rufen Sie eine einzelne Region per [ISO 3166-2](https://www.iso.org/iso-3166-2-codes.html)-Code ab (z. B. `US-CA`, `GB-ENG`). Liefert `404`, wenn der Code nicht gefunden wird.

### Anfrage [#request-1]

<DocApiPath method="GET" path="/regions/{code}" />

| Parameter | Typ    | Erforderlich | Beschreibung                                 |
| --------- | ------ | ------------ | -------------------------------------------- |
| `code`    | string | Ja           | Pfadparameter mit dem ISO-3166-2-Regionscode |

### Antwort [#response-1]

```json
{
  "id": 306110,
  "code": "US-NY",
  "local_code": "NY",
  "name": "New York",
  "continent": null,
  "iso_country": "US",
  "wikipedia_link": "https://en.wikipedia.org/wiki/New_York",
  "keywords": "Airports in New York"
}
```

Gleiche Objektstruktur wie bei den Listeneinträgen. Listenfilter ohne Treffer liefern `regions: []` und `total: 0` — keinen Fehler.

## Client-Typen [#client-types]

<DocClientTypes id="v31/regions/reference-types" />

## Integration [#integration]

Rufen Sie Regionsreferenzdaten für ein ausgewähltes Land ab und bilden Sie sie auf Formularoptionen ab.

Das folgende Beispiel speichert Regionslisten 24 Stunden lang im Cache und verwendet explizite Timeouts, damit Onboarding-Formulare reaktionsschnell bleiben.

<DocExample id="v31/regions/list-fetch" />

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

**Land zuerst (UX).** Fragen Sie nach Möglichkeit per `country` ab — vermeiden Sie es, die vollständige globale Liste an Browser zu senden.

**Verknüpfung mit Flughäfen.** Verknüpfen Sie `airport.iso_region` aus [Flughäfen](/docs/v31/airports) direkt mit `regions.code`.

**Codeformat.** Erzwingen Sie nach Möglichkeit schon vor der Anfrage das Format `XX-YYY`, um vermeidbare 404-Fehler zu reduzieren.

## Fehlerantworten [#error-responses]

Allgemeine Fehler: [Fehlerbehandlung](/docs/errors). Endpoint-spezifisch:

### 404 - Region nicht gefunden [#404---region-not-found]

```json
{
  "detail": "Region 'ZZ-XX' not found"
}
```

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/regions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/regions/{code}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />

***

Siehe auch: [Länder](/docs/v31/countries) · [Flughäfen](/docs/v31/airports) · [Flughafensuche](/docs/v31/airport-search)