Registrieren Sie sich und kontaktieren Sie den Support, um 100 kostenlose Prüfungen zu erhalten.Kostenlos registrieren
CarrierLookup
CarrierLookup Workflow-Illustration zu „Bulk Carrier Lookup API: Einreichen einer Datei-Aufgabe und Abrufen der CSV“
Ein visueller Überblick über den in diesem CarrierLookup Artikel beschriebenen Workflow.

Ein Entwickler-Leitfaden für die Bulk-Datei-Aufgabe von CarrierLookup: Übermittlung einer TXT- oder CSV-Datei mit Länderangabe, Status-Polling und Lesen des resultierenden CSV-Ergebnisses.

Die Bulk-Carrier-Lookup-API von CarrierLookup ist eine asynchrone Datei-Aufgabe. Senden Sie eine Multipart-Anfrage an POST /api/v1/bulk-tasks, wobei das Feld für das Land vor der Datei platziert wird. Lesen Sie anschließend den Status über GET /api/v1/bulk-tasks/{id} – jedoch nicht häufiger als alle 30 Sekunden –, bis der Status success oder failed lautet. Eine erfolgreiche Aufgabe liefert eine herunterladbare CSV-Datei mit Angaben zum ursprünglichen Netzbetreiber, dem zugrunde liegenden Netzbetreiber, dem Nummerntyp und den Zuweisungsdaten. Dieser Pfad eignet sich für große Listen für ein einzelnes Land. Es gelten produktbezogene Limits; prüfen Sie diese daher vorab in der API-Dokumentation.

Vorbereiten der Datei vor dem API-Aufruf

Eine saubere Datei spart mehr Zeit als jede Wiederholungslogik. Der Bulk-Pfad akzeptiert eine einspaltige TXT- oder CSV-Datei mit einer Nummer pro Zeile, inklusive Ländervorwahl. XLSX-Dateien werden nicht akzeptiert; exportieren Sie Tabellenkalkulationen daher zuerst in ein Text- oder CSV-Format.

Schreiben Sie jede Zeile als Ziffernfolge mit Ländervorwahl. Halten Sie die Liste im Wesentlichen auf ein Land beschränkt, da für die Aufgabe ein einzelnes Land ausgewählt wird und Nummern außerhalb dieses Bereichs ausgeschlossen werden.

Eine kurze Vorbereitungsroutine:

  1. Exportieren Sie eine Spalte und entfernen Sie Kopfzeilen oder Notizen.
  2. Normalisieren Sie jede Zeile auf das Format mit Ländervorwahl.
  3. Teilen Sie die Masterliste nach Ländern auf und erstellen Sie eine Datei pro Land.
  4. Prüfen Sie die Datei anhand der aktuellen Limits in der API-Dokumentation. Die dort dokumentierte Standard-Dateigrößenobergrenze kann durch ein vom Live-Dienst zurückgegebenes Limit überschrieben werden; der Live-Wert hat Vorrang.

Durch die Vorverarbeitung werden ungültige Zeilen, Duplikate, Nummern ohne Ländervorwahl und Nummern außerhalb des ausgewählten Landes ausgeschlossen; diese werden nicht berechnet. Wenn Sie diese selbst vorab entfernen, erhalten Sie ein klareres Bild davon, wie viele Zeilen Sie tatsächlich übermittelt haben. Bewahren Sie eine Kopie der exakt übermittelten Datei samt Zeilenanzahl auf, damit Sie die finale CSV später mit Ihrer Quelldatei abgleichen und sehen können, welche Zeilen herausgefiltert wurden.

Einreichen der Aufgabe mit einer Multipart-Anfrage

Übermitteln Sie die Aufgabe mit POST /api/v1/bulk-tasks von einem vertrauenswürdigen Server aus. Authentifizieren Sie sich mit dem Header X-API-Key und geben Sie den Schlüssel niemals im Browser-Code preis.

Der Body ist ein Multipart-Form-Data mit zwei Teilen: dem ausgewählten Land und der Datei. Die Reihenfolge ist wichtig; platzieren Sie daher den Teil für das Land vor dem Dateiteil. Viele HTTP-Clients erstellen den Body aus einem Dictionary, wobei die Reihenfolge der Einfügung folgen kann; prüfen Sie daher, wie Ihr Client dies serialisiert.

Ein Entwurf des Aufrufs mit curl:

curl -X POST https://carrierlookup.online/api/v1/bulk-tasks \
  -H "X-API-Key: $CARRIERLOOKUP_API_KEY" \
  -F "country=GB" \
  -F "file=@uk_numbers.csv"

Verwenden Sie den ISO-Ländercode, der zur Liste passt. Die Antwort bietet Ihnen eine Möglichkeit, die Aufgabe für das Polling zu referenzieren; speichern Sie diese Referenz zusammen mit Ihrem eigenen Job-Datensatz. Erfinden Sie keine zusätzlichen Felder, JSON-Arrays von Nummern, Webhooks oder Abbruchaufrufe. Nur die Dateiübermittlung und Statusabfragen sind dokumentiert.

Polling der Aufgabe ohne Überlastung der API

Lesen Sie den Status mit GET /api/v1/bulk-tasks/{id}. Eine Aufgabe befindet sich in einem von drei Zuständen: processing, success oder failed.

Führen Sie das Polling nicht häufiger als alle 30 Sekunden durch. Eine engere Schleife beschleunigt die Arbeit nicht. Es ist keine normale Abschlusszeit dokumentiert, und es gibt keinen Fortschritt pro Nummer; bauen Sie die Schleife daher um den Status herum auf, anstatt die Dauer zu schätzen.

import time, requests

