API Pencarian Operator Telepon: Satu Permintaan, Satu Hasil Operator Asli

Panduan pengembang untuk panggilan API pencarian operator telepon satu nomor: permintaan, pembacaan hasil, penanganan kesalahan, dan kapan harus beralih ke permintaan multi-nomor.

API pencarian operator telepon mengambil satu nomor telepon dari server Anda dan mengembalikan operator tempat rentang nomor tersebut dialokasikan secara asli, beserta konteks terkait. Dengan CarrierLookup, backend tepercaya mengirimkan satu nomor E.164 ke POST /api/v1/check dengan header X-API-Key dan menerima hasil sinkron: operator asli, operator pendukung, jenis nomor, kode negara, serta wilayah dan kota alokasi. Operator tersebut adalah alokasi asli, bukan jaringan setelah porting. Hasil yang selesai dengan kolom kosong tetap merupakan pencarian yang selesai, sementara pemeriksaan yang tidak dapat ditentukan mengembalikan kode bisnis bukan nol. Untuk hingga 100 nomor dalam satu panggilan, beralihlah ke POST /api/v1/batch-check.

Apa yang dikembalikan oleh API pencarian operator telepon

Banyak halaman pencarian operator mengaburkan dua pertanyaan berbeda: kepada siapa rentang nomor ini diberikan, dan siapa yang melayani nomor tersebut saat ini. CarrierLookup menjawab pertanyaan pertama. Hasil operatornya menyebutkan operator tempat blok nomor tersebut dialokasikan secara asli berdasarkan rencana penomoran nasional. Di negara-negara dengan portabilitas nomor, pelanggan dapat mempertahankan nomor tersebut saat pindah ke penyedia lain, sebagaimana dijelaskan dalam panduan porting FCC, sehingga operator asli dan penyedia saat ini bisa berbeda.

Hasil tunggal yang selesai, jika dijelaskan dengan kata-kata sederhana, berisi:

• Operator asli: operator tempat rentang tersebut dialokasikan.
• Operator pendukung: jaringan di balik operator tersebut, jika nilainya tersedia.
• Jenis nomor: jenis rentang, seperti seluler atau telepon kabel (fixed line).
• Kode negara, wilayah, dan kota: tempat rentang tersebut dialokasikan, bukan tempat orang atau perangkat berada.

Perlakukan ini sebagai konteks alokasi untuk pengelompokan, pengujian perutean, dan peninjauan. Hasil operator tidak menunjukkan bahwa nomor tersebut sedang aktif, dapat menerima panggilan atau SMS, atau milik orang tertentu.

Mengirim satu nomor ke API pencarian operator

Rute satu nomor adalah permintaan sinkron yang singkat. Integrasi umum mengikuti lima langkah:

1. Simpan kunci di server tepercaya. REST API melakukan autentikasi dengan header X-API-Key. Panggil dari backend atau runner tugas Anda, jangan pernah dari kode browser atau aplikasi seluler di mana kunci tersebut dapat disalin.
2. Normalisasi input ke E.164. Rencana ITU-T E.164 mendefinisikan format internasional. CarrierLookup mengharapkan tanda plus di depan, kode negara, dan nomor pelanggan, tanpa spasi, tanda hubung, atau tanda kurung. Nomor Inggris yang ditulis sebagai 020 7946 0000 menjadi +442079460000. Pustaka seperti libphonenumber dapat mengurai format lokal jika negara catatan diketahui.
3. Kirim ke POST /api/v1/check. Satu nomor per permintaan. Tidak diperlukan pemilihan negara terpisah, karena kode negara adalah bagian dari nomor tersebut.
4. Tunggu respons sinkron. Hasilnya kembali dalam respons yang sama; tidak ada yang perlu di-polling.
5. Simpan hasil dengan tanggal pencarian. Data alokasi stabil untuk suatu rentang, tetapi mencatat kapan setiap pencarian dijalankan membuat audit menjadi sederhana.

Jika input ditolak karena formatnya, perbaiki nomor tersebut dan kirim ulang. Penolakan format tidak memberikan informasi apa pun tentang operator.

Membaca hasil yang selesai, kosong, dan tidak dapat ditentukan

Bug integrasi yang paling umum adalah memperlakukan tiga hasil berbeda sebagai satu hal yang sama. Lakukan percabangan pada kode bisnis terlebih dahulu, kemudian pada nilainya.

Dua aturan mengikuti tabel tersebut. Kedua, pemeriksaan yang tidak dapat ditentukan bukanlah hasil kosong yang sukses, jadi jangan pernah menulis kolom kosong darinya ke dalam CRM Anda. Pencarian yang gagal atau tidak dapat ditentukan tidak dikenakan biaya, sementara pencarian yang selesai akan dikenakan biaya, meskipun kolomnya kosong.

Kolom opsional seperti operator pendukung, wilayah, atau kota mungkin kosong pada hasil yang sebenarnya lengkap. Rancang skema Anda agar setiap kolom dapat bernilai null secara independen.

