Watch-IP

Batch-IP-Geolokalisierung mit Python

Reichern Sie eine Liste von IPs über POST /v1/lookup in Batches von 100 an, mit Zeilenzuordnung, per Checkpoint gesicherter Ausgabe und 429-Backoff — direkt per HTTP aufgerufen, da das offizielle Python-SDK diesen Endpoint nicht abdeckt.

Bevor Sie beginnen

  • Ein Watch-IP-Konto und ein geheimer Lookup-Schlüssel — POST /v1/lookup ist nur für Server-zu-Server-Aufrufe; rufen Sie ihn nie aus einem Browser auf und liefern Sie den Schlüssel nie in einem Client aus.
  • Python 3.9 oder höher.
  • Eine lokale Liste von IPs zum Anreichern — dieser Leitfaden liest sie aus einer CSV mit einer IP pro Zeile.

1. Warum dies direktes HTTP statt des SDK verwendet

watch-ip-sdk, das offizielle Python-Paket, implementiert nur GET /v1/geo, den browserorientierten Besucher-Endpoint — es hat keine Methode für POST /v1/lookup. Dieser Leitfaden ruft die API direkt mit urllib aus der Standardbibliothek auf, im selben abhängigkeitsfreien Ansatz wie das SDK selbst, statt nur für diesen Fall eine neue Abhängigkeit hinzuzufügen.

2. Die Eingabeliste lesen und validieren

Behalten Sie die ursprüngliche Zeilenposition jeder IP bei, damit ein Ergebnis dem Datensatz zugeordnet werden kann, aus dem es stammt — die API liefert die Ergebnisse in derselben Reihenfolge zurück, in der sie die IPs erhalten hat, was nur hilft, wenn Ihre eigene Liste diese Reihenfolge ebenfalls beibehält.

Python

import csv

with open("ips.csv", newline="") as f:
    ips = [row[0].strip() for row in csv.reader(f) if row and row[0].strip()]

print(f"{len(ips)} IPs geladen")

3. In Batches von 100 aufteilen

POST /v1/lookup akzeptiert 1–100 IPs pro Aufruf und validiert den gesamten Batch, bevor überhaupt etwas nachgeschlagen wird — eine einzige fehlerhafte Adresse lässt den ganzen Batch fehlschlagen, validieren Sie also zuerst lokal die IP-Syntax, falls Ihre Eingabeliste unsauber sein könnte.

Python

def chunk(items, size=100):
    for i in range(0, len(items), size):
        yield items[i : i + size]

4. Jeden Batch einreichen und Ergebnisse per Checkpoint sichern

Schreiben Sie Ergebnisse, sobald jeder Batch abgeschlossen ist, statt alles bis zum Schluss im Speicher zu halten, damit ein Fehler mitten in einer langen Liste nicht die bereits erfolgreichen Batches verliert. found: false bedeutet, dass die IP syntaktisch gültig ist, aber keinen Eintrag in der Datenbank hat — ein normales Ergebnis, kein Fehler.

Python

import json
import time
import urllib.error
import urllib.request

API_URL = "https://api.watch-ip.com/v1/lookup"
SECRET_KEY = "YOUR_SECRET_KEY"

def lookup_batch(ips):
    request = urllib.request.Request(
        API_URL,
        data=json.dumps({"ips": ips}).encode(),
        headers={
            "Authorization": f"Bearer {SECRET_KEY}",
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)["results"]

with open("results.jsonl", "a") as out:
    for batch in chunk(ips):
        try:
            results = lookup_batch(batch)
        except urllib.error.HTTPError as err:
            if err.code == 429:
                time.sleep(60)  # bis zum Ende des aktuellen Ein-Minuten-Fensters warten
                results = lookup_batch(batch)
            else:
                raise
        for result in results:
            out.write(json.dumps(result) + "\n")

5. Einen teilweisen Job fortsetzen

Da Ergebnisse batchweise angehängt werden, muss ein Neustart nach einem Absturz nur die bereits in results.jsonl geschriebenen IPs überspringen, statt die gesamte Liste erneut einzureichen — eine doppelt eingereichte IP wird erneut abgerechnet, da jede Eingabe in einem Batch individuell erfasst statt dedupliziert wird.

Python

done = set()
with open("results.jsonl") as f:
    for line in f:
        done.add(json.loads(line)["ip"])

remaining = [ip for ip in ips if ip not in done]

Fehler und Grenzfälle

Ein 400 bedeutet, dass der Batch mehr als 100 IPs, eine leere Liste oder irgendwo eine fehlerhafte Adresse enthielt — der gesamte Batch schlägt fehl, nicht nur der fehlerhafte Eintrag. Ein 403 bedeutet, dass ein veröffentlichbarer statt eines geheimen Schlüssels verwendet wurde. Gemischte IPv4- und IPv6-Adressen im selben Batch sind unproblematisch; jede wird unabhängig nachgeschlagen, mit denselben nullable Feldern in beiden Fällen.

Nächster Schritt

Siehe die Referenz zur IP-Massenabfrage für das genaue Antwortschema und Fehler und Ratenbegrenzungen für die vollständige Liste der Statuscodes, die dieser Endpoint zurückgeben kann.

Verwandte Seiten