# Mencari nomor telepon

Satu panggilan menjawab apa itu sebuah nomor. Semua yang ada di sini memerlukan kunci API dengan scope `lookup`.

## Jalankan pencarian dasar

Kirim nomor saja, tanpa parameter lain. Lookup dasar selalu ditagih satu kali, dan selalu menjawab negara, jaringan yang melayani, jaringan yang menerbitkan, serta jenis saluran secara umum.

**TypeScript**

```typescript
const answer = await bird.lookup.phoneNumber({
  phone_number: "+31612345678",
  type: ["classification", "score"],
});
console.log(answer.country_code, answer.line_type);
// Only a block whose status is ok carries a value, and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);
```

Examples: [TypeScript](/id-id/dokumentasi/guides/lookup/phone-numbers.ts.md) · [Python](/id-id/dokumentasi/guides/lookup/phone-numbers.py.md) · [Go](/id-id/dokumentasi/guides/lookup/phone-numbers.go.md) · [PHP](/id-id/dokumentasi/guides/lookup/phone-numbers.php.md) · [CLI](/id-id/dokumentasi/guides/lookup/phone-numbers.cli.md) · [MCP](/id-id/dokumentasi/guides/lookup/phone-numbers.mcp.md) · [cURL](/id-id/dokumentasi/guides/lookup/phone-numbers.curl.md)

## Cara menulis nomor

Kirim kode panggilan negara, lalu nomor nasional. Awalan `+` bersifat opsional dan `00` dapat digunakan sebagai gantinya, sehingga `+31612345678`, `31612345678`, dan `0031612345678` adalah nomor yang sama.

Nomor yang ditulis untuk panggilan dalam negeri, tanpa kode negara, ditolak alih-alih ditebak. `0612345678` mengembalikan [`E22000`](/docs/api/errors/E22000), karena menambahkan kode negara akan menunjuk nomor asli di tempat lain dan Anda ditagih untuk pencarian tersebut.

## Apa yang dijawab oleh pencarian dasar

`country_code` adalah negara nomor tersebut, tidak ada jika nomor tidak termasuk dalam satu negara tertentu, seperti pada rentang non-geografis.

`network_info` adalah jaringan yang melayani nomor saat ini, dan `original_network_info` adalah jaringan yang menerbitkan rentangnya. Keduanya berbeda jika nomor telah dipindahkan (porting), dan dalam kasus tersebut `flags` berisi `ported`.

`line_type` adalah jenis saluran nomor tersebut: `mobile`, `fixed_line`, `voip`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `m2m`, `service`, `other`, atau `unknown`. `unknown` berarti platform operator tidak memiliki klasifikasi untuk rentang tersebut; `other` berarti platform memiliki klasifikasi tetapi tidak ada padanan di sini. Untuk layanan teralokasi dengan presisi lebih tinggi, minta properti `classification`. Properti ini menjawab dari sumber berbeda dengan kosakata lebih luas, dan dilaporkan terpisah agar Anda selalu dapat membedakan keduanya.

## Tambahkan properti

Sebutkan properti yang Anda inginkan di `type`. Setiap properti ditagih terpisah dan hanya saat berhasil dikirim.

| Properti         | Apa yang dijawab                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `classification` | Layanan teralokasi yang tepat dari rentang tersebut: tarif premium, satelit, M2M, telepon umum. |
| `porting`        | Kapan nomor terakhir berpindah jaringan, dan setiap perpindahan yang tercatat.                  |
| `presence`       | Apakah nomor tersebut saat ini aktif di jaringan.                                               |
| `roaming`        | Apakah nomor sedang roaming, dan di jaringan mana.                                              |
| `sim_swap`       | Kapan SIM-nya terakhir diganti.                                                                 |
| `score`          | Skor kredibilitas dari 0 hingga 100.                                                            |

