# Cercare un numero di telefono

Una sola chiamata risponde a cos'è un numero. Tutto qui richiede una chiave API con lo scope `lookup`.

## Eseguire una ricerca base

Invia il numero e nient'altro. La ricerca base viene addebitata una sola volta e risponde sempre con il paese, la rete servente, la rete emittente e un tipo di linea generico.

**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](/it-it/documentazione/guides/lookup/phone-numbers.ts.md) · [Python](/it-it/documentazione/guides/lookup/phone-numbers.py.md) · [Go](/it-it/documentazione/guides/lookup/phone-numbers.go.md) · [PHP](/it-it/documentazione/guides/lookup/phone-numbers.php.md) · [CLI](/it-it/documentazione/guides/lookup/phone-numbers.cli.md) · [MCP](/it-it/documentazione/guides/lookup/phone-numbers.mcp.md) · [cURL](/it-it/documentazione/guides/lookup/phone-numbers.curl.md)

## Come scrivere il numero

Invia il prefisso internazionale seguito dal numero nazionale. Il `+` iniziale è facoltativo e `00` funziona al suo posto, quindi `+31612345678`, `31612345678` e `0031612345678` sono tutti lo stesso numero.

Un numero scritto per la composizione nazionale, senza prefisso internazionale, viene rifiutato anziché interpretato. `0612345678` restituisce [`E22000`](/docs/api/errors/E22000), perché anteporre un prefisso internazionale identificherebbe un numero reale altrove e ti verrebbe addebitata la ricerca.

## Cosa risponde la ricerca base

`country_code` è il paese del numero, assente quando il numero non appartiene a un singolo paese, come nel caso di una numerazione non geografica.

`network_info` è la rete che serve il numero oggi, e `original_network_info` è la rete che ha assegnato la numerazione. I due valori differiscono quando il numero è stato portato, e in quel caso `flags` contiene `ported`.

`line_type` indica il tipo di linea del numero: `mobile`, `fixed_line`, `voip`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `m2m`, `service`, `other` o `unknown`. `unknown` significa che la piattaforma dell'operatore non ha una classificazione per la numerazione; `other` significa che ne ha una senza equivalente qui. Per il servizio allocato con maggiore precisione, richiedi la proprietà `classification`. Risponde da una fonte diversa con un vocabolario più ampio, ed è riportata separatamente così puoi sempre distinguere le due informazioni.

## Aggiungere proprietà

Indica le proprietà desiderate in `type`. Ciascuna viene fatturata separatamente e solo quando viene consegnata.

| Proprietà        | Cosa risponde                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| `classification` | Il servizio allocato preciso della numerazione: premium rate, satellite, M2M, telefono pubblico. |
| `porting`        | Quando il numero ha cambiato rete l'ultima volta, e ogni spostamento registrato.                 |
| `presence`       | Se il numero è attualmente attivo sulla rete.                                                    |
| `roaming`        | Se è in roaming, e su quale rete.                                                                |
| `sim_swap`       | Quando la SIM è stata cambiata l'ultima volta.                                                   |
| `score`          | Un punteggio di credibilità da 0 a 100.                                                          |

`classification`, `porting` e `score` leggono dati archiviati e rispondono rapidamente. `presence`, `roaming` e `sim_swap` interrogano la rete in tempo reale, quindi sono più lente e la loro copertura varia per operatore. Per queste ultime, aspettati `unavailable` o `inconclusive` più spesso che per quelle archiviate.

Due proprietà rispondono a domande che la ricerca base già tocca, con una risoluzione maggiore. `porting` fornisce la data e lo storico completo, mentre il flag `ported` della ricerca base indica solo se uno spostamento è mai avvenuto. `classification` risolve `line_type` nel servizio allocato esatto.

## Leggi lo stato prima del valore

Ogni blocco proprietà contiene uno `status`, e solo `ok` contiene un valore.

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

In quella risposta ti è stata addebitata la ricerca base e `classification`. Non ti è stato addebitato `score`.

Leggi `status` per primo e tratta qualsiasi valore diverso da `ok` come "not answered". È un vocabolario aperto, quindi un valore che non riconosci è uno stato futuro, non un errore.

Due blocchi riportano un intervallo anziché un valore esatto quando la rete non lo rilascia. `sim_swap` restituisce `min_days` e `max_days` al posto di `last_swapped_at` quando è noto solo un intervallo di recenza. `porting` imposta `last_ported_at_is_approximate` quando un registro riporta il periodo di uno spostamento ma non il giorno.

Un campo si legge come un risultato negativo ma è in realtà un risultato positivo: `porting.ported` impostato a `false` significa che il registro è stato consultato e non contiene spostamenti per questo numero, non che non è stato possibile verificare. Questa distinzione è il ruolo di `status`.

## Riprovare senza pagare due volte

Una ricerca viene fatturata, quindi una richiesta ripetuta non deve acquistare una seconda risposta. Invia un `Idempotency-Key` e la stessa richiesta riprodurrà la risposta archiviata anziché eseguire una nuova ricerca. Vedi [Idempotency](/docs/guides/idempotency).

La forma `GET` di questa operazione, che inserisce il numero nell'URL, non può includere una chiave di idempotenza. Usa la forma `POST` per tutto ciò che è automatizzato.

## Errori

| Codice                              | Cosa è successo                                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [`E22000`](/docs/api/errors/E22000) | Il numero non è un numero di telefono valido in formato internazionale. Non è stato addebitato nulla.         |
| [`E22001`](/docs/api/errors/E22001) | Il wallet dell'organizzazione non può coprire la ricerca. Ricaricalo e riprova. Non è stato addebitato nulla. |
| [`E22002`](/docs/api/errors/E22002) | La ricerca è temporaneamente non disponibile. Riprova con backoff. Non è stato addebitato nulla.              |

Una proprietà che fallisce non è un errore. Viene restituita come stato nel suo blocco, con la ricerca base servita insieme.

## Prossimi passi

- [Cerca un indirizzo email](/docs/guides/lookup/email-addresses) è l'altra metà di Lookup.
- [Riferimento API di Lookup](/docs/api/reference/create-phone-number-lookup) documenta ogni campo e ogni blocco proprietà.
- [Limiti di frequenza](/docs/guides/rate-limits) tratta il bucket `lookup` da cui attingono queste chiamate.
- [Verifica numero di telefono: controlla un numero prima di inviare](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) è un video che esegue una ricerca e aggiunge i controlli sulla rete in tempo reale.

## Related resources

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

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