API-Referenz zur Besucher-Geolokalisierung

GET/v1/geo

Liefert die verfügbaren Standort- und Anreicherungsdaten des verbundenen Clients zurück. Rufen Sie ihn aus dem Browser eines Besuchers auf, um die Verbindung dieses Besuchers zu beschreiben — eine Anfrage von Ihrem Anwendungsserver beschreibt stattdessen die Verbindung des Servers selbst.

Authentifizierung

Stellen Sie einen Origin-gebundenen veröffentlichbaren Schlüssel über den X-Api-Key-Header bereit, oder alternativ den key-Abfrageparameter. Die Zugriffskontrolle beruht auf der für den Schlüssel konfigurierten Liste erlaubter Origins, geprüft gegen den Origin/Referer-Header der Anfrage — nicht darauf, den Schlüssel geheim zu halten, da er dafür ausgelegt ist, im Browser-Quellcode zu erscheinen.

Antwortfelder

ip: Die IP-Adresse des verbundenen Clients.
country, region, regionCode, city, postalCode, continent: Ungefährer Standort, nullable, wenn die zugrunde liegenden Edge-Daten keinen auflösen.
latitude, longitude: Ungefähre Koordinaten für den aufgelösten Standort, keine Geräte- oder GPS-Position.
timezone: IANA-Zeitzonenname, oder null, wenn nicht verfügbar.
isEUCountry: Boolescher Wert; ein Standort-Indikator, keine rechtliche Feststellung.
asn, asOrganization: Das verbundene Netzwerk und sein Betreiber, sofern von den zugrunde liegenden Daten bereitgestellt; sonst null.
currency, callingCode: Regionaler Kontext, abgeleitet aus dem aufgelösten Land, oder null.
locale, holidays, compliance, tax, ageVerification: Optionale, abgeleitete Anreicherungsgruppen, jede unabhängig nullable. Keine davon ist eine rechtliche, steuerliche oder identitätsbezogene Feststellung.
hostname: Nur vorhanden, wenn über ?include=hostname angefordert; ein Reverse-DNS-Ergebnis, null bei Fehlschlag.
security: Wird auf Tarifen, die es nicht enthalten, vollständig weggelassen. Wenn vorhanden: isTor, isVpn, isDatacenter, isThreat, isSanctionedNetwork — listenbasierte Indikatoren. Die IPv6-Tor-Erkennung ist derzeit nicht implementiert; false bedeutet keine Übereinstimmung in den verfügbaren Daten, nicht das Fehlen eines Risikos.

Fehler

401: Fehlender oder ungültiger API-Schlüssel.
403: Der Origin/Referer der Anfrage steht nicht in der Liste der erlaubten Origins des Schlüssels. Für diese Antwort wird auch kein CORS-Header gesetzt, sodass der Browser sie unabhängig vom JSON-Text blockiert.
429: Ratenlimit für das aktuelle feste Ein-Minuten-Fenster überschritten.

Beispiel

Anfrage

curl https://api.watch-ip.com/v1/geo \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY"

Antwort — zur Veranschaulichung; Felder variieren je nach Tarif und verfügbaren Daten

{
  "ip": "203.0.113.1",
  "country": "US",
  "region": "Texas",
  "regionCode": "TX",
  "city": "Austin",
  "postalCode": "78701",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "continent": "NA",
  "timezone": "America/Chicago",
  "isEUCountry": false,
  "asn": 12345,
  "asOrganization": "Example ISP",
  "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" },
  "callingCode": "+1"
}

Limits

Unterliegt dem monatlichen Anfragelimit und der Ratenbegrenzung pro Minute Ihres Tarifs — siehe Preise. Jeder erfolgreiche Aufruf wird als ein geo-Nutzungsereignis erfasst.