API di Convalida e Formattazione del Numero di Telefono

L'API di convalida dei numeri di telefono è supportata in 242 paesi.

L'API di Convalida e Formattazione del Numero di Telefono ti consente di elaborare facilmente i numeri di telefono inseriti dagli utenti in una vasta gamma di formati. Che l'input sia irregolare come 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309 o semplicemente 2128675309, la nostra API rileverà intelligentemente la struttura e restituirà una versione standardizzata.

Questo strumento converte automaticamente l'input fornito nel formato E.164, che è lo standard riconosciuto a livello globale per i numeri di telefono internazionali. Ad esempio, +1 212 867 5309 viene restituito come +12128675309, rendendolo adatto per sistemi di chiamata internazionali e integrazioni.

Oltre alla formattazione, l'API fornisce capacità dettagliate di convalida del numero di telefono. Verifica se il numero è isValid: true — il che significa che è valido secondo i piani di numerazione nazionali. Fornisce anche un controllo isPossible: true, che indica se un numero potrebbe potenzialmente esistere anche se non è attualmente assegnato. Questo è utile per la pre-validazione prima del salvataggio o dell'elaborazione.

Il parametro numberType aiuta a identificare se il numero di telefono è un numero mobile, fisso o VoIP. Questo è particolarmente utile in scenari in cui vuoi consentire solo numeri mobili per la verifica tramite SMS o numeri fissi per i contatti aziendali.

Con il supporto per il riconoscimento del prefisso, l'API può anche rilevare l'origine geografica del numero. Ad esempio, un numero che inizia con il prefisso 212 viene automaticamente associato a New York City (Manhattan). Questa funzionalità è perfetta per applicazioni che richiedono segmentazione o analisi basate sulla posizione.

Ogni numero è anche associato a metadati a livello di paese, come il codice regione ISO (ad esempio, US) e il codice paese numerico (ad esempio, 1), consentendo logiche e formati di visualizzazione specifici per regione nelle tue applicazioni.

✅ Risposta dell'API

Esempio di risposta JSON:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Stati Uniti",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

Prova tu stesso l'API di Convalida del Numero

Utilizzo Base

Invia un numero di telefono al seguente endpoint:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

Puoi ottenere la tua chiave API giornaliera gratuita con 200 crediti da questo link.

Parametro Address

L'API supporta anche un parametro facoltativo address, molto utile nei casi in cui il numero di telefono è fornito senza prefisso internazionale. Questo campo aiuta il sistema a rilevare la regione desiderata e analizzare correttamente il numero. Ad esempio, se il numero è 2128675309 e non è specificato un prefisso, impostare address=US, address=United States o anche address=New York aiuta l'API a determinare che il numero appartiene agli Stati Uniti.

Il parametro address accetta input in diversi formati, inclusi:

• Codici ISO 3166-1 alpha-2 come US, DE o TR
• Nomi di paese come Germania, Turchia o America
• Nomi di città o regioni come Berlino, Istanbul o New York

Anche se facoltativo, address diventa obbligatorio se il numero non inizia con il segno più e un codice internazionale (es. +1, +44, +90). Senza queste informazioni contestuali, l'API potrebbe non essere in grado di interpretare correttamente il formato nazionale.

Esempio con parametro address:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

Campi della Risposta

Valori del Tipo di Numero

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

API di Convalida del Numero tramite Richiesta POST

Puoi utilizzare il metodo POST per convalidare un numero di telefono degli Stati Uniti. È sufficiente fornire il numero nel formato E.164, nazionale o internazionale insieme al paese o indirizzo. La tua chiave API deve essere inviata come token Bearer.

Esempio con cURL

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

Esempio cURL in PHP

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Esempio di fetch in JavaScript

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Esempio con requests in Python

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Librerie Client

Per semplificare ulteriormente l'integrazione, offriamo una serie di librerie client ufficiali e supportate dalla community per diversi linguaggi di programmazione. Queste librerie ti consentono di interagire con gli endpoint di GenderAPI — come l'API di Convalida del Numero di Telefono — senza dover gestire manualmente richieste HTTP o il parsing del JSON. Ti basta scegliere la libreria adatta al tuo ambiente, installarla e iniziare a inviare richieste con una configurazione minima.

Puoi trovare le librerie client disponibili e le istruzioni di installazione alla seguente pagina:
https://www.genderapi.io/it/docs-client-libraries

Domande Frequenti (FAQ)

1. Cos'è l'API di Convalida e Formattazione del Numero di Telefono?

L'API di Convalida e Formattazione del Numero di Telefono è uno strumento che consente di convalidare, formattare e analizzare numeri di telefono da tutto il mondo. Può convertire i numeri nel formato standardizzato E.164 e determinare metadati come regione, tipo (mobile/fisso), validità e altro ancora.

2. A cosa serve la Convalida del Numero?

Serve per verificare se un numero è valido, formattarlo per l'uso internazionale, identificare il tipo (es. mobile, VoIP), rilevare metadati regionali e garantire input puliti e standardizzati per CRM, strumenti di marketing o iscrizioni utente.

3. Quanti paesi sono supportati?

L'API supporta numeri di telefono da 242 paesi e territori in tutto il mondo. Questo garantisce una copertura globale per qualsiasi applicazione internazionale o regionale.

4. Quali formati sono supportati?

L'API accetta numeri in vari formati come nazionale, internazionale o E.164. Li rileva e normalizza automaticamente nel formato corretto.

5. Cosa succede se ometto il parametro country o address?

Se il numero non inizia con un '+' e non viene fornito un valore per country/address, l'API potrebbe non interpretare correttamente il numero. Si consiglia di includere il parametro address (come US, United States o New York).

6. L'API può rilevare il tipo di numero?

Sì. L'API restituisce il campo numberType, che indica se il numero è MOBILE, FIXED_LINE, VOIP, ecc.

7. Qual è la differenza tra isValid e isPossible?

isValid significa che il numero è ufficialmente assegnato e conforme alle regole regionali. isPossible verifica se il numero potrebbe teoricamente esistere in base alla sua struttura, anche se non è ancora assegnato.

8. Che tipo di risposta restituisce l'API?

Una risposta di successo include lo stato, le varianti formattate del numero (nazionale, internazionale, E.164), dati sulla regione, tipo di numero, uso dei crediti e altro. Consulta la sezione dell'esempio di risposta per vedere l'output completo.

9. Come devo inviare la mia chiave API?

Per richieste GET, aggiungi la chiave come ?key=YOUR_API_KEY. Per richieste POST, usa il token Bearer nell’header come segue:
"Authorization: Bearer YOUR_API_KEY".

10. Cosa significa una risposta status: false?

Significa che la richiesta è fallita. Il campo message conterrà il motivo dettagliato dell'errore, come parametri mancanti, numero non valido o crediti insufficienti.

11. Sono ammessi caratteri speciali o spazi nell’input?

Sì, ma devono essere codificati in formato URL per le richieste GET. Ad esempio, usa %20 invece di uno spazio. Consulta la sezione di avviso sopra per un uso corretto.

12. Posso usare indirizzi in formati o lingue diverse?

Sì. Oltre ai codici ISO 3166-1 alpha-2 (come US, DE, TR), il parametro address accetta anche nomi di paesi o città — anche in lingue diverse. L'API utilizza un’AI integrata per rilevare e interpretare correttamente il paese o la regione. Ad esempio:

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

Tutti questi input verranno correttamente associati ai rispettivi paesi o regioni dall'API senza problemi.