Carrier Lookup API in Python: Einzel- und Multi-Anfragen mit requests

Ein Python-Leitfaden für Einzel- und Multi-Abfragen des ursprünglichen Netzbetreibers mit requests, einschließlich Fehlerbehandlung und Zuordnung geordneter Ergebnisse zu Datensätzen.

Um eine Carrier Lookup API in Python aufzurufen, verwenden Sie die Bibliothek requests, um eine E.164-Nummer per POST an /api/v1/check für ein einzelnes Ergebnis zu senden oder eine Liste von bis zu 100 Nummern an /api/v1/batch-check für einen geordneten Satz von Ergebnissen. Senden Sie den API-Schlüssel im Header X-API-Key von einem vertrauenswürdigen Server aus, legen Sie ein Timeout fest, prüfen Sie den Antwortcode vor dem Lesen der Daten und ordnen Sie Multi-Ergebnisse anhand ihrer Position und Kennung wieder Ihren Datensätzen zu. Der zurückgegebene Netzbetreiber entspricht der ursprünglichen Zuweisung, nicht dem aktuellen Netz.

Einrichten einer requests-Sitzung für Carrier Lookups

Die requests-Bibliothek hält HTTP-Aufrufe kurz, und ein Sitzungsobjekt ermöglicht es, dass alle Aufrufe dieselben Header und eine Verbindung teilen. Installieren Sie sie mit pip install requests und halten Sie den Schlüssel aus dem Quellcode fern, indem Sie ihn aus einer Umgebungsvariable lesen.

import os
import requests

BASE_URL = "https://carrierlookup.online"

session = requests.Session()
session.headers.update({
    "X-API-Key": os.environ["CARRIERLOOKUP_API_KEY"],
    "Accept": "application/json",
})

Drei Gewohnheiten sollten von Anfang an etabliert werden:

• Führen Sie diesen Code nur auf einem vertrauenswürdigen Server, einem Worker oder einem Notebook aus, das Sie kontrollieren. Geben Sie den Schlüssel niemals in einem Browser oder einer mobilen App weiter.
• Übergeben Sie bei jedem Aufruf immer ein timeout. Ohne ein solches kann requests unbegrenzt warten.
• Normalisieren Sie Nummern vor dem Senden auf das E.164-Format: ein führendes Pluszeichen, der Ländercode und die Teilnehmernummer, ohne Leerzeichen oder Trennzeichen.

Ein kleines Hilfsprogramm, das Trennzeichen entfernt und das Pluszeichen hinzufügt, erspart viel wiederholte Bereinigungsarbeit und hält Formatierungsprobleme aus Ihren Ergebnissen fern. Ein abgelehntes Format ist ein Formatierungsproblem, keine Antwort des Netzbetreibers; behandeln Sie dies daher vor der Anfrage.

Senden einer Einzelabfrage an /api/v1/check

Die Echtzeit-Einzelabfrage erfolgt über POST /api/v1/check. Sie nimmt eine E.164-Nummer entgegen und antwortet in derselben Anfrage. Senden Sie die Nummer im JSON-Body, wie in der API-Dokumentation beschrieben.

def check_one(number: str) -> dict | None:
    resp = session.post(
        f"{BASE_URL}/api/v1/check",
        json=build_single_payload(number),  # Body-Struktur: siehe API-Dokumentation
        timeout=65,
    )
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 0:
        print("nicht abgeschlossen:", body.get("msg"))
        return None
    return body["data"]

Der Body enthält einen code, eine msg und ein flaches data-Objekt. Ein code von null bedeutet, dass die Abfrage abgeschlossen wurde. Die Daten enthalten den ursprünglichen Netzbetreiber, den zugrunde liegenden Netzbetreiber, den Nummerntyp, den Ländercode, die Region und die Stadt. Jeder der optionalen Werte kann leer sein, und ein abgeschlossenes Ergebnis, bei dem alle Netzbetreiberwerte leer sind, ist dennoch ein normales Ergebnis. Speichern Sie leere Werte als nicht verfügbar, nicht als Beweis dafür, dass eine Nummer keinen Netzbetreiber hat.

