Zum Hauptinhalt springen
GET
IP-Geolokalisierungs-API
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

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:
Dies ist eine erfolgreiche Anfrage — die IP-Adresse und zugehörige Details werden unten zurückgegeben:

Anfrageparameter

api_key
String
erforderlich
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.
ip_address
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.
fields
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.

Antwortparameter

Die API-Antwort wird in einem universellen und leichtgewichtigen JSON-Format zurückgegeben.
ip_address
String
Die zur Geolokalisierung übermittelte IP-Adresse.
city
String
Name der Stadt.
city_geoname_id
String
Geoname-ID der Stadt.
region
String
Bundesland oder Provinz, in der die Stadt liegt.
region_iso_code
Char[2]
ISO-3166-2-Code des Bundeslands oder der Provinz.
region_geoname_id
String
Geoname-ID des Bundeslands oder der Provinz.
postal_code
String
Postleitzahl.
country
String
Name des Landes.
country_code
Char[2]
ISO-3166-1-alpha-2-Code des Landes.
country_geoname_id
String
Geoname-ID des Landes.
country_is_eu
Boolean
true, wenn das Land in der EU liegt, sonst false.
continent
String
Name des Kontinents.
continent_code
Char[2]
Zweistelliger Kontinentcode: AF, AS, EU, NA, OC, SA, AN.
continent_geoname_id
String
Geoname-ID des Kontinents.
longitude
Float
Längengrad als Dezimalzahl.
latitude
Float
Breitengrad als Dezimalzahl.
security.is_vpn
Boolean
true, wenn die IP mit der enumerierten VPN-Exit-Node-Datenbank (IP-to-VPN MMDB) übereinstimmt.
security.is_proxy
Boolean
true, wenn die IP mit der Proxy-Datenbank (IP-to-VPN MMDB) übereinstimmt.
security.vpn_provider
String
VPN-Dienstname aus der MMDB (z. B. NordVPN). Wird weggelassen, wenn is_vpn false ist.
timezone.name
String
Zeitzonenname aus der IANA Time Zone Database.
timezone.abbreviation
String
Zeitzonenabkürzung, ebenfalls aus der IANA Time Zone Database.
timezone.gmt_offset
String
Zeitzonenversatz zur Greenwich Mean Time (GMT).
timezone.current_time
String
Aktuelle Uhrzeit in der lokalen Zeitzone.
timezone.is_dst
Boolean
true, wenn der Standort derzeit Sommerzeit (DST) hat.
flag.svg
String
Link zu einer gehosteten Version der Landesflagge im SVG-Format.
flag.png
String
Link zu einer gehosteten Version der Landesflagge im PNG-Format.
flag.emoji
String
Landesflagge als Emoji.
flag.unicode
String
Landesflagge in Unicode.
currency.currency_name
String
Name der Währung.
currency.currency_code
String
Währungscode im ISO-4217-Format.
connection.connection_type
String
Abgeleitet aus dem ASN-Organisationsnamen (z. B. Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN und Proxy werden in security gemeldet, nicht hier.
connection.autonomous_system_number
Uint32
Autonomous-System-Nummer.
connection.autonomous_system_organization
String
Name der Autonomous-System-Organisation.
connection.isp_name
String
Name des Internet Service Provider (ISP).
connection.organization_name
String
Name der Organisation.

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:
Die Antwort sieht so aus:

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.
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.

Ländercodes

Nachfolgend eine Liste der zweistelligen ISO-3166-Alpha-2-Ländercodes in der Antwort. Diese Liste als CSV anzeigen.

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.