Batch-Abfrage von Telefonnummern: Synchrone Multi-Anfragen vs. Bulk-Dateiaufträge

Ein Vergleich der beiden Batch-Methoden von CarrierLookup, der synchronen Multi-Anfrage und dem asynchronen Bulk-Dateiauftrag, inklusive eines Leitfadens zur Auswahl basierend auf Listengröße und Workflow.

Die Batch-Abfrage von Telefonnummern mit CarrierLookup erfolgt über einen von zwei Wegen. Eine synchrone Multi-Anfrage verarbeitet bis zu 100 Nummern über die API oder bis zu 500 über das Dashboard und liefert geordnete Ergebnisse in derselben Antwort. Ein Bulk-Dateiauftrag verarbeitet eine TXT- oder CSV-Datei für ein ausgewähltes Land, läuft asynchron ab und endet mit einer herunterladbaren CSV-Datei. Wählen Sie die Multi-Anfrage für kleine Gruppen und Live-Workflows sowie den Dateiauftrag für umfangreiche Listen. Beide liefern den ursprünglichen Netzbetreiber und Kontext zur Nummernzuweisung, nicht den aktuellen Netzbetreiber nach einer Portierung und kein Signal zur Erreichbarkeit.

Zwei Batch-Methoden, zwei verschiedene Aufgaben

Teams, die nach einer Batch-Abfrage von Telefonnummern suchen, gehen oft davon aus, dass jedes Batch-Tool auf die gleiche Weise funktioniert. CarrierLookup bietet bewusst zwei Formate an, und deren Verwechslung ist der häufigste Planungsfehler.

Die synchrone Multi-Anfrage ist ein interaktiver Aufruf. Sie senden eine Gruppe von E.164-Nummern, warten und erhalten eine geordnete Antwort. Die Nummern in der Gruppe können aus verschiedenen Ländern stammen; eine separate Länderauswahl ist nicht erforderlich.

Der Bulk-Dateiauftrag ist ein Prozess. Sie bereiten eine einspaltige TXT- oder CSV-Datei vor, wählen ein Land aus, übermitteln die Datei und rufen das Ergebnis später ab. Die Arbeit erfolgt im Hintergrund, und das Ergebnis ist eine Datei anstelle eines Antwortkörpers.

Für beide Methoden gelten produktabhängige Limits; prüfen Sie daher die aktuelle API-Dokumentation, bevor Sie einen Auftrag dimensionieren.

Funktionsweise einer synchronen Multi-Anfrage

Verwenden Sie POST /api/v1/batch-check von einem vertrauenswürdigen Server aus, wobei der API-Schlüssel im X-API-Key Header gesendet wird. Das Dashboard bietet für größere Gruppen von bis zu 500 Nummern dieselbe Funktionalität im Browser.

Jede Nummer muss im E.164-Format geschrieben sein: ein führendes Pluszeichen, der Ländercode und die Teilnehmernummer, ohne Leerzeichen oder Trennzeichen. Eine falsch formatierte Nummer wird aufgrund ihres Formats abgelehnt. Dies ist ein Formatierungsproblem, das behoben werden muss, und kein Hinweis darauf, dass die Nummer keinen Netzbetreiber hat.

Die Antwort gibt an, wie viele Nummern übermittelt wurden, wie viele erfolgreich waren und wie viele fehlgeschlagen sind, gefolgt von den Ergebnissen in der gleichen Reihenfolge, in der Sie die Nummern gesendet haben. Die Reihenfolge ist wichtig, da sie es Ihnen ermöglicht, jede Antwort ohne einen Join-Schlüssel einer Zeile in Ihrer eigenen Tabelle zuzuordnen.

Zwei Verhaltensweisen verdienen Aufmerksamkeit:

• Ein als nicht existent markiertes Ergebnis bedeutet, dass für diese Nummer kein normales Ergebnis zurückgegeben wurde. Dies ist keine Aussage darüber, dass die Nummer ungültig oder abgeschaltet ist.
• Wenn die gesamte Anfrage eine Zeitüberschreitung (Timeout) erfährt, schlägt sie als Ganzes fehl. Es werden keine Teilergebnisse zurückgegeben, und der volle Betrag wird Ihrem Guthaben gutgeschrieben.

