Nazionalità da un nome: cosa un nome può dirti e cosa no
Una chiamata API trasforma un nome o un cognome in un elenco ordinato dei paesi da cui viene, con una probabilità su ciascuno. Risponde a una domanda sul nome — che è una domanda diversa da dove vive la persona, e diversa ancora da chi è.
La risposta breve
- Ottieni un elenco ordinato di massimo 25 paesi, ciascuno con una probabilità, un codice ISO, un nome di paese e, dove il paese li ha registrati, la sua regione continentale e statistica.
- La stessa risposta contiene anche il genere, la lingua di origine, il significato del nome e la sua distribuzione tra i gruppi etnici, da un database che copre 192 paesi.
- Costa 2 credits per nome — il doppio di una semplice determinazione del genere, perché è una richiesta più pesante. I credits si acquistano in anticipo e non scadono.
- È una statistica sul nome, non un'affermazione sulla persona. Usalo per le formule di saluto, l'analisi aggregata e la qualità dei dati — non per decidere qualcosa su una singola persona.
Da dove viene il numero?
Qui non tira a indovinare nessun modello, e nulla viene generato. La probabilità è aritmetica su record che abbiamo davvero, ed è per questo che lo stesso nome restituisce lo stesso elenco oggi, il mese prossimo e l'anno prossimo.
Entrano due segnali. Il primo è come i record di quel nome si distribuiscono tra i paesi — un nome che abbiamo soprattutto dalla Polonia tende al polacco. Il secondo è quanto è grande ognuna di quelle popolazioni, e impedisce a un paese piccolo con un nome ben campionato di superare un paese grande per solo volume. I due vengono mediati per paese, tutto ciò che sta sotto l'uno per cento viene scartato, e quel che resta viene ordinato.
Poiché è una distribuzione, un nome comune in due paesi risponde con due paesi invece di scegliere un vincitore. È proprio questa la parte utile: la forma dell'elenco ti dice quanto puoi fidarti della prima voce.
Cosa torna
Un POST, un nome, una risposta. L'elenco qui sotto è accorciato; quello vero arriva ai 25 paesi più probabili.
POST https://gender-api.com/v2/country-of-origin
{ "first_name": "Johann" }{
"result_found": true,
"first_name": "Johann",
"gender": "male",
"probability": 0.9,
"language_of_origin": "Germanic",
"meaning": "…",
"country_of_origin": [
{
"country_name": "Germany",
"country": "DE",
"probability": 0.52,
"continental_region": "Europe",
"statistical_region": "Western Europe"
},
{
"country_name": "Austria",
"country": "AT",
"probability": 0.48,
"continental_region": "Europe",
"statistical_region": "Western Europe"
}
],
"ethnicity": {
"id": "GERMANIC",
"name": "Germanic (German, Austrian, Swiss)",
"distribution": [ … ]
},
"details": { "credits_used": 2, "samples": 890, "duration": "414ms" }
}Nota i due campi che rendono la risposta verificabile: samples ti dice su quanti record si basa, e credits_used conferma i due credits. Una risposta con pochi campioni non ti viene nascosta.
- Con continental_region e statistical_region puoi aggregare l'elenco per regione senza mantenere una tua tabella di corrispondenza.
- La risposta contiene anche un link a una mappa interattiva di quel nome, il modo più rapido per controllare un risultato a occhio.
- Ogni campo è documentato nella referenza v2.
L'origine non è la residenza
È il fraintendimento più frequente, e va in entrambe le direzioni. Due campi diversi, due significati diversi, direzioni opposte.
| Domanda | Il paese che invii | Il paese che ricevi |
|---|---|---|
| Campo | country, locale, ip |
country_of_origin |
| Significa | Dove si trova la persona ora | Da dove viene il nome |
| Cambia la risposta sul genere | Sì — Andrea è maschile in Italia e femminile in Germania | No — è un output, non un input |
| Di solito lo sai già | Sì — dall'indirizzo di spedizione, dal dominio o dall'IP | No — è proprio questo che stai comprando |
| Credits | Gratis — un parametro, non una richiesta | 2 per nome |
Cosa non è
Un nome è un indizio su un nome. Trattarlo come un indizio su una persona è il punto in cui questo tipo di dati va a rotoli, quindi vale la pena essere diretti sui limiti prima di costruirci sopra.
Una persona di nome Nguyen può essere nata a Melbourne, e una persona di nome Smith può non aver mai messo piede in un paese anglofono. L'endpoint risponde a «da dove viene questo nome», e quella è l'unica domanda a cui risponde.
- Non è una nazionalità, né una cittadinanza, né un luogo di nascita — e non è prova di nessuno dei tre.
- Non è l'etnia della persona. La distribuzione etnica descrive come il nome si distribuisce tra i gruppi: una proprietà del nome.
- Non dovrebbe decidere nulla su una singola persona — né un prezzo, né una candidatura, né un punteggio di rischio. I dati che indicano l'origine etnica sono una categoria particolare ai sensi dell'articolo 9 del GDPR, e quella decisione è tua come titolare del trattamento, non nostra.
- Non è un'ipotesi. Dove abbiamo troppo poco, result_found vale false e il numero di campioni lo dice, invece di inventare un paese plausibile per riempire il campo.
Da parte nostra: siamo un'azienda tedesca, tutti i server sono in Germania, i dati vengono trattati all'interno dell'UE, e puoi richiedere un accordo sul trattamento dei dati dal tuo account. Il quadro completo è nella panoramica sulla privacy.
A cosa serve davvero
- Azzeccare la formula di saluto. Sapere che un nome è italiano e non tedesco è ciò che trasforma «Andrea» dal saluto sbagliato a quello giusto — e la determinazione del genere nella stessa risposta è la parte che lo applica.
- Analisi di mercato e di pubblico in forma aggregata. In quale lingua tradurre una campagna, quali regioni una mailing list raggiunge davvero, dove è cresciuta una base clienti.
- Qualità dei dati. Un elenco in cui la distribuzione delle origini cambia forma all'improvviso significa di solito che un'importazione è andata male, non che il pubblico si è spostato.
- Ricerca e demografia, dove una distribuzione a livello di nome su un'intera coorte è l'unità di analisi e non si trae alcuna conclusione individuale.
- Traslitterazione e abbinamento, dove conoscere la probabile origine di un nome restringe le sue grafie plausibili.
Eseguirlo su un elenco
La forma batch accetta fino a 100 nomi per richiesta, senza limite sul numero di richieste. Il payload è un semplice array JSON.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Al posto di un nome di battesimo va bene anche un nome completo o un indirizzo e-mail — prima viene estratto il nome, poi viene risolta l'origine.
- Client ufficiali per PHP, Python, Node, Java, Go, Ruby, Rust, Perl e .NET.
- Per un elenco una volta sola invece di un'integrazione, vedi determinazione del genere in massa — gli stessi credits, senza codice.
- Ogni campo, ogni errore e una descrizione OpenAPI: la referenza v2.
Domande frequenti
Puoi dirmi la nazionalità di una persona dal suo nome?
No, e nessun servizio onesto può farlo. Quello che ottieni è dove il nome compare e con quanta forza, ordinato per paese — una statistica sul nome, non un fatto sulla persona che lo porta. Molte persone portano un nome la cui origine non ha nulla a che vedere con il loro luogo di nascita.
Cosa restituisce l'endpoint?
Un elenco ordinato di massimo 25 paesi, ciascuno con una probabilità, un codice paese ISO, un nome di paese e — dove il paese li ha registrati — la sua regione continentale e statistica. La stessa risposta contiene anche il genere, la lingua di origine, il significato del nome e la sua distribuzione tra i gruppi etnici.
Come viene calcolata la probabilità?
Da due segnali: quale quota dei record che abbiamo per quel nome viene da ciascun paese, e quanto è grande ognuna di quelle popolazioni. I due vengono mediati per paese, i paesi all'uno per cento o meno vengono scartati, e il resto viene ordinato. Ogni valore è una quota del totale e non un punteggio del paese preso da solo — leggili quindi gli uni rispetto agli altri. Non daranno esattamente 1: tutto quello che sta sotto l'uno per cento resta fuori, e anche tutto quello che viene dopo il venticinquesimo paese.
Quanto costa una richiesta di paese di origine?
Due credits per nome, perché è una richiesta più pesante di una semplice determinazione del genere. I credits partono da €0.35 per 1.000, si acquistano in anticipo e non scadono.
È la stessa cosa del parametro country che invio?
No — sono direzioni opposte. Il country, locale o ip che invii descrive dove si trova la persona ora e cambia quale genere viene restituito. Il paese di origine che ricevi descrive da dove viene il nome e non dipende da dove vive la persona.
Posso farci passare un elenco intero?
Sì. La variante batch accetta fino a 100 nomi per richiesta, senza limite sul numero di richieste, e lo stesso endpoint risponde altrettanto bene a un singolo nome.
Dedurre l'origine da un nome è lecito secondo il GDPR?
Dipende da cosa ne fai, ed è una tua decisione come titolare del trattamento, non nostra. I dati che indicano l'origine etnica sono una categoria particolare ai sensi dell'articolo 9, quindi usarli per prendere decisioni su singole persone richiede una base giuridica che tu possa dimostrare. Le analisi aggregate e le formule di saluto corrette sono gli usi ordinari. Siamo un'azienda tedesca, tutti i server sono in Germania, e puoi richiedere un accordo sul trattamento dei dati dal tuo account.
PROVALO SU NOMI CHE GIÀ CONOSCI
100 richieste gratuite al mese, senza carta di credito. Inizia con nomi la cui origine puoi verificare da te — è il modo più rapido per capire cosa ti sta dicendo la distribuzione.
Documentazione dell'API · Elabora un elenco intero · Fai una domanda