def wait_for_task(task_ref, headers):
    while True:
        r = requests.get(f"https://carrierlookup.online/api/v1/bulk-tasks/{task_ref}", headers=headers, timeout=30)
        state = r.json()["data"]["status"]
        if state in ("success", "failed"):
            return state
        time.sleep(30)

Betrachten Sie die Feldnamen in diesem Entwurf als Platzhalter und entnehmen Sie die exakte Antwortstruktur der API-Dokumentation. Fügen Sie in der Produktion eine maximale Wartezeit hinzu, die Ihrem Zeitplan entspricht, speichern Sie den zuletzt beobachteten Status und lassen Sie einen Operator-Alarm auslösen, wenn eine Aufgabe länger als Ihre Toleranzgrenze im Status processing verbleibt.

Herunterladen und Lesen der CSV

Wenn der Status success lautet, laden Sie das Ergebnis herunter. Sie erhalten eine CSV-Datei, keine ZIP-Datei. Sie enthält den Identifikator, den Netzbetreiber, den zugrunde liegenden Netzbetreiber, den Nummerntyp, den Ländercode, die Region und die Stadt für die Nummern, für die Ergebnisse zurückgegeben wurden.

Drei Regeln für das Lesen:

  • Der Identifikator enthält kein Pluszeichen. Es handelt sich um reine Ziffern mit Ländervorwahl ohne Leerzeichen. Normalisieren Sie Ihre eigenen Schlüssel auf die gleiche Weise, bevor Sie diese zusammenführen.
  • Leere Zellen bedeuten Unbestimmt. Behalten Sie diese als Unbestimmt-Werte bei und konvertieren Sie sie nicht in eine negative Schlussfolgerung.
  • Der Netzbetreiber ist die ursprüngliche Zuweisung. Es handelt sich nicht um den aktuellen Netzbetreiber nach einer Portierung. Region und Stadt beschreiben die Zuweisungsgeografie, nicht den aktuellen Aufenthaltsort einer Person oder eines Geräts.

Laden Sie die Datei zuerst in eine Staging-Tabelle und führen Sie sie dann anhand des Schlüssels mit Ihren Kontaktdaten zusammen. Bewahren Sie die Aufgabenreferenz und das Ausführungsdatum in der Staging-Tabelle auf, damit spätere Audits nachvollziehen können, welche Ausführung welche Werte geliefert hat. Denken Sie daran, dass die CSV keine Spalte enthält, die angibt, ob eine Nummer erreichbar ist; Ihre eigenen Regeln sollten dies nicht ableiten.

Fehler, Reservierung und Guthaben

Eine Bulk-Aufgabe reserviert bei der Übermittlung einen geschätzten Betrag und berechnet nur die Nummern, für die Ergebnisse zurückgegeben werden. Der ungenutzte Teil der Reservierung fließt nach Abschluss der Aufgabe in dasselbe Wallet zurück, und eine fehlgeschlagene Aufgabe gibt ihre gesamte Reservierung frei. Dies ist ein Abgleich innerhalb Ihres Guthabens und keine Rückerstattung eines Kaufs.

Eine Aufgabe kann während der Vorbereitung fehlschlagen, zum Beispiel wenn zu wenige gültige Mobilfunknummern geschätzt werden oder eine andere Akzeptanzbedingung nicht erfüllt ist. Wenn dies geschieht, überprüfen Sie die Datei auf die oben beschriebenen Ausschlüsse, korrigieren Sie die Liste und reichen Sie eine neue Aufgabe ein, anstatt blind dieselbe Datei erneut zu versuchen.

Prüfen Sie GET /api/v1/balance vor der Übermittlung. Dies liest das Guthaben aus, ohne Kosten zu verursachen. Vergleichen Sie bei einem geplanten Job das Guthaben mit Ihrer erwarteten Listengröße und stoppen Sie frühzeitig, falls es nicht ausreicht, da eine Reservierung, die nicht passt, die Aufgabe ansonsten stoppen würde. Für kleine verbleibende Gruppen nach einer Länderaufteilung kann eine synchrone Multi-Anfrage über POST /api/v1/batch-check einfacher sein als eine weitere Datei-Aufgabe.

FAQ

Wie können Entwickler eine Bulk-Aufgabe ohne Multipart-Fehler einreichen?

Platzieren Sie das Feld für das Land vor dem Dateifeld im Multipart-Body, senden Sie die Datei als einfache TXT- oder CSV-Datei mit einer Nummer pro Zeile inklusive Ländervorwahl und halten Sie den API-Schlüssel im Header X-API-Key von einem vertrauenswürdigen Server aus bereit. Prüfen Sie, wie Ihr HTTP-Client Formularfelder sortiert.

Wie können Entwickler ein Polling-Intervall für den Aufgabenstatus wählen?

Führen Sie das Polling für den Statusaufruf nicht häufiger als alle 30 Sekunden durch und stoppen Sie, wenn der Status success oder failed lautet. Es ist keine normale Abschlusszeit oder ein Fortschritt pro Nummer dokumentiert; legen Sie daher Ihre eigene maximale Wartezeit fest und alarmieren Sie einen Operator, wenn eine Aufgabe diese überschreitet.

Wie können Teams mit einer fehlgeschlagenen Bulk-Aufgabe umgehen?

Werten Sie den Fehler als Signal bezüglich der Datei oder der Akzeptanzbedingungen. Die Reservierung wird vollständig zurückgegeben; überprüfen Sie daher die Liste auf ungültige Zeilen, Duplikate, fehlende Ländervorwahlen und Nummern außerhalb des ausgewählten Landes, korrigieren Sie diese und reichen Sie eine neue Aufgabe ein.

Mehr erfahren

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

Quellen