Da der Aufruf synchron ist, sollten Sie ihn aus Pfaden heraushalten, in denen ein Benutzer auf das Laden einer Seite wartet, es sei denn, Sie haben das Timeout entsprechend behandelt.

Funktionsweise eines Bulk-Dateiauftrags

Verwenden Sie POST /api/v1/bulk-tasks mit einem multipart-Body. Platzieren Sie das Feld für das Land vor dem Dateifeld, da die Reihenfolge bei der multipart-Übermittlung wichtig ist. Rufen Sie anschließend den Fortschritt mit GET /api/v1/bulk-tasks/{id} ab.

Ein Auftrag befindet sich in einem von drei Zuständen: processing, success oder failed. Fragen Sie den Status nicht häufiger als alle 30 Sekunden ab. Eine engere Schleife erhöht die Last, ohne den Auftrag schneller abzuschließen, und da keine Abschlusszeit dokumentiert ist, sollten Sie den Prozess basierend auf dem Status planen.

Vor dem Hauptdurchlauf wird die Datei vorverarbeitet. Ungültige Zeilen, Duplikate, Nummern ohne Ländercode und Nummern außerhalb des ausgewählten Landes werden ausgeschlossen; ausgeschlossene Zeilen werden nicht berechnet. Ein Auftrag kann auch während der Vorbereitung fehlschlagen, wenn die Datei nicht den Annahmebedingungen entspricht; in diesem Fall wird der reservierte Betrag vollständig auf Ihr Guthaben zurückgebucht.

Bei Erfolg laden Sie eine CSV-Datei herunter, keine ZIP-Datei. Die Spalten sind der Identifikator, der Netzbetreiber, der zugrunde liegende Netzbetreiber, der Nummerntyp, der Ländercode, die Region und die Stadt. In der CSV-Datei besteht der Identifikator aus reinen Ziffern mit Ländercode ohne Pluszeichen; normalisieren Sie daher Ihre eigenen Schlüssel, bevor Sie die Datei wieder mit einer Datenbank zusammenführen. Leere Zellen bedeuten, dass der Wert nicht verfügbar ist.

Auswahl nach Listengröße, Ländermix und Workflow

Orientieren Sie sich an der Struktur Ihrer Daten und nicht nur an der reinen Anzahl.

1. Eine Gruppe mit gemischten Ländern, die sofort eine Antwort benötigt. Verwenden Sie eine synchrone Multi-Anfrage. Ein Dateiauftrag würde Sie zwingen, die Liste zuerst nach Ländern aufzuteilen.
2. Eine große Liste, die im Wesentlichen aus einem Land besteht. Verwenden Sie einen Dateiauftrag. Wählen Sie das Land aus, übermitteln Sie die Datei und lassen Sie die Vorverarbeitung Duplikate und fehlerhafte Nummern entfernen.
3. Eine große Liste mit gemischten Ländern. Teilen Sie diese nach Ländercode auf und übermitteln Sie dann einen Dateiauftrag pro Land. Alles, was nicht in eine Länderdatei passt, kann in Blöcken von bis zu 100 Nummern über Multi-Anfragen verarbeitet werden.
4. Eine Einzelprüfung bei der Registrierung oder CRM-Eingabe. Verwenden Sie die Einzelnummernprüfung, POST /api/v1/check. Nummern aus Festlandchina, Hongkong und Macau werden nur über Echtzeit-Einzelprüfungen bei geringem Volumen unterstützt; leiten Sie diese daher dorthin und nicht in eine Multi-Anfrage oder einen Dateiauftrag.

Bulk-Arbeiten eignen sich auch für Batch-Jobs, die über Nacht oder zwischen Kampagnen laufen, da Sie diese übermitteln, abfragen und sammeln. Multi-Anfragen passen zu Schleifen, die Daten bereits in kleinen Blöcken verarbeiten und Ergebnisse direkt in eine Datenbank oder ein CRM schreiben können.

Abrechnung und Guthabenprüfung für beide Methoden

Beide Methoden greifen auf ein gemeinsames Guthaben zurück, und jede erfolgreich verarbeitete Nummer wird zum gleichen veröffentlichten Tarif berechnet. Fehlgeschlagene oder unbestimmte Abfragen werden nicht berechnet. Eine abgeschlossene Abfrage, deren Netzbetreiberfelder alle leer sind, gilt dennoch als abgeschlossene Abfrage und kann berechnet werden; interpretieren Sie eine leere Zeile daher nicht als kostenlos oder als Beweis dafür, dass kein Netzbetreiber existiert.