Menangani timeout, konkurensi, dan saldo

API publik mendokumentasikan serangkaian kontrol penggunaan kecil, bukan kuota per menit. Sebuah akun memiliki lima slot in-flight bersama untuk permintaan sinkron, dan hanya satu permintaan multi yang dapat berjalan dalam satu waktu. Permintaan tunggal memiliki batas timeout yang didokumentasikan selama 60 detik, jadi atur timeout klien HTTP Anda sedikit di atas itu, bukan hanya beberapa detik.

Penanganan praktis:

• Antre alih-alih membanjiri. Jika pekerjaan pendaftaran atau impor Anda menghasilkan lonjakan, pertahankan kumpulan pekerja kecil agar tidak lebih dari lima pencarian yang sedang berjalan.
• Coba lagi hasil yang tidak dapat ditentukan dengan jeda. Gunakan penundaan dan batas percobaan ulang; percobaan ulang segera yang berulang jarang membantu.
• Catat kode bisnis dan pesan. Keduanya menjelaskan kegagalan jauh lebih baik daripada sekadar status HTTP.
• Baca saldo tanpa membelanjakannya. GET /api/v1/balance mengembalikan saldo yang tersisa tanpa biaya, yang cocok untuk pemeriksaan sebelum pekerjaan besar.

Untuk batas saat ini pada akun Anda, periksa dokumentasi API alih-alih melakukan hard-coding pada asumsi; API tidak memublikasikan batas permintaan harian yang tetap.

Kapan harus beralih ke POST /api/v1/batch-check atau tugas file

Rute satu nomor cocok untuk pekerjaan berbasis peristiwa: pengiriman formulir, catatan CRM baru, agen dukungan yang memeriksa satu kontak. Setelah suatu pekerjaan menangani beberapa nomor sekaligus secara rutin, satu panggilan per nomor akan menambah overhead.

• POST /api/v1/batch-check menerima 1 hingga 100 nomor E.164 dalam satu permintaan sinkron, dan nomor tersebut dapat berasal dari negara yang berbeda. Hasil kembali dalam urutan yang sama dengan input, sehingga Anda dapat memetakan setiap baris kembali berdasarkan posisinya. Setiap baris membawa flag exists; false berarti tidak ada hasil normal untuk baris tersebut, bukan berarti nomor tersebut tidak valid atau terputus. Jika permintaan multi mengalami timeout, seluruh permintaan gagal tanpa hasil parsial dan jumlah yang dicadangkan dikembalikan sepenuhnya, jadi jaga agar batch tetap sederhana dan coba lagi batch tersebut.
• Dasbor menerima hingga 500 nomor untuk pencarian multi sinkron tanpa kode.
• Tugas file massal cocok untuk seluruh daftar: unggahan asinkron file TXT atau CSV untuk satu negara yang dipilih, di-polling hingga satu CSV siap. Batas per produk berlaku; lihat dokumentasi API.

Pencarian yang sama juga tersedia bagi asisten AI melalui endpoint MCP resmi, yang mencakup pemeriksaan tunggal dan multi tetapi tidak mencakup tugas file.

FAQ

Bagaimana tim dapat membedakan hasil operator kosong dari pencarian yang gagal?

Periksa kode bisnis sebelum membaca nilai apa pun. Kode sukses dengan kolom operator kosong adalah pencarian yang selesai dan harus disimpan sebagai tidak tersedia. Kode bukan nol berarti pemeriksaan tidak dapat ditentukan atau gagal; tidak ada yang boleh ditulis sebagai hasil, dan catatan dapat dicoba lagi nanti atau dikirim untuk ditinjau. Menjaga kedua jalur ini tetap terpisah menghindari penandaan catatan yang baik sebagai data yang hilang.

Apakah API pencarian operator menunjukkan jaringan yang digunakan nomor tersebut saat ini?

Tidak. Nilai operator adalah operator tempat rentang nomor tersebut dialokasikan secara asli. Setelah pelanggan melakukan porting nomor tersebut, operator asli itu tetap sama dalam hasil meskipun layanan telah pindah ke tempat lain. Tim yang memerlukan konteks alokasi untuk pengelompokan, pengujian perutean, atau peninjauan dapat menggunakannya secara langsung; ini tidak boleh diperlakukan sebagai jaringan yang melayani saat ini atau sebagai kemampuan untuk dihubungi.

Haruskah frontend memanggil API pencarian operator secara langsung?

Tidak seharusnya. Header X-API-Key memberikan akses ke saldo akun, jadi panggilan harus dilakukan di server tepercaya. Pola umum adalah frontend mengirimkan nomor telepon ke backend Anda sendiri, yang menormalisasinya ke E.164, memanggil POST /api/v1/check, menyimpan hasilnya, dan hanya mengembalikan apa yang perlu ditampilkan oleh antarmuka.

Pelajari Lebih Lanjut

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

• Lihat dokumentasi produk →
• Bicara dengan tim →