`classification`, `porting`, dan `score` membaca data tersimpan dan mengembalikan hasil dengan cepat. `presence`, `roaming`, dan `sim_swap` menjangkau jaringan langsung, sehingga lebih lambat dan cakupannya bervariasi menurut operator. Untuk properti ini, `unavailable` atau `inconclusive` lebih sering muncul dibandingkan properti yang tersimpan.

Dua properti menjawab pertanyaan yang sudah disinggung pencarian dasar, dengan resolusi lebih tinggi. `porting` memberikan tanggal dan riwayat lengkap, sedangkan flag `ported` pada pencarian dasar hanya menyatakan apakah perpindahan pernah terjadi. `classification` menerjemahkan `line_type` ke layanan teralokasi yang tepat.

## Baca status sebelum nilainya

Setiap blok properti memiliki `status`, dan hanya `ok` yang memiliki nilai.

```json
{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "unavailable"
  }
}
```

Dalam jawaban tersebut, Anda ditagih untuk pencarian dasar dan untuk `classification`. Anda tidak ditagih untuk `score`.

Baca `status` terlebih dahulu dan perlakukan apa pun selain `ok` sebagai "not answered". Kosakatanya terbuka, jadi nilai yang tidak Anda kenali adalah status baru, bukan kesalahan.

Dua blok melaporkan batas alih-alih angka pasti jika jaringan tidak merilisnya. `sim_swap` mengembalikan `min_days` dan `max_days` alih-alih `last_swapped_at` jika hanya rentang kebaruan yang diketahui. `porting` mengisi `last_ported_at_is_approximate` jika registri mencatat periode perpindahan tetapi bukan tanggal pastinya.

Satu field terbaca sebagai negatif tetapi sebenarnya temuan positif: `porting.ported` yang diisi `false` berarti registri sudah dikonsultasi dan tidak mencatat perpindahan untuk nomor ini, bukan berarti tidak ada yang bisa diperiksa. Pembedaan itulah fungsi `status`.

## Coba lagi tanpa membayar dua kali

Pencarian dikenakan biaya, jadi permintaan yang dicoba lagi tidak boleh membeli jawaban kedua. Kirim `Idempotency-Key` dan pengulangan permintaan yang sama akan memutar ulang jawaban tersimpan alih-alih menjalankan pencarian baru. Lihat [Idempotency](/docs/guides/idempotency).

Bentuk `GET` dari operasi ini, yang menempatkan nomor di URL, tidak dapat membawa kunci idempotensi. Gunakan bentuk `POST` untuk apa pun yang diotomatisasi.

## Error

| Kode                                | Apa yang terjadi                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`E22000`](/docs/api/errors/E22000) | Nomor tersebut bukan nomor telepon valid dalam format internasional. Tidak ada yang ditagih.           |
| [`E22001`](/docs/api/errors/E22001) | Saldo organisasi tidak mencukupi untuk pencarian ini. Isi ulang dan coba lagi. Tidak ada yang ditagih. |
| [`E22002`](/docs/api/errors/E22002) | Pencarian tidak tersedia untuk sementara. Coba lagi dengan backoff. Tidak ada yang ditagih.            |

Properti yang gagal bukan error. Properti tersebut dikembalikan sebagai status pada bloknya, dan pencarian dasar tetap disajikan bersamanya.

## Langkah selanjutnya

- [Cari alamat email](/docs/guides/lookup/email-addresses) adalah bagian lain dari Lookup.
- [Referensi API Lookup](/docs/api/reference/create-phone-number-lookup) mendokumentasikan setiap field dan setiap blok properti.
- [Pembatasan laju permintaan](/docs/guides/rate-limits) membahas bucket `lookup` yang digunakan panggilan ini.
- [Pencarian nomor telepon: periksa nomor sebelum Anda mengirim](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) adalah video yang menjalankan pencarian dan menambahkan pemeriksaan jaringan langsung.

## Related resources

- [Phone number lookup](/lookup-api) (product)

[Get an implementation brief](/learn/workspace?topic=lookup-phone)