Ein code ungleich null bedeutet, dass die Abfrage nicht abgeschlossen wurde, beispielsweise wenn eine Antwort nicht ermittelt werden konnte. Wandeln Sie diesen Fall nicht in einen leeren Erfolg um. Fehlgeschlagene oder unbestimmte Abfragen werden nicht berechnet, daher ist ein erneuter Versuch mit einer kurzen Verzögerung sinnvoll. Die öffentliche Dokumentation listet Timeout-Obergrenzen für Echtzeit-Aufrufe auf; halten Sie Ihr Client-Timeout daher auf oder über der dokumentierten Obergrenze für Einzelanfragen.

Senden einer Multi-Anfrage und Zuordnung der Ergebnisse zu Datensätzen

Wenn Sie eine kleine Menge haben, nimmt POST /api/v1/batch-check zwischen 1 und 100 E.164-Nummern entgegen und gibt ein geordnetes, synchrones Ergebnis zurück. Die Nummern können aus verschiedenen Ländern stammen. Die Antwort fasst zusammen, wie viele Elemente vorhanden waren, wie viele erfolgreich waren und wie viele fehlgeschlagen sind, und listet dann ein Ergebnis pro Eingabe in der richtigen Reihenfolge auf.

def check_many(numbers: list[str]) -> list[dict]:
    resp = session.post(
        f"{BASE_URL}/api/v1/batch-check",
        json=build_multi_payload(numbers),  # Body-Struktur: siehe API-Dokumentation
        timeout=310,
    )
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 0:
        raise RuntimeError(body.get("msg"))
    return body["data"]["results"]

Um Ergebnisse Ihren Datensätzen zuzuordnen, verknüpfen Sie die Eingabeliste mit der Ergebnisliste und prüfen Sie, ob die Kennung jedes Elements mit der von Ihnen gesendeten Nummer übereinstimmt. Diese zweite Prüfung schützt Sie vor stillschweigenden Fehlzuordnungen, falls eine Liste zwischen dem Erstellen und dem Senden der Anfrage geändert wurde.

Jedes Element enthält zudem ein exists-Flag. Wenn dieses falsch ist, hat das Element kein normales Ergebnis. Dies ist nicht dasselbe wie eine ungültige oder nicht vergebene Nummer; speichern Sie es daher als kein Ergebnis und entscheiden Sie später, ob Sie es erneut versuchen oder belassen wollen. Eine Multi-Anfrage, deren Zeitlimit überschritten wird, schlägt als Ganzes ohne Teilergebnisse fehl, und der volle Betrag wird zurückgegeben; die sichere Reaktion ist daher, denselben Block erneut zu senden.

Pro Konto wird immer nur eine Multi-Anfrage gleichzeitig ausgeführt; eine Schleife, die Blöcke verarbeitet, sollte daher auf den Abschluss jedes Aufrufs warten, bevor der nächste gesendet wird.

Blockweise Verarbeitung, Wiederholungen und Guthabenprüfung

Echte Listen sind länger als 100 Nummern, teilen Sie diese daher in Blöcke auf und verarbeiten Sie jeden nacheinander.

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

rows = []
for part in chunks(clean_numbers):
    rows.extend(check_many(part))

Mehrere praktische Regeln halten diese Schleife zuverlässig:

1. Bereinigen Sie die Liste zuerst durch Deduplizierung, sodass jede Nummer nur einmal abgefragt wird.
2. Fangen Sie requests.exceptions.Timeout und ConnectionError separat von API-Fehlern ab und führen Sie eine begrenzte Anzahl von Wiederholungen mit einer Pause durch.
3. Halten Sie die Nebenläufigkeit gering. Die öffentliche Dokumentation beschreibt eine kleine Anzahl gemeinsam genutzter Echtzeit-Slots und veröffentlicht kein festes Limit pro Minute; vermeiden Sie daher das Starten vieler paralleler Threads.
4. Schreiben Sie jeden abgeschlossenen Block sofort nach Erhalt auf die Festplatte oder in eine Datenbank, damit bei einem Absturz keine fertige Arbeit verloren geht.

