Nationalitet ur ett namn: vad ett namn kan och inte kan säga
Ett API-anrop gör ett för- eller efternamn till en rangordnad lista över de länder det kommer från, med en sannolikhet på varje. Det svarar på en fråga om namnet — vilket är en annan fråga än var personen bor, och ännu en annan än vem personen är.
Det korta svaret
- Du får en rangordnad lista på upp till 25 länder, vart och ett med en sannolikhet, en ISO-kod, ett landsnamn och, där landet har dem registrerade, dess kontinentala och statistiska region.
- Samma svar innehåller också kön, ursprungsspråk, namnets betydelse och dess fördelning över etniska grupper, ur en databas som täcker 192 länder.
- Det kostar 2 credits per namn — dubbelt så mycket som en vanlig könsbestämning, eftersom det är en tyngre fråga. Credits köps i förväg och blir inte ogiltiga.
- Det är en statistik om namnet, inte ett påstående om personen. Använd det för tilltal, aggregerad analys och datakvalitet — inte för att avgöra något om en enskild människa.
Var kommer siffran ifrån?
Här gissar ingen modell, och inget genereras. Sannolikheten är aritmetik på poster vi verkligen har — därför ger samma namn samma lista i dag, nästa månad och nästa år.
Två signaler går in. Den första är hur posterna för namnet är fördelade över länderna — ett namn vi mest har från Polen lutar polskt. Den andra är hur stor var och en av de befolkningarna är, vilket hindrar ett litet land med ett välbelagt namn från att gå om ett stort land på ren volym. De två snittas per land, allt under en procent faller bort, och det som återstår sorteras.
Eftersom det är en fördelning svarar ett namn som är vanligt i två länder med två länder i stället för att utse en vinnare. Just det är det användbara: listans form säger dig hur mycket du kan lita på den första posten.
Vad du får tillbaka
En POST, ett namn, ett svar. Listan nedan är förkortad; den riktiga går till de 25 troligaste länderna.
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" }
}Lägg märke till de två fälten som gör svaret granskningsbart: samples säger hur många poster det vilar på, och credits_used bekräftar de två credits. Ett svar med få samples göms inte för dig.
- Med continental_region och statistical_region kan du rulla upp listan till region utan att underhålla en egen mappning.
- Svaret innehåller också en länk till en interaktiv karta över namnet — det snabbaste sättet att ögna igenom ett resultat.
- Varje fält är dokumenterat i v2-referensen.
Ursprung är inte bostadsort
Det här är det allra vanligaste missförståndet, och det går i båda riktningarna. Två olika fält, två olika betydelser, motsatta riktningar.
| Fråga | Landet du skickar | Landet du får tillbaka |
|---|---|---|
| Fält | country, locale, ip |
country_of_origin |
| Betyder | Var personen är nu | Var namnet kommer ifrån |
| Ändrar könssvaret | Ja — Andrea är maskulint i Italien och feminint i Tyskland | Nej — det är utdata, inte indata |
| Oftast vet du det redan | Ja — från leveransadressen, domänen eller IP-adressen | Nej — det är precis det du köper |
| Credits | Gratis — en parameter, inte en fråga | 2 per namn |
Vad det inte är
Ett namn är bevis om ett namn. Att behandla det som bevis om en person är där den här typen av data går fel, så det är värt att vara rakt på om gränserna innan du bygger på det.
En person som heter Nguyen kan vara född i Melbourne, och en person som heter Smith kanske aldrig har satt sin fot i ett engelskspråkigt land. Endpointen svarar på ”var kommer det här namnet ifrån”, och det är den enda frågan den svarar på.
- Det är ingen nationalitet, inget medborgarskap och ingen födelseort — och inget bevis för något av dem.
- Det är inte personens etnicitet. Den etniska fördelningen beskriver hur namnet är spritt över grupper: en egenskap hos namnet.
- Det bör inte avgöra något om en enskild person — inte ett pris, inte en ansökan, inte en riskpoäng. Uppgifter som pekar på etniskt ursprung är en särskild kategori enligt artikel 9 i GDPR, och det beslutet är ditt som personuppgiftsansvarig, inte vårt.
- Det är ingen gissning. Där vi har för lite är result_found false och antalet samples säger det — i stället för att hitta på ett rimligt land för att fylla fältet.
På vår sida: vi är ett tyskt företag, alla servrar står i Tyskland, data behandlas inom EU, och ett personuppgiftsbiträdesavtal kan begäras i ditt konto. Hela bilden finns i integritetsöversikten.
Vad det faktiskt används till
- Att få tilltalet rätt. Att veta att ett namn är italienskt och inte tyskt är det som gör ”Andrea” från fel hälsning till rätt — och könsbestämningen i samma svar är det som utför det.
- Marknads- och målgruppsanalys på aggregerad nivå. Vilket språk en kampanj ska översättas till, vilka regioner en sändlista faktiskt når, var en kundbas har vuxit.
- Datakvalitet. En lista där ursprungsfördelningen plötsligt ändrar form betyder oftast att en import gick fel, inte att publiken har flyttat.
- Forskning och demografi, där en fördelning på namnnivå över en hel kohort är analysenheten och ingen slutsats dras om enskilda personer.
- Translitterering och matchning, där kunskap om ett namns troliga ursprung snävar in de rimliga stavningarna.
Att köra det över en lista
Batch-formen tar upp till 100 namn per anrop, utan tak för antalet anrop. Nyttolasten är en ren JSON-array.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- I stället för ett förnamn fungerar också ett fullständigt namn eller en e-postadress — namnet plockas ut först, sedan löses ursprunget.
- Officiella klienter för PHP, Python, Node, Java, Go, Ruby, Rust, Perl och .NET.
- För en engångslista i stället för en integration, se könsbestämning i bulk — samma credits, ingen kod.
- Varje fält, varje fel och en OpenAPI-beskrivning: v2-referensen.
Vanliga frågor
Kan du se en persons nationalitet på namnet?
Nej, och ingen hederlig tjänst kan det. Vad du får är var namnet förekommer och hur starkt, rangordnat per land — en statistik om namnet, inte ett faktum om personen som bär det. Väldigt många bär ett namn vars ursprung inte har något att göra med var de föddes.
Vad returnerar endpointen?
En rangordnad lista på upp till 25 länder, vart och ett med en sannolikhet, en ISO-landskod, ett landsnamn och — där landet har dem registrerade — dess kontinentala och statistiska region. Samma svar innehåller också kön, ursprungsspråk, namnets betydelse och dess fördelning över etniska grupper.
Hur beräknas sannolikheten?
Från två signaler: hur stor andel av de poster vi har för namnet som kommer från varje land, och hur stor var och en av de befolkningarna är. De två snittas per land, länder på en procent eller mindre faller bort, och resten sorteras. Varje värde är en andel av helheten och inte ett betyg för landet i sig — läs dem alltså mot varandra. De summerar inte till exakt 1: allt under en procent lämnas utanför, och allt efter det tjugofemte landet också.
Vad kostar en förfrågan om ursprungsland?
Två credits per namn, eftersom det är en tyngre fråga än en vanlig könsbestämning. Credits börjar på €0.35 per 1 000, köps i förväg och blir inte ogiltiga.
Är det samma sak som country-parametern jag skickar?
Nej — det är motsatta riktningar. Den country, locale eller ip du skickar beskriver var personen är nu och ändrar vilket kön som kommer tillbaka. Ursprungslandet du får tillbaka beskriver var namnet kommer ifrån och beror inte på var personen bor.
Kan jag köra en hel lista genom den?
Ja. Batch-varianten tar upp till 100 namn per anrop, utan tak för antalet anrop, och samma endpoint svarar lika bra på ett enda namn.
Är det tillåtet enligt GDPR att härleda ursprung ur ett namn?
Det beror på vad du gör med det, och det är ditt beslut som personuppgiftsansvarig, inte vårt. Uppgifter som pekar på etniskt ursprung är en särskild kategori enligt artikel 9, så att använda dem för beslut om enskilda personer kräver en rättslig grund du kan visa. Aggregerade analyser och rätt tilltal är de vanliga användningarna. Vi är ett tyskt företag, alla servrar står i Tyskland, och ett personuppgiftsbiträdesavtal kan begäras i ditt konto.
TESTA PÅ NAMN DU REDAN KÄNNER
100 gratis förfrågningar per månad, utan kort. Börja med namn vars ursprung du själv kan kontrollera — det är snabbaste vägen att se vad fördelningen säger dig.
