> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IP-Geolokalisierungs-API

> Die Cleariflow IP-Geolokalisierungs-API ist eine schnelle, effiziente und moderne RESTful JSON-API, die den Standort und weitere Details von IP-Adressen in über 190 Ländern ermittelt.

Die API arbeitet mit bemerkenswerter Einfachheit: Übergeben Sie Ihren API-Schlüssel zusammen mit einer IP-Adresse, und Sie erhalten umfassende Standortdaten einschließlich Postleitzahlen, Städtenamen, Regionsinformationen, Länderdetails und präzisen Breiten-/Längenkoordinaten.

## Erste Schritte

### REST-Architektur

Wie alle Cleariflow-APIs folgt die IP-Geolokalisierungs-API REST-Prinzipien. Sie verwendet vorhersehbare, ressourcenorientierte URLs und HTTP-Statuscodes zur Fehleranzeige.

### HTTPS-Sicherheit

Alle Kommunikation mit der IP-Geolokalisierungs-API muss mit TLS 1.2 oder höher gesichert sein.

### API-Versionierung

Alle Cleariflow-APIs sind versioniert. Die IP-Geolokalisierungs-API befindet sich derzeit in Version 1.

### Authentifizierung mit API-Schlüssel

Ihr API-Schlüssel ist Ihre eindeutige Authentifizierungsberechtigung für den Zugriff auf die Cleariflow IP-Geolokalisierungs-API. Beachten Sie, dass jede Cleariflow-API einen eigenen API-Schlüssel erfordert — Sie benötigen also separate Schlüssel für IP-Geolokalisierung und E-Mail-Validierung. Zur Authentifizierung hängen Sie Ihren API-Schlüssel an die Basis-URL an.

### Basis-URL

```
https://ipgeolocation.cleariflow.com/v1/
```

### Geolokalisierungs-Endpunkt

Die Cleariflow IP-Geolokalisierungs-API benötigt nur Ihren eindeutigen API-Schlüssel und erkennt die IP-Adresse des anfragenden Clients automatisch. Alternativ können Sie den Parameter `ip_address` übergeben, um eine bestimmte IP zu analysieren:

```
https://ipgeolocation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 94.198.41.118 (optional)
```

Dies ist eine erfolgreiche Anfrage — die IP-Adresse und zugehörige Details werden unten zurückgegeben:

<ResponseExample>
  ```json theme={"system"}
  {
      "ip_address": "80.255.13.30",
      "city": null,
      "city_geoname_id": null,
      "region": null,
      "region_iso_code": null,
      "region_geoname_id": null,
      "postal_code": null,
      "country": "Germany",
      "country_code": "DE",
      "country_geoname_id": 2921044,
      "country_is_eu": true,
      "continent": "Europe",
      "continent_code": "EU",
      "continent_geoname_id": 6255148,
      "longitude": 9.491,
      "latitude": 51.2993,
      "security": {
          "is_vpn": true,
          "is_proxy": false,
          "vpn_provider": "NordVPN"
      },
      "timezone": {
          "name": "Europe/Berlin",
          "abbreviation": "CEST",
          "gmt_offset": 2,
          "current_time": "21:21:22",
          "is_dst": true
      },
      "flag": {
          "emoji": "🇩🇪",
          "unicode": "U+1F1E9 U+1F1EA",
          "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
          "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
      },
      "currency": {
          "currency_name": "Euros",
          "currency_code": "EUR"
      },
      "connection": {
          "autonomous_system_number": 201011,
          "autonomous_system_organization": "Core-Backbone GmbH",
          "connection_type": null,
          "isp_name": null,
          "organization_name": null
      }
  }
  ```
</ResponseExample>

### Anfrageparameter

<ParamField query="api_key" type="String" required>
  Ihr eindeutiger API-Schlüssel. Beachten Sie, dass jeder Nutzer für jede Cleariflow-API eigene API-Schlüssel hat — Ihr IP-Geolokalisierungs-API-Schlüssel funktioniert z. B. nicht für die E-Mail-Validierungs-API.
</ParamField>

<ParamField query="ip_address" type="String">
  Die zu geolokalisierende IP-Adresse. IPv4- und IPv6-Adressen werden unterstützt. Bleibt der Parameter leer, geolokalisiert der Dienst die IP-Adresse, von der die Anfrage stammt.
</ParamField>

<ParamField query="fields" type="String">
  Kommagetrennte Liste der zurückzugebenden **Top-Level**-Schlüssel (z. B. `?fields=country,security`). Für VPN-/Proxy-Flags `security` verwenden — das gesamte Objekt wird zurückgegeben (`is_vpn`, `is_proxy` und `vpn_provider` falls vorhanden). Verschachtelte Schlüssel wie allein `is_vpn` werden nicht unterstützt.
</ParamField>

### Antwortparameter

