API Pencarian Operator Asli di Python: Permintaan Tunggal dan Multi dengan requests

Panduan Python untuk pencarian operator asli tunggal dan multi dengan requests, termasuk penanganan kesalahan dan pemetaan hasil berurutan kembali ke baris data.

Untuk memanggil API Pencarian Operator Asli di Python, gunakan pustaka requests untuk melakukan POST nomor E.164 ke /api/v1/check untuk satu hasil, atau daftar hingga 100 nomor ke /api/v1/batch-check untuk mendapatkan sekumpulan hasil yang berurutan. Kirim kunci API di header X-API-Key dari server tepercaya, atur batas waktu (timeout), periksa kode respons sebelum membaca data, dan petakan hasil multi kembali ke baris data Anda berdasarkan posisi dan pengenal. Operator yang dikembalikan adalah alokasi asli, bukan jaringan saat ini.

Menyiapkan sesi requests untuk pencarian operator

Pustaka requests menjaga panggilan HTTP tetap ringkas, dan objek sesi memungkinkan setiap panggilan berbagi header dan koneksi. Instal pustaka ini dengan pip install requests dan simpan kunci agar tidak masuk ke kode sumber dengan membacanya dari variabel lingkungan.

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",
})

Tiga kebiasaan yang layak dibangun sejak awal:

• Jalankan kode ini hanya di server tepercaya, pekerja, atau notebook yang Anda kendalikan. Jangan pernah mengirimkan kunci di browser atau aplikasi seluler.
• Selalu berikan timeout ke setiap panggilan. Tanpa batas waktu, requests dapat menunggu tanpa batas.
• Normalisasikan nomor ke E.164 sebelum mengirim apa pun: tanda plus di depan, kode negara, dan nomor pelanggan, tanpa spasi atau pemisah.

Pembantu kecil yang menghapus pemisah dan menambahkan tanda plus akan menghemat banyak pembersihan berulang, serta menjaga masalah format agar tidak masuk ke hasil Anda. Format yang ditolak adalah masalah pemformatan, bukan jawaban operator, jadi tangani hal tersebut sebelum melakukan permintaan.

Mengirim pencarian tunggal ke /api/v1/check

Pencarian tunggal waktu nyata adalah POST /api/v1/check. Layanan ini menerima satu nomor E.164 dan menjawab dalam respons yang sama. Kirim nomor tersebut dalam badan JSON seperti yang dijelaskan dalam dokumentasi API.

def check_one(number: str) -> dict | None:
    resp = session.post(
        f"{BASE_URL}/api/v1/check",
        json=build_single_payload(number),  # bentuk badan: lihat dokumentasi API
        timeout=65,
    )
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 0:
        print("tidak selesai:", body.get("msg"))
        return None
    return body["data"]

Badan respons memiliki code, msg, dan objek data datar. code nol berarti pencarian selesai. Data tersebut berisi operator asli, operator dasar, jenis nomor, kode negara, wilayah, dan kota. Nilai opsional apa pun bisa kosong, dan hasil yang selesai dengan setiap nilai operator kosong tetap merupakan hasil yang normal. Simpan nilai kosong sebagai tidak tersedia, bukan sebagai bukti bahwa nomor tersebut tidak memiliki operator.

code bukan nol berarti pencarian tidak selesai, misalnya ketika jawaban tidak dapat ditentukan. Jangan ubah kasus tersebut menjadi keberhasilan kosong. Pencarian yang gagal atau Tidak dapat ditentukan tidak dikenakan biaya, jadi mencoba kembali dengan jeda singkat adalah hal yang wajar. Dokumentasi publik mencantumkan batas waktu untuk panggilan waktu nyata, jadi pertahankan batas waktu klien Anda pada atau di atas batas yang didokumentasikan untuk permintaan tunggal.

Mengirim permintaan multi dan memetakan hasil ke baris data

Jika Anda memiliki batch kecil, POST /api/v1/batch-check menerima antara 1 hingga 100 nomor E.164 dan mengembalikan hasil sinkron yang berurutan. Nomor-nomor tersebut bisa berasal dari negara yang berbeda. Respons merangkum berapa banyak item yang ada, berapa banyak yang berhasil, dan berapa banyak yang gagal, lalu mencantumkan hasil per input secara berurutan.

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

Untuk melampirkan hasil ke baris data Anda, gabungkan daftar input dengan daftar hasil, dan periksa apakah pengenal setiap item cocok dengan nomor yang Anda kirim. Pemeriksaan kedua tersebut melindungi Anda dari ketidaksesuaian diam-diam jika daftar diubah antara pembuatan dan pengiriman permintaan.