Ein Dateiauftrag reserviert bei der Übermittlung einen geschätzten Betrag und berechnet dann nur die Nummern, für die Ergebnisse zurückgegeben wurden. Der ungenutzte Teil der Reservierung oder die gesamte Reservierung eines fehlgeschlagenen Auftrags fließt in dasselbe Guthaben zurück. Dies ist eine Abstimmung innerhalb Ihres Guthabens, keine Rückerstattung eines Kaufs.

Lesen Sie vor jeder großen Übermittlung das Guthaben mit GET /api/v1/balance aus. Der Aufruf ist kostenlos und informiert Sie darüber, ob die Reservierung ausreicht. Fügen Sie dieselbe Prüfung in einen geplanten Job ein, damit ein niedriges Guthaben den Lauf stoppt, bevor er beginnt, anstatt mitten in einer Pipeline fehlzuschlagen.

Korrektes Lesen der Ergebnisse

Egal für welche Methode Sie sich entscheiden, die Daten bedeuten dasselbe. Der Netzbetreiber ist derjenige, dem der Nummernkreis ursprünglich zugewiesen wurde. Es ist nicht das Netzwerk, das die Nummer heute bedient, da eine Portierung eine Nummer verschieben kann, ohne die ursprüngliche Zuweisung zu ändern. Der zugrunde liegende Netzbetreiber und der Nummerntyp liefern Kontext, und Region sowie Stadt beschreiben die Geografie der Zuweisung und nicht den aktuellen Standort einer Person oder eines Geräts.

Dies macht die Ausgabe nützlich für Gruppierungen, Routing-Tests und Prüfschlangen. Es ist kein Beweis dafür, dass eine Nummer Anrufe oder Nachrichten empfangen kann, dass sie aktiv ist oder wem sie gehört.

Speichern Sie jedes Feld als Attribut der ursprünglichen Zuweisung, kennzeichnen Sie leere Werte als nicht verfügbar und vermeiden Sie das Überschreiben von Feldern, die Ihre eigenen Systeme auf anderem Wege bestätigt haben. Teams, die diese Felder als Zuweisungskontext behandeln, vermeiden später die meisten Streitigkeiten darüber, was die Daten versprochen haben.

FAQ

Wie können Teams zwischen einer Multi-Anfrage und einem Dateiauftrag entscheiden?

Betrachten Sie zuerst die Struktur Ihrer Liste. Eine Gruppe von Nummern aus gemischten Ländern, die eine sofortige, geordnete Antwort erfordert, eignet sich für eine Multi-Anfrage. Eine große Liste, die im Wesentlichen aus einem Land besteht, eignet sich für einen Dateiauftrag, der im Hintergrund läuft und in einer CSV-Datei endet. Es gelten produktabhängige Limits; prüfen Sie daher die aktuelle API-Dokumentation, bevor Sie eine der Methoden dimensionieren.

Wie können Teams die Reihenfolge der Ergebnisse bei einer Multi-Anfrage handhaben?

Die Ergebnisse werden in der gleichen Reihenfolge zurückgegeben, in der die Nummern gesendet wurden. Behalten Sie daher Ihre eigene Liste in einer stabilen Reihenfolge bei und ordnen Sie die Ergebnisse nach Position zu. Behandeln Sie ein Ergebnis als Unbestimmt, wenn kein normales Ergebnis vorliegt, nicht als ungültige Nummer, und wiederholen Sie nur die Zeilen, die Sie nach der Behebung von Formatproblemen benötigen.

Wie können Teams unnötiges Polling bei einem Bulk-Auftrag vermeiden?

Fragen Sie den Auftragsstatus nicht häufiger als alle 30 Sekunden ab und stoppen Sie, wenn der Status success oder failed lautet. Da keine Abschlusszeit dokumentiert ist, bauen Sie den Job um den Status herum auf. Laden Sie bei Erfolg die einzelne CSV-Datei herunter und normalisieren Sie den Identifikator, bevor Sie ihn mit bestehenden Datensätzen zusammenführen.

Mehr erfahren

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

• Zur Produktdokumentation →
• Kontaktieren Sie das Team →