Dividere un nome completo in nome e cognome
Un campo nome combinato, una chiamata API, due campi puliti — le particelle, i titoli e l'ordine invertito che mandano in crisi una divisione scritta a mano sono già gestiti, e il genere è nella stessa risposta.
La risposta breve
- Invia il campo combinato e ricevi first_name e last_name — più il genere, l'accuratezza e il numero di campioni, nella stessa risposta, per un credit.
- Le particelle nobiliari («van der», «von den», «de la») e i titoli accademici e professionali vengono gestiti invece di far inciampare — e anche un «Rossi, Andrea» invertito si risolve, dai dati dei nomi e non dalla virgola.
- Dove entrambe le metà potrebbero essere l'una o l'altra, la decisione viene da quanto spesso ogni parte compare come nome rispetto a quanto spesso compare come cognome — non dalla sua posizione nella stringa.
- La modalità strict restituisce un cognome vuoto invece di un'ipotesi quando il cognome non è nel database, così vedi il buco.
Perché dividere allo spazio non funziona
Quasi ogni codebase ne ha una versione: prendi il campo nome, dividi agli spazi, il primo elemento è il nome, l'ultimo il cognome. Passa la revisione perché i dati di test sono inglesi, e va storto in silenzio con il primo cliente che non lo è.
Quello che costa è il modo in cui fallisce. Nulla solleva un'eccezione. Ti ritrovi un database pieno di persone il cui cognome è «van», un invio massivo che le saluta così, e nessuna riga di log che indichi la causa.
Cosa decide la divisione
Quattro cose, in quest'ordine — e l'ultima è quella che una divisione basata su regole non può avere, perché richiede di sapere come i nomi sono davvero distribuiti.
- I titoli vanno via per primi. «Prof. Dr.», «Dipl.-Ing.», «Managing Director» e il resto di un elenco mantenuto vengono rimossi prima di decidere qualsiasi altra cosa, così non finiscono mai in un campo nome.
- Le particelle restano con il cognome. «van», «van der», «van den», «von», «von der», «de», «de la», «du», «le», «di», «des» e le loro vicine vengono riconosciute come parte del cognome a cui appartengono.
- Alla punteggiatura non si affida l'ordine. La virgola in «Rossi, Andrea» viene rimossa insieme ai titoli, e l'ordine viene poi letto dai dati dei nomi — una virgola è un'abitudine di formattazione, e molti elenchi la usano in modo incoerente. Nel caricamento CSV ed Excel puoi invece indicare l'ordine della colonna, e un ordine indicato viene usato così com'è.
- L'ambiguità la risolvono i dati. Ogni parte candidata viene cercata sia nel database dei nomi sia in quello dei cognomi, e la parte che si comporta molto più da cognome che da nome è il cognome.
Passa un codice paese e lo stesso confronto avviene con quel paese invece che con tutti i paesi insieme — è quello che vuoi quando sai già da dove viene l'elenco.
Come chiamarlo
Due endpoint fanno questo, e quale ti serve dipende dal fatto che ti serva la modalità strict.
v2 — l'API attuale
POST https://gender-api.com/v2/gender/by-full-name
{ "full_name": "Anna van der Berg", "country": "NL" }{
"result_found": true,
"first_name": "Anna",
"last_name": "van der Berg",
"gender": "female",
"probability": 0.98,
"details": { "credits_used": 1, "samples": 8961, "duration": "33ms" }
}v1 — quando ti serve la modalità strict
La modalità strict esiste solo sull'endpoint di divisione v1. Se un cognome vuoto conta più per te che stare sull'API più recente, usa questo.
GET https://gender-api.com/get?split=Anna%20van%20der%20Berg&strict=true&key=…- referenza v2 nome completo — campi, errori, descrizione OpenAPI.
- referenza v1 divisione — il parametro strict e le sue risposte esatte.
- Client ufficiali per PHP, Python, Node, Java, Go, Ruby, Rust, Perl e .NET.
Prima di tutto: quella colonna contiene davvero nomi completi?
Utile saperlo prima di elaborare un file che non hai creato tu. Invia un campione di massimo 100 valori e ricevi se sembrano nomi completi — e non costa credits.
POST https://gender-api.com/v2/name-format-detect
{ "names": ["Sophie Jones", "Lorenzo Carlos", "Anna van der Berg"] }{
"is_fullname": true,
"fullname_probability": 1,
"validHints": [ … ]
}Sia chiaro cosa misura: fullname_probability è la quota dei valori inviati che ha più di una parola, e is_fullname è quella quota sopra 0,6. È un giudizio sulla colonna, non su ogni singolo nome — esattamente quello che ti serve per decidere se dividere, e non un sostituto della divisione stessa.
Anche una colonna mista è una risposta valida: certi elenchi contengono «Thomas» e «John Smith» affiancati, e la divisione gestisce entrambi senza che tu li ordini prima.
Dove ha ancora bisogno del tuo aiuto
Una divisione che dicesse di gestire ogni nome del mondo mentirebbe. Questi sono i casi in cui nessuna regola risolve la stringa da sola.
Se controlli il modulo, la soluzione più economica non è affatto un'API: due campi invece di uno, o un'indicazione che il formato è «nome, cognome». Tutto quello che segue vale per quando non lo controlli.
- Cognome per primo. Con o senza virgola, vince la lettura che i dati dei nomi sostengono rispetto a una regola sulla posizione — e ha ragione molto più spesso di quanto sbagli, ma non è una garanzia. Se sai che tutta la colonna ha il cognome per primo, indicalo nel caricamento invece di affidarti alla punteggiatura.
- Nomi di una sola parola. Un mononimo non ha un cognome da trovare. Il cognome torna vuoto invece di tagliare in due il nome.
- Traslitterazione incoerente. Lo stesso nome scritto in tre modi in un elenco si risolve come tre nomi, perché nei dati è esattamente questo.
- Nomi doppi senza trattino. «Anna Maria» resta unito dove i dati lo sostengono, ma un elenco che mescola «Anna Maria Rossi» e «Anna Rossi» non sarà uniforme.
In tutti quattro i casi un codice paese restringe il problema, e la modalità strict rende visibili le righe incerte invece che silenziosamente plausibili. Un campo vuoto che puoi filtrare vale più di uno sbagliato che non noti.
Un'intera colonna in una volta
Se i nomi sono in un foglio di calcolo e non in un'applicazione, non ti serve l'API. Carica il file, indica la colonna con i nomi combinati, e le parti divise tornano come nuove colonne accanto ai tuoi dati — fino a 10,000,000 righe per CSV o 100,000 per cartella di lavoro Excel, e la tua cartella torna intatta.
- Carica un file CSV o Excel — senza codice, con la formattazione originale conservata.
- Determinazione del genere in massa — i limiti, il prezzo a volume e le risposte per gli acquisti.
- Lavori in un foglio di calcolo o in un CRM? Ci sono integrazioni già pronte per Excel, Google Sheets, Shopify, HubSpot, Salesforce, Zapier e altri.
Domande frequenti
Perché non dividere semplicemente allo spazio?
Perché lo spazio non è il confine. «Anna van der Berg» dà il cognome «van» al primo spazio e il nome «Anna van der» all'ultimo. Sono entrambi sbagliati, entrambi sembrano perfetti in un test con nomi inglesi, ed entrambi falliscono in silenzio nel momento in cui arriva un cognome olandese, tedesco, francese, spagnolo o portoghese.
Cosa decide dove avviene la divisione?
Prima vengono rimossi i titoli noti, e le particelle nobiliari come «van der», «von den» e «de la» restano con il cognome. Dopo si soppesa quanto spesso ogni parte compare come nome rispetto a quanto spesso compare come cognome — quindi non è la posizione della parola a deciderlo, e nemmeno la punteggiatura: una virgola viene rimossa insieme ai titoli, non letta come indicatore di «cognome per primo». Nel caricamento CSV ed Excel puoi indicare direttamente l'ordine della colonna, e allora viene usato così com'è.
Cosa succede se il cognome non è nel database?
È a questo che serve la modalità strict, sull'endpoint v1. Con la modalità strict attiva, il cognome torna vuoto invece che indovinato, quindi il buco è visibile nei tuoi dati. Senza di essa viene comunque estratto un cognome, per quanto possibile.
Mi dà anche il genere?
Sì, nella stessa risposta e per lo stesso credit — insieme al numero di campioni e all'accuratezza che c'è dietro. Dividere il nome e determinarne il genere è una chiamata, non due.
Come faccio a sapere se la mia colonna contiene davvero nomi completi?
Invia un campione di massimo 100 valori all'endpoint name-format-detect. Non costa credits e ti dice se la colonna sembra contenere nomi completi, nomi di battesimo o un misto — utile prima di decidere come elaborare il file.
Quanto costa la divisione?
Un credit per nome, come una semplice determinazione del genere, da €0.35 per 1.000. I credits si acquistano in anticipo e non scadono.
Funziona con nomi non occidentali?
In parte, ed è meglio conoscere i limiti. I nomi scritti con il cognome per primo senza separatore, i nomi di una sola parola e i nomi traslitterati in modo incoerente sono i casi difficili — nessuna regola li risolve dalla sola stringa. Inviare un codice paese aiuta, perché la ricerca soppesa allora le parti rispetto a quel paese invece che rispetto a tutto.
PROVALO SUI NOMI CHE MANDANO IN CRISI LA TUA DIVISIONE
100 richieste gratuite al mese, senza carta di credito. Prendi le venti righe che il tuo codice attuale sbaglia e inizia da quelle.
Documentazione dell'API · Carica invece un file · Fai una domanda
