API validazione e formattazione numeri di telefono

Dati telefonici globali

Un numero, un output coerente

Accetta input nazionali, internazionali e con formattazione irregolare, quindi restituisce formati standard e metadati di validazione per 242 paesi e territori.

Input originale+39 02 1234 5678

Output E.164+390212345678

ValidazioneisValid e isPossible

FormattazioneNazionale, internazionale ed E.164

ClassificazioneMobile, linea fissa, VoIP e altro

LocalizzazioneRegione, prefisso e località

Parametri di input

Numero e contesto geografico

Parametro	Requisito	Descrizione
`number`	Obbligatorio	Numero di telefono in formato nazionale, internazionale o E.164.
`address`	Condizionale	Codice paese ISO, nome del paese, città o regione usati per interpretare un numero nazionale.

Quando address diventa obbligatorio

Se number non inizia con + e un prefisso internazionale, fornisci un contesto comeIT, Italia oppure Milano.

ITItaliaMilanoNew YorkÉtats-Unis

GET

Autenticazione nella query string

Richiesta GET di base

cURL

curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B390212345678&address=IT"

Codifica URL: codifica + come %2B e gli spazi come %20. Usa le utility URL o URLSearchParams del tuo linguaggio invece di comporre manualmente la stringa.

POST

Autenticazione Bearer

Richiesta POST lato server

Invia il numero e l’indirizzo facoltativo in JSON, con la chiave API nell’header Authorization.

cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number":"+390212345678","address":"IT"}'

JavaScript

const response = await fetch("https://api.genderapi.io/api/phone", {
  method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ number: "+390212345678", address: "Italia" })
});

Risposta API

Validazione, formattazione e metadati

JSON

{
  "status": true, "remaining_credits": 15709, "expires": 0, "duration": "18ms",
  "regionCode": "IT", "countryCode": 39, "country": "Italy",
  "national": "02 1234 5678", "international": "+39 02 1234 5678", "e164": "+390212345678",
  "isValid": true, "isPossible": true, "numberType": "FIXED_LINE",
  "nationalSignificantNumber": "0212345678", "rawInput": "+39 02 1234 5678",
  "isGeographical": true, "areaCode": "02", "location": "Milan"
}

Campi della risposta

Campo	Tipo	Descrizione
`status`	boolean	Indica se la richiesta è stata completata correttamente.
`remaining_credits`	integer	Crediti disponibili dopo la richiesta.
`expires`	integer	Scadenza dei crediti come timestamp UNIX.
`duration`	string	Tempo di elaborazione sul server.
`regionCode`	string	Codice regione ISO 3166-1 alpha-2 rilevato.
`countryCode`	integer	Prefisso telefonico internazionale.
`country`	string	Nome del paese in formato leggibile.
`national`	string	Numero formattato per l’uso nazionale.
`international`	string	Numero formattato per la visualizzazione internazionale.
`e164`	string	Rappresentazione canonica E.164.
`isValid`	boolean	Indica se il numero rispetta le regole di validazione regionali.
`isPossible`	boolean	Indica se il numero potrebbe esistere in base alla sua struttura.
`numberType`	string	Categoria rilevata per il numero.
`nationalSignificantNumber`	string	Numero nazionale senza il prefisso internazionale.
`rawInput`	string	Numero originale inviato nella richiesta.
`isGeographical`	boolean	Indica se il numero può essere associato a un’area geografica.
`areaCode`	string	Prefisso locale rilevato.
`location`	string	Località associata al prefisso.

Riferimento per la classificazione

Valori del tipo di numero

FIXED_LINE

Linea fissa associata a una località geografica.

MOBILE

Numero di telefono mobile o cellulare.

FIXED_LINE_OR_MOBILE

Il piano di numerazione non distingue tra linea fissa e mobile.

TOLL_FREE

Numero verde con costo a carico del destinatario.

PREMIUM_RATE

Numero per servizi a tariffazione maggiorata.

SHARED_COST

Costo della chiamata condiviso tra chiamante e destinatario.

VOIP

Numero telefonico Voice over IP.

PERSONAL_NUMBER

Numero personale che può inoltrare le chiamate a un’altra linea.

PAGER

Numero per servizi cercapersone.

UAN

Numero di accesso universale usato come contatto aziendale condiviso.

VOICEMAIL

Numero dedicato all’accesso alla segreteria telefonica.

UNKNOWN

Non è stato possibile determinare la categoria del numero.

Domande frequenti

FAQ sull’API telefonica

Che cosa fa l’API di validazione telefonica?

Valida e normalizza i numeri di telefono, restituisce i formati nazionale, internazionale ed E.164 e identifica regione, tipo di numero e metadati geografici quando disponibili.

Qual è la differenza tra isValid e isPossible?

isValid verifica il numero rispetto alle regole di numerazione regionali; isPossible indica che la struttura potrebbe rappresentare un numero, anche quando la validità non può essere confermata.

Quando è obbligatorio address?

Fornisci address quando il numero non inizia con il segno più e il prefisso internazionale. Può essere un codice paese ISO, un paese, una città o una regione.

Come devono essere inviati i caratteri speciali?

Codifica per URL spazi, segni più e altri caratteri speciali nei parametri GET. Nei body JSON POST la codifica viene gestita dal client HTTP.

Riferimento successivo

Controlla utilizzo e quota

Utilizzo e quotaComprendi crediti e limiti →Librerie clientInstalla un pacchetto per la validazione telefonica →