Nationalitet ud fra et navn: hvad et navn kan og ikke kan sige
Ét API-kald gør et for- eller efternavn til en rangordnet liste over de lande, det kommer fra, med en sandsynlighed på hvert. Det svarer på et spørgsmål om navnet — og det er et andet spørgsmål end, hvor personen bor, og endnu et andet end, hvem personen er.
Det korte svar
- Du får en rangordnet liste med op til 25 lande, hvert med en sandsynlighed, en ISO-kode, et landenavn og, hvor landet har dem registreret, dets kontinentale og statistiske region.
- Samme svar indeholder også køn, oprindelsessprog, navnets betydning og dets fordeling på etniske grupper, fra en database med 192 lande.
- Det koster 2 credits pr. navn — dobbelt så meget som en almindelig kønsbestemmelse, fordi det er en tungere forespørgsel. Credits købes på forhånd og udløber ikke.
- Det er en statistik om navnet, ikke en påstand om personen. Brug det til tiltale, aggregeret analyse og datakvalitet — ikke til at afgøre noget om et enkelt menneske.
Hvor kommer tallet fra?
Her gætter ingen model, og intet bliver genereret. Sandsynligheden er regnestykker på poster, vi faktisk har — derfor giver samme navn samme liste i dag, næste måned og næste år.
To signaler går ind. Det første er, hvordan posterne for navnet er fordelt på landene — et navn vi mest har fra Polen, læner polsk. Det andet er, hvor stor hver af de befolkninger er, hvilket forhindrer et lille land med et velbelagt navn i at overhale et stort udelukkende på mængde. De to gennemsnitsberegnes pr. land, alt under én procent falder ud, og det, der er tilbage, sorteres.
Fordi det er en fordeling, svarer et navn, der er almindeligt i to lande, med to lande i stedet for at udpege en vinder. Netop det er det nyttige: listens form fortæller dig, hvor meget du kan stole på den første post.
Hvad du får tilbage
Én POST, ét navn, ét svar. Listen nedenfor er forkortet; den rigtige går til de 25 mest sandsynlige lande.
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" }
}Bemærk de to felter, der gør svaret efterprøveligt: samples fortæller, hvor mange poster det bygger på, og credits_used bekræfter de to credits. Et svar med få samples bliver ikke skjult for dig.
- Med continental_region og statistical_region kan du rulle listen op til region uden at vedligeholde din egen mapping.
- Svaret indeholder også et link til et interaktivt kort over navnet — den hurtigste måde at tjekke et resultat med øjnene.
- Hvert felt er dokumenteret i v2-referencen.
Oprindelse er ikke bopæl
Det er den absolut mest almindelige misforståelse, og den går begge veje. To forskellige felter, to forskellige betydninger, modsatte retninger.
| Spørgsmål | Landet du sender | Landet du får tilbage |
|---|---|---|
| Felt | country, locale, ip |
country_of_origin |
| Betyder | Hvor personen er nu | Hvor navnet kommer fra |
| Ændrer kønssvaret | Ja — Andrea er maskulint i Italien og feminint i Tyskland | Nej — det er output, ikke input |
| Normalt ved du det allerede | Ja — ud fra leveringsadressen, domænet eller IP-adressen | Nej — det er præcis det, du køber |
| Credits | Gratis — en parameter, ikke en forespørgsel | 2 pr. navn |
Hvad det ikke er
Et navn er bevis om et navn. At behandle det som bevis om en person er der, hvor den slags data går galt, så det er værd at være direkte om grænserne, før du bygger på det.
En person der hedder Nguyen kan være født i Melbourne, og en person der hedder Smith har måske aldrig sat sin fod i et engelsktalende land. Endpointet svarer på “hvor kommer dette navn fra”, og det er det eneste spørgsmål, det svarer på.
- Det er ikke en nationalitet, ikke et statsborgerskab og ikke et fødested — og ikke bevis for nogen af dem.
- Det er ikke personens etnicitet. Den etniske fordeling beskriver, hvordan navnet er spredt på grupper: en egenskab ved navnet.
- Det bør ikke afgøre noget om en enkeltperson — ikke en pris, ikke en ansøgning, ikke en risikoscore. Oplysninger, der peger på etnisk oprindelse, er en særlig kategori efter artikel 9 i GDPR, og den beslutning er din som dataansvarlig, ikke vores.
- Det er ikke et gæt. Hvor vi har for lidt, er result_found false, og antallet af samples siger det — i stedet for at der opfindes et plausibelt land for at udfylde feltet.
På vores side: vi er et tysk selskab, alle servere står i Tyskland, data behandles inden for EU, og en databehandleraftale kan bestilles i din konto. Det fulde billede står i privatlivsoversigten.
Hvad det faktisk bruges til
- At få tiltalen rigtig. At vide, at et navn er italiensk og ikke tysk, er det, der gør “Andrea” fra den forkerte hilsen til den rigtige — og kønsbestemmelsen i samme svar er den del, der handler på det.
- Markeds- og målgruppeanalyse på aggregeret niveau. Hvilket sprog en kampagne skal oversættes til, hvilke regioner en mailingliste faktisk rammer, hvor en kundebase er vokset.
- Datakvalitet. En liste, hvor oprindelsesfordelingen pludselig skifter form, betyder oftest, at et import gik galt, ikke at målgruppen er flyttet.
- Forskning og demografi, hvor en fordeling på navneniveau over en hel kohorte er analyseenheden, og der ikke drages konklusioner om enkeltpersoner.
- Translitteration og matchning, hvor kendskab til et navns sandsynlige oprindelse indsnævrer de plausible stavemåder.
At køre det over en liste
Batch-formen tager op til 100 navne pr. kald, uden loft over antallet af kald. Payloaden er et rent JSON-array.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- I stedet for et fornavn virker også et fuldt navn eller en e-mailadresse — navnet trækkes ud først, derefter afgøres oprindelsen.
- Officielle klienter til PHP, Python, Node, Java, Go, Ruby, Rust, Perl og .NET.
- Til en enkeltstående liste frem for en integration, se kønsbestemmelse i bulk — samme credits, ingen kode.
- Hvert felt, hver fejl og en OpenAPI-beskrivelse: v2-referencen.
Ofte stillede spørgsmål
Kan du se en persons nationalitet ud fra navnet?
Nej, og ingen hæderlig tjeneste kan det. Hvad du får, er hvor navnet forekommer og hvor stærkt, rangordnet efter land — en statistik om navnet, ikke et faktum om personen, der bærer det. Rigtig mange bærer et navn, hvis oprindelse intet har at gøre med, hvor de er født.
Hvad returnerer endpointet?
En rangordnet liste med op til 25 lande, hvert med en sandsynlighed, en ISO-landekode, et landenavn og — hvor landet har dem registreret — dets kontinentale og statistiske region. Samme svar indeholder også køn, oprindelsessprog, navnets betydning og dets fordeling på etniske grupper.
Hvordan beregnes sandsynligheden?
Ud fra to signaler: hvor stor en andel af de poster, vi har for navnet, der kommer fra hvert land, og hvor stor hver af de befolkninger er. De to gennemsnitsberegnes pr. land, lande på én procent eller mindre falder ud, og resten sorteres. Hver værdi er en andel af helheden og ikke en karakter for landet i sig selv — læs dem derfor i forhold til hinanden. De summer ikke til præcis 1: alt under én procent er udeladt, og alt efter det femogtyvende land også.
Hvad koster en forespørgsel om oprindelsesland?
To credits pr. navn, fordi det er en tungere forespørgsel end en almindelig kønsbestemmelse. Credits starter ved €0.35 pr. 1.000, købes på forhånd og udløber ikke.
Er det det samme som country-parameteren, jeg sender?
Nej — det er modsatte retninger. Den country, locale eller ip du sender, beskriver hvor personen er nu, og ændrer hvilket køn du får tilbage. Oprindelseslandet du får tilbage, beskriver hvor navnet kommer fra og afhænger ikke af, hvor personen bor.
Kan jeg køre en hel liste igennem?
Ja. Batch-varianten tager op til 100 navne pr. kald, uden loft over antallet af kald, og samme endpoint svarer lige så godt på ét navn.
Er det lovligt efter GDPR at udlede oprindelse ud fra et navn?
Det afhænger af, hvad du bruger det til, og det er din beslutning som dataansvarlig, ikke vores. Oplysninger, der peger på etnisk oprindelse, er en særlig kategori efter artikel 9, så at bruge dem til beslutninger om enkeltpersoner kræver et retsgrundlag, du kan påvise. Aggregerede analyser og korrekt tiltale er de almindelige anvendelser. Vi er et tysk selskab, alle servere står i Tyskland, og en databehandleraftale kan bestilles i din konto.
PRØV DET PÅ NAVNE DU ALLEREDE KENDER
100 gratis forespørgsler om måneden, uden kort. Start med navne, hvis oprindelse du selv kan tjekke — det er den hurtigste vej til at se, hvad fordelingen fortæller dig.
