Mit IP Geolocation findest du heraus, wo eine IP-Adresse oder Domain ungefähr verortet ist: Land, Region, Stadt, Koordinaten, Zeitzone und der Netzbetreiber dahinter. Typische Einsätze sind die Vorauswahl von Land und Sprache in einem Formular oder die grobe Herkunft von Bestellungen.
In allen Beispielen ersetzt du fd_DEIN_SCHLUESSEL durch deinen eigenen FlowData-Schlüssel. Wie du ihn anlegst, steht in FlowData-API-Schlüssel anlegen.
Eine IP-Adresse oder Domain abfragen
Hänge die IP-Adresse oder die Domain an den Pfad an. IPv4, IPv6 und Domainnamen funktionieren gleichermaßen.
curl "https://api.flowdata.one/v1/geolocation/8.8.8.8?lang=de" \
-H "Authorization: Bearer fd_DEIN_SCHLUESSEL"
Die Antwort sieht so aus:
{
"status": "success",
"continent": "Nordamerika",
"continentCode": "NA",
"country": "Vereinigte Staaten",
"countryCode": "US",
"region": "CA",
"regionName": "Kalifornien",
"city": "Mountain View",
"district": null,
"zip": "94043",
"lat": 37.4192,
"lon": -122.0574,
"timezone": "America/Los_Angeles",
"offset": -25200,
"currency": "USD",
"isp": "Google LLC",
"org": "Google LLC",
"as": "AS15169 Google LLC",
"asname": "Google LLC",
"reverse": null,
"mobile": null,
"proxy": null,
"hosting": null,
"query": "8.8.8.8"
}
Ohne IP im Pfad, also mit GET https://api.flowdata.one/v1/geolocation, bekommst du die Daten zu der IP-Adresse, von der deine Anfrage kommt. Warum das bei Aufrufen vom Server meist nicht das ist, was du willst, erklärt Warum zeigt IP Geolocation den Standort meines Servers statt den meines Besuchers?.
Jede Abfrage siehst du anschließend im Dashboard unter Bereiche › IP Geolocation, mit Kennzahlen, Verlauf der letzten 30 Tage und dem Protokoll der einzelnen Anfragen. Wie du es liest, steht in Statistik und Protokoll eines FlowData-Bereichs.
Die Felder im Überblick
- continent, continentCode: Kontinent als Name und als Kürzel.
- country, countryCode: Land als Name und als zweistelliger ISO-Code, zum Beispiel
DE. - region, regionName: Kürzel und Name des Bundeslands oder der Region.
- city, zip: Stadt und Postleitzahl. Beide können leer sein, wenn die Ortung nur das Land kennt.
- lat, lon: Breiten- und Längengrad. Achtung, der Längengrad heißt hier
lon, nichtlngwie in Maps. - timezone, offset: Zeitzone wie
Europe/Berlinund der aktuelle Abstand zu UTC in Sekunden.3600bedeutet also eine Stunde. - currency: Landeswährung als ISO-Code, zum Beispiel
EUR. - isp, org, asname: Name des Netzbetreibers. Alle drei enthalten denselben Wert.
- as: Netznummer mit Name, zum Beispiel
AS15169 Google LLC. - query: die abgefragte IP-Adresse. Hast du eine Domain abgefragt, steht hier die IP-Adresse, zu der sie aufgelöst wurde.
Die Felder district, reverse, mobile, proxy und hosting bleiben Teil der Antwort, damit bestehende Integrationen nicht brechen, sind aber immer null. Stütze deine Logik also nicht auf sie.
Sprache der Namen
Kontinent-, Länder-, Regions- und Städtenamen kommen standardmäßig auf Deutsch. Mit dem Parameter lang wählst du eine andere Sprache: de, en, es, pt-BR, fr, ja, zh-CN oder ru. Gibt es einen Namen nicht in der gewählten Sprache, kommt er auf Englisch.
Achte auf die genaue Schreibweise. Ein anderer Wert wird mit HTTP 400 abgelehnt:
{"status":"fail","message":"Invalid parameters: Der ausgewählte Wert für lang ist ungültig."}
Wenn etwas nicht klappt
Lässt sich eine Adresse nicht verorten, antwortet die API trotzdem mit HTTP 200. Prüfe deshalb immer das Feld status. Bei fail nennt message den Grund, und die Ortsfelder fehlen:
{"status":"fail","message":"private range","query":"192.168.1.20"}
| HTTP | status und message |
Bedeutung |
|---|---|---|
| 200 | fail, invalid query |
Weder eine gültige IP-Adresse noch eine Domain, die sich auflösen lässt. |
| 200 | fail, private range |
Private Adresse aus einem lokalen Netz. |
| 200 | fail, reserved range |
Reservierte Adresse, zum Beispiel 127.0.0.1. |
| 200 | fail, not found |
Die Adresse ist in den Ortungsdaten nicht bekannt. |
| 400 | fail, Invalid parameters: ... |
Der Wert von lang ist ungültig. |
| 500 | fail, Internal server error |
Unerwarteter Fehler. Versuch es nach einer kurzen Pause erneut. |
| 503 | fail, Geolocation database unavailable |
Die Ortung ist gerade nicht verfügbar. Versuch es nach einer kurzen Pause erneut. |
Fehler rund um Schlüssel und Guthaben erklärt Fehlermeldungen und Anfragelimits.
Was kostet eine Abfrage?
IP Geolocation wird je 1.000 erfolgreiche Abfragen berechnet. Nur Antworten mit status: success zählen, fail und alle Fehler sind kostenlos. Die Beträge stehen auf der Preisseite, die für dein Team gültigen Preise im Dashboard unter Abrechnung. Reicht dein Guthaben nicht, antwortet die API mit HTTP 402. Mehr dazu in FlowData-Preise verstehen.
Gut zu wissen
- Die Ortung per IP ist eine Schätzung. Bei Mobilfunk und VPN liegt der angezeigte Ort oft weit vom echten Standort entfernt.
- Viele Adressen auf einmal fragst du per Batch ab, siehe Wie frage ich bis zu 100 IP-Adressen auf einmal ab?.
- Die vollständige Referenz steht in der API-Dokumentation.