Setiap item juga membawa tanda exists. Jika tandanya salah, item tersebut tidak memiliki hasil normal. Itu tidak sama dengan nomor yang tidak valid atau terputus, jadi simpan sebagai tidak ada hasil dan putuskan nanti apakah akan mencoba kembali atau membiarkannya. Permintaan multi yang kehabisan waktu akan gagal secara keseluruhan tanpa hasil parsial, dan jumlah penuh dikembalikan, jadi respons yang aman adalah mencoba kembali potongan yang sama.

Hanya satu permintaan multi per akun yang berjalan pada satu waktu, jadi loop yang memproses potongan harus menunggu setiap panggilan selesai sebelum mengirim yang berikutnya.

Memotong, mencoba kembali, dan memeriksa saldo

Daftar nyata lebih panjang dari 100 nomor, jadi bagi daftar tersebut menjadi potongan-potongan dan tangani masing-masing secara bergantian.

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))

Beberapa aturan praktis menjaga loop ini tetap dapat diandalkan:

1. Hapus duplikat daftar bersih terlebih dahulu, sehingga setiap nomor dicari satu kali.
2. Tangkap requests.exceptions.Timeout dan ConnectionError secara terpisah dari kesalahan API, dan coba kembali dalam jumlah terbatas dengan jeda.
3. Jaga konkurensi tetap rendah. Dokumentasi publik menjelaskan sejumlah kecil slot waktu nyata yang digunakan bersama dan tidak memublikasikan batas tetap per menit, jadi hindari menjalankan banyak thread paralel.
4. Tulis setiap potongan yang selesai ke disk atau basis data segera setelah dikembalikan, sehingga kerusakan sistem tidak menghilangkan pekerjaan yang sudah selesai.

Sebelum menjalankan proses besar, panggil GET /api/v1/balance. Perintah ini membaca saldo akun tanpa membebankan biaya apa pun, dan memungkinkan skrip berhenti lebih awal dengan pesan yang jelas alih-alih gagal di tengah jalan. Baik layanan waktu nyata maupun layanan file berbagi satu saldo dan menagih per nomor yang selesai.

Untuk daftar yang jauh lebih besar daripada beberapa potongan, tugas file asinkron lebih cocok daripada loop panjang panggilan sinkron. Tugas file adalah alur kerja terpisah dengan titik akhirnya sendiri, bukan versi yang lebih besar dari permintaan multi.

Menafsirkan hasil secara bertanggung jawab

Setelah data berada dalam bingkai pandas atau basis data, risiko utamanya adalah membaca data secara berlebihan. Operator adalah operator tempat rentang nomor tersebut dialokasikan secara asli. Setelah porting, orang tersebut mungkin menggunakan operator lain. Wilayah dan kota menggambarkan geografi alokasi, bukan di mana orang atau telepon berada sekarang. Jenis nomor memberi tahu Anda jenis rentang, bukan apakah saluran tersebut aktif.

Penggunaan yang baik termasuk mengelompokkan catatan untuk pengujian perutean penyedia, menandai jenis nomor yang tidak biasa untuk ditinjau, dan menambahkan kolom konteks ke CRM. Penggunaan yang buruk termasuk memutuskan bahwa suatu nomor dapat atau tidak dapat dihubungi, berasumsi siapa pemiliknya, atau menyimpulkan persetujuan.

Skema sederhana menjaga maknanya tetap jelas: operator asli, operator dasar, jenis nomor, kode negara, wilayah, kota, status pencarian, dan waktu pencarian. Kolom status memisahkan hasil yang selesai, kosong, dan gagal, sehingga laporan nantinya tidak mencampurnya.

FAQ

Pustaka Python mana yang paling cocok untuk panggilan API pencarian operator?

Pustaka requests sudah cukup untuk titik akhir tunggal maupun multi. Gunakan sesi untuk berbagi header kunci API, selalu atur batas waktu, dan panggil raise_for_status ditambah pemeriksaan pada kode respons. Untuk banyak pekerjaan konkuren, jaga agar kumpulan tetap kecil karena slot waktu nyata dibagikan di seluruh akun.

Bagaimana tim dapat memetakan hasil multi kembali ke baris input?

Hasil kembali dalam urutan input, dan setiap item mengulangi pengenal yang dikirim. Gabungkan daftar input dengan hasil, lalu verifikasi bahwa setiap pengenal cocok dengan barisnya sebelum menulis data. Item di mana tanda exists salah harus disimpan sebagai tidak memiliki hasil normal, bukan sebagai nomor yang tidak valid.

Di mana kunci API harus disimpan dalam proyek Python?

Simpan kunci tersebut dalam variabel lingkungan atau manajer rahasia di server tepercaya dan baca saat startup. Jangan masukkan kunci ke kontrol sumber atau kirim dari kode browser atau seluler. Jika kunci bocor ke log atau repositori, ganti kunci tersebut dan tinjau penggunaan terbaru.

Pelajari Lebih Lanjut

Pilih informasi produk yang sesuai dengan langkah berikutnya dalam alur kerja Anda.

• Lihat dokumentasi produk →
• Bicara dengan tim →