Die API-Antwort wird in einem universellen und leichtgewichtigen [JSON-Format](https://www.json.org/json-en.html) zurückgegeben.

<ResponseField name="ip_address" type="String">
  Die zur Geolokalisierung übermittelte IP-Adresse.
</ResponseField>

<ResponseField name="city" type="String">
  Name der Stadt.
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  Geoname-ID der Stadt.
</ResponseField>

<ResponseField name="region" type="String">
  Bundesland oder Provinz, in der die Stadt liegt.
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  ISO-3166-2-Code des Bundeslands oder der Provinz.
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  Geoname-ID des Bundeslands oder der Provinz.
</ResponseField>

<ResponseField name="postal_code" type="String">
  Postleitzahl.
</ResponseField>

<ResponseField name="country" type="String">
  Name des Landes.
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  ISO-3166-1-alpha-2-Code des Landes.
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  Geoname-ID des Landes.
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  `true`, wenn das Land in der EU liegt, sonst `false`.
</ResponseField>

<ResponseField name="continent" type="String">
  Name des Kontinents.
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  Zweistelliger Kontinentcode: AF, AS, EU, NA, OC, SA, AN.
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  Geoname-ID des Kontinents.
</ResponseField>

<ResponseField name="longitude" type="Float">
  Längengrad als Dezimalzahl.
</ResponseField>

<ResponseField name="latitude" type="Float">
  Breitengrad als Dezimalzahl.
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  `true`, wenn die IP mit der enumerierten VPN-Exit-Node-Datenbank (IP-to-VPN MMDB) übereinstimmt.
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  `true`, wenn die IP mit der Proxy-Datenbank (IP-to-VPN MMDB) übereinstimmt.
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  VPN-Dienstname aus der MMDB (z. B. `NordVPN`). Wird weggelassen, wenn `is_vpn` `false` ist.
</ResponseField>

<ResponseField name="timezone.name" type="String">
  Zeitzonenname aus der IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  Zeitzonenabkürzung, ebenfalls aus der IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  Zeitzonenversatz zur Greenwich Mean Time (GMT).
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  Aktuelle Uhrzeit in der lokalen Zeitzone.
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  `true`, wenn der Standort derzeit Sommerzeit (DST) hat.
</ResponseField>

<ResponseField name="flag.svg" type="String">
  Link zu einer gehosteten Version der Landesflagge im SVG-Format.
</ResponseField>

<ResponseField name="flag.png" type="String">
  Link zu einer gehosteten Version der Landesflagge im PNG-Format.
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  Landesflagge als Emoji.
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Landesflagge in Unicode.
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  Name der Währung.
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  Währungscode im ISO-4217-Format.
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  Abgeleitet aus dem ASN-Organisationsnamen (z. B. Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN und Proxy werden in `security` gemeldet, nicht hier.
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  Autonomous-System-Nummer.
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  Name der Autonomous-System-Organisation.
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  Name des Internet Service Provider (ISP).
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  Name der Organisation.
</ResponseField>

### Antwortfelder einschränken

Sie können festlegen, nur bestimmte Felder aus der JSON-Antwort zu erhalten. Fügen Sie dazu einen `fields`-Wert in den Abfrageparametern mit einer kommagetrennten Liste der gewünschten Top-Level-Schlüssel hinzu.

Eine Anfrage, die nur Land und Stadt einer IP zurückgeben soll, sieht z. B. so aus:

```
https://ipgeolocation.cleariflow.com/v1/
    ? api_key = YOUR_API_KEY
    & ip_address = 94.198.41.122
    & fields = country,city
```

Die Antwort sieht so aus:

```json theme={"system"}
{
    "city": "Vienna",
    "country": "Austria"
}
```

## Anwendungsfälle

### Geolokalisierung eines Website-Besuchers

Um die Geolokalisierung einer IP-Adresse anzufordern, fügen Sie einfach Ihren eindeutigen API-Schlüssel in die Vorlage unten ein.

Beachten Sie, dass Sie die IP des Besuchers nicht kennen müssen, um die Anfrage zu stellen.

```javascript theme={"system"}
$.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
   console.log(data.ip_address);
   console.log(data.country);
})
```

Das ist alles, was Sie benötigen, um Geolokalisierung und weitere Daten eines Besuchers zu erhalten! Es gibt nur einen erforderlichen Parameter: Ihren eindeutigen API-Schlüssel.

## Antwort- und Fehlercodes

Schlägt eine Anfrage fehl, wird ebenfalls ein Fehler im JSON-Format zurückgegeben. Die Fehler enthalten einen Fehlercode und eine Beschreibung — Details finden Sie unten.

| Code | Typ                   | Beschreibung                                                                                                    |
| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Alles funktionierte wie erwartet.                                                                               |
| 204  | OK                    | Für die übermittelte IP liegen keine Standortdaten vor.                                                         |
| 400  | Bad request           | Fehlerhafte Anfrage.                                                                                            |
| 401  | Unauthorized          | Die Anfrage war nicht zulässig — in der Regel fehlt der API-Schlüssel oder er ist ungültig.                     |
| 422  | Quota reached         | Die Anfrage wurde abgebrochen, da nicht genügend API-Guthaben vorhanden ist (kostenlose Tarife).                |
| 429  | Too many requests     | Das Anfragenlimit pro Sekunde wurde erreicht. Bei kostenlosen Tarifen gilt ein Limit von 1 Anfrage pro Sekunde. |
| 500  | Internal server error | Die Anfrage konnte aufgrund eines Serverfehlers nicht abgeschlossen werden.                                     |
| 503  | Service unavailable   | Der Server war nicht verfügbar.                                                                                 |

## Ländercodes

Nachfolgend eine Liste der zweistelligen ISO-3166-Alpha-2-Ländercodes in der Antwort. Diese Liste als [CSV](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing) anzeigen.

| Ländername                       | Ländercode |
| -------------------------------- | ---------- |
| Afghanistan                      | AF         |
| Albania                          | AL         |
| Algeria                          | DZ         |
| American Samoa                   | AS         |
| Andorra                          | AD         |
| Angola                           | AO         |
| Anguilla                         | AI         |
| Antigua and Barbuda              | AG         |
| Argentina                        | AR         |
| Armenia                          | AM         |
| Aruba                            | AW         |
| Australia                        | AU         |
| Austria                          | AT         |
| Azerbaijan                       | AZ         |
| Bahrain                          | BH         |
| Bangladesh                       | BD         |
| Barbados                         | BB         |
| Belarus                          | BY         |
| Belgium                          | BE         |
| Belize                           | BZ         |
| Benin                            | BJ         |
| Bermuda                          | BM         |
| Bhutan                           | BT         |
| Bolivia                          | BO         |
| Bosnia and Herzegovina           | BA         |
| Botswana                         | BW         |
| Brazil                           | BR         |
| British Virgin Islands           | VG         |
| Brunei                           | BN         |
| Bulgaria                         | BG         |
| Burkina Faso                     | BF         |
| Burundi                          | BI         |
| Cabo Verde                       | CV         |
| Cambodia                         | KH         |
| Cameroon                         | CM         |
| Canada                           | CA         |
| Cayman Islands                   | KY         |
| Central African Republic         | CF         |
| Chad                             | TD         |
| Chile                            | CL         |
| China                            | CN         |
| Colombia                         | CO         |
| Comoros                          | KM         |
| Congo                            | CG         |
| Congo Democratic Republic        | CD         |
| Cook Islands                     | CK         |
| Costa Rica                       | CR         |
| Cote d'Ivoire                    | CI         |
| Croatia                          | HR         |
| Cuba                             | CU         |
| Curaçao                          | CW         |
| Cyprus                           | CY         |
| Czechia                          | CZ         |
| Denmark                          | DK         |
| Djibouti                         | DJ         |
| Dominica                         | DM         |
| Dominican Republic               | DO         |
| East Timor                       | TL         |
| Ecuador                          | EC         |
| Egypt                            | EG         |
| El Salvador                      | SV         |
| Equatorial Guinea                | GQ         |
| Eritrea                          | ER         |
| Estonia                          | EE         |
| eSwatini                         | SZ         |
| Ethiopia                         | ET         |
| Falkland Islands                 | FK         |
| Faroe Islands                    | FO         |
| Fiji                             | FJ         |
| Finland                          | FI         |
| France                           | FR         |
| French Guiana                    | GF         |
| French Polynesia                 | PF         |
| Gabon                            | GA         |
| Gambia                           | GM         |
| Georgia                          | GE         |
| Germany                          | DE         |
| Ghana                            | GH         |
| Gibraltar                        | GI         |
| Greece                           | GR         |
| Greenland                        | GL         |
| Grenada                          | GD         |
| Guadeloupe                       | GP         |
| Guam                             | GU         |
| Guatemala                        | GT         |
| Guernsey                         | GG         |
| Guinea                           | GN         |
| Guinea-Bissau                    | GW         |
| Guyana                           | GY         |
| Haiti                            | HT         |
| Honduras                         | HN         |
| Hong Kong                        | HK         |
| Hungary                          | HU         |
| Iceland                          | IS         |
| India                            | IN         |
| Indonesia                        | ID         |
| Iran                             | IR         |
| Iraq                             | IQ         |
| Ireland                          | IE         |
| Isle of Man                      | IM         |
| Israel                           | IL         |
| Italy                            | IT         |
| Jamaica                          | JM         |
| Japan                            | JP         |
| Jersey                           | JE         |
| Jordan                           | JO         |
| Kazakhstan                       | KZ         |
| Kenya                            | KE         |
| Kiribati                         | KI         |
| Kosovo                           | XK         |
| Kuwait                           | KW         |
| Kyrgyzstan                       | KG         |
| Laos                             | LA         |
| Latvia                           | LV         |
| Lebanon                          | LB         |
| Lesotho                          | LS         |
| Liberia                          | LR         |
| Libya                            | LY         |
| Liechtenstein                    | LI         |
| Lithuania                        | LT         |
| Luxembourg                       | LU         |
| Macau                            | MO         |
| Madagascar                       | MG         |
| Malawi                           | MW         |
| Malaysia                         | MY         |
| Maldives                         | MV         |
| Mali                             | ML         |
| Malta                            | MT         |
| Marshall Islands                 | MH         |
| Martinique                       | MQ         |
| Mauritania                       | MR         |
| Mauritius                        | MU         |
| Mayotte                          | YT         |
| Mexico                           | MX         |
| Micronesia                       | FM         |
| Moldova                          | MD         |
| Monaco                           | MC         |
| Mongolia                         | MN         |
| Montenegro                       | ME         |
| Montserrat                       | MS         |
| Morocco                          | MA         |
| Mozambique                       | MZ         |
| Myanmar                          | MM         |
| Namibia                          | NA         |
| Nauru                            | NR         |
| Nepal                            | NP         |
| Netherlands                      | NL         |
| New Caledonia                    | NC         |
| New Zealand                      | NZ         |
| Nicaragua                        | NI         |
| Niger                            | NE         |
| Nigeria                          | NG         |
| North Korea                      | KP         |
| North Macedonia                  | MK         |
| Northern Mariana Islands         | MP         |
| Norway                           | NO         |
| Oman                             | OM         |
| Pakistan                         | PK         |
| Palau                            | PW         |
| Panama                           | PA         |
| Papua New Guinea                 | PG         |
| Paraguay                         | PY         |
| Peru                             | PE         |
| Philippines                      | PH         |
| Poland                           | PL         |
| Portugal                         | PT         |
| Puerto Rico                      | PR         |
| Qatar                            | QA         |
| Reunion                          | RE         |
| Romania                          | RO         |
| Russia                           | RU         |
| Rwanda                           | RW         |
| Saint Helena                     | SH         |
| Saint Kitts and Nevis            | KN         |
| Saint Lucia                      | LC         |
| Saint Martin                     | MF         |
| Saint Pierre and Miquelon        | PM         |
| Saint Vincent and the Grenadines | VC         |
| Samoa                            | WS         |
| San Marino                       | SM         |
| Sao Tome and Principe            | ST         |
| Saudi Arabia                     | SA         |
| Senegal                          | SN         |
| Serbia                           | RS         |
| Seychelles                       | SC         |
| Sierra Leone                     | SL         |
| Singapore                        | SG         |
| Sint Maarten                     | SX         |
| Slovakia                         | SK         |
| Slovenia                         | SI         |
| Solomon Islands                  | SB         |
| Somalia                          | SO         |
| South Africa                     | ZA         |
| South Korea                      | KR         |
| South Sudan                      | SS         |
| Spain                            | ES         |
| Sri Lanka                        | LK         |
| St. Barts                        | BL         |
| Sudan                            | SD         |
| Suriname                         | SR         |
| Sweden                           | SE         |
| Switzerland                      | CH         |
| Syria                            | SY         |
| Taiwan                           | TW         |
| Tajikistan                       | TJ         |
| Tanzania                         | TZ         |
| Thailand                         | TH         |
| The Bahamas                      | BS         |
| Togo                             | TG         |
| Tonga                            | TO         |
| Trinidad and Tobago              | TT         |
| Tunisia                          | TN         |
| Turkey                           | TR         |
| Turkmenistan                     | TM         |
| Turks and Caicos Islands         | TC         |
| Tuvalu                           | TV         |
| Uganda                           | UG         |
| Ukraine                          | UA         |
| United Arab Emirates             | AE         |
| United Kingdom                   | GB         |
| United States                    | US         |
| Uruguay                          | UY         |
| US Virgin Islands                | VI         |
| Uzbekistan                       | UZ         |
| Vanuatu                          | VU         |
| Vatican City (Holy See)          | VA         |
| Venezuela                        | VE         |
| Vietnam                          | VN         |
| Wallis and Futuna                | WF         |
| Yemen                            | YE         |
| Zambia                           | ZM         |
| Zimbabwe                         | ZW         |

## Weitere Hinweise

Wichtiger Hinweis zur Abrechnung: Jede verarbeitete IP-Adresse verbraucht ein Guthaben. Die Abrechnung erfolgt pro Anfrage, unabhängig vom Erfolg der Antwort. Selbst eine ungültige IP-Adresse wie „fda3346ds" zieht ein Guthaben von Ihrem Konto ab.