Rufen Sie vor einem großen Durchlauf GET /api/v1/balance auf. Dies liest das Kontoguthaben aus, ohne etwas zu berechnen, und ermöglicht es dem Skript, frühzeitig mit einer klaren Meldung anzuhalten, anstatt auf halbem Weg fehlzuschlagen. Sowohl Echtzeit- als auch Dateidienste teilen sich ein Guthaben und rechnen pro abgeschlossener Nummer ab.

Für Listen, die weit über einige wenige Blöcke hinausgehen, ist eine asynchrone Dateiaufgabe besser geeignet als eine lange Schleife synchroner Aufrufe. Eine Dateiaufgabe ist ein separater Arbeitsablauf mit einem eigenen Endpunkt, keine größere Version einer Multi-Anfrage.

Ergebnisse verantwortungsbewusst interpretieren

Sobald die Daten in einem Pandas-Frame oder einer Datenbank vorliegen, besteht das Hauptrisiko in einer Überinterpretation. Der Netzbetreiber ist derjenige, dem der Nummernkreis ursprünglich zugewiesen wurde. Nach einer Portierung kann die Person einen anderen Betreiber nutzen. Region und Stadt beschreiben die Zuweisungsgeografie, nicht den aktuellen Standort einer Person oder eines Telefons. Der Nummerntyp gibt die Art des Bereichs an, nicht, ob der Anschluss aktiv ist.

Gute Einsatzmöglichkeiten umfassen das Gruppieren von Datensätzen für Tests des Provider-Routings, das Markieren ungewöhnlicher Nummerntypen zur Überprüfung und das Hinzufügen von Kontextspalten zu einem CRM. Schlechte Einsatzmöglichkeiten umfassen die Entscheidung, ob eine Nummer erreichbar ist oder nicht, Annahmen über den Besitzer oder die Ableitung einer Einwilligung.

Ein einfaches Schema hält die Bedeutung klar: ursprünglicher Netzbetreiber, zugrunde liegender Netzbetreiber, Nummerntyp, Ländercode, Region, Stadt, Abfragestatus und Abfragezeitpunkt. Die Statusspalte trennt abgeschlossene, leere und fehlgeschlagene Ergebnisse, sodass spätere Berichte diese nicht vermischen.

FAQ

Welche Python-Bibliothek eignet sich am besten für Carrier Lookup API-Aufrufe?

Die requests-Bibliothek reicht sowohl für den Einzel- als auch für den Multi-Endpunkt aus. Verwenden Sie eine Sitzung, um den API-Schlüssel-Header zu teilen, legen Sie immer ein Timeout fest und rufen Sie raise_for_status sowie eine Prüfung des Antwortcodes auf. Halten Sie bei vielen gleichzeitigen Aufgaben den Pool klein, da Echtzeit-Slots kontoübergreifend geteilt werden.

Wie können Teams Multi-Ergebnisse wieder den Eingabedatensätzen zuordnen?

Die Ergebnisse kommen in der Reihenfolge der Eingabe zurück, und jedes Element wiederholt die gesendete Kennung. Verknüpfen Sie die Eingabeliste mit den Ergebnissen und prüfen Sie dann, ob jede Kennung mit ihrer Zeile übereinstimmt, bevor Sie Daten schreiben. Elemente, bei denen das exists-Flag falsch ist, sollten als kein normales Ergebnis gespeichert werden, nicht als ungültige Nummern.

Wo sollte der API-Schlüssel in einem Python-Projekt gespeichert werden?

Bewahren Sie ihn in einer Umgebungsvariable oder einem Secrets-Manager auf einem vertrauenswürdigen Server auf und lesen Sie ihn beim Start ein. Übertragen Sie ihn nicht in die Versionsverwaltung und senden Sie ihn nicht aus Browser- oder Mobil-Code. Falls er in ein Protokoll oder Repository gelangt, rotieren Sie ihn und überprüfen Sie die kürzliche Nutzung.

Mehr erfahren

Wählen Sie die Produktinformationen, die zum nächsten Schritt in Ihrem Arbeitsablauf passen.

• Zur Produktdokumentation →
• Kontakt zum Team →