Nationaliteit uit een naam: wat een naam wel en niet kan zeggen
Eén API-call maakt van een voor- of achternaam een gerangschikte lijst van de landen waar hij vandaan komt, met een waarschijnlijkheid bij elk. Het antwoordt op een vraag over de naam — en dat is een andere vraag dan waar de persoon woont, en weer een andere dan wie diegene is.
Het korte antwoord
- Je krijgt een gerangschikte lijst van maximaal 25 landen, elk met een waarschijnlijkheid, een ISO-code, een landnaam en, als het land ze heeft vastgelegd, de continentale en statistische regio.
- Dezelfde respons bevat ook het geslacht, de taal van herkomst, de betekenis van de naam en de verdeling over etnische groepen, uit een database met 192 landen.
- Het kost 2 credits per naam — twee keer een gewone geslachtsbepaling, want het is een zwaardere query. Credits koop je vooraf en ze verlopen niet.
- Het is een statistiek over de naam, geen uitspraak over de persoon. Gebruik het voor de aanhef, geaggregeerde analyse en datakwaliteit — niet om iets over een individu te beslissen.
Waar komt het getal vandaan?
Hier gokt geen model, en er wordt niets gegenereerd. De waarschijnlijkheid is rekenwerk op records die we echt hebben — daarom geeft dezelfde naam vandaag, volgende maand en volgend jaar dezelfde lijst.
Er gaan twee signalen in. Het eerste is hoe de records voor die naam over de landen verdeeld zijn — een naam die we vooral uit Polen hebben leunt Pools. Het tweede is hoe groot elk van die bevolkingen is, wat voorkomt dat een klein land met een goed bemonsterde naam een groot land voorbijstreeft op volume alleen. Beide worden per land gemiddeld, alles onder één procent valt af, en wat overblijft wordt gesorteerd.
Omdat het een verdeling is, antwoordt een naam die in twee landen veel voorkomt met twee landen in plaats van een winnaar te kiezen. Dat is precies het nuttige deel: de vorm van de lijst zegt je hoeveel je op de eerste vermelding kunt vertrouwen.
Wat je terugkrijgt
Eén POST, één naam, één respons. De lijst hieronder is ingekort; de echte gaat tot de 25 waarschijnlijkste landen.
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" }
}Let op de twee velden die het antwoord controleerbaar maken: samples zegt op hoeveel records het rust, en credits_used bevestigt de twee credits. Een antwoord met weinig samples wordt niet voor je verborgen.
- Met continental_region en statistical_region rol je de lijst op naar regio zonder je eigen mapping bij te houden.
- De respons bevat ook een link naar een interactieve kaart van die naam — de snelste manier om een resultaat met het oog te checken.
- Elk veld staat beschreven in de v2-referentie.
Herkomst is niet woonplaats
Dit is het meestvoorkomende misverstand, en het gaat twee kanten op. Twee verschillende velden, twee verschillende betekenissen, tegengestelde richtingen.
| Vraag | Het land dat je verstuurt | Het land dat je terugkrijgt |
|---|---|---|
| Veld | country, locale, ip |
country_of_origin |
| Betekent | Waar de persoon nu is | Waar de naam vandaan komt |
| Verandert het antwoord over geslacht | Ja — Andrea is in Italië mannelijk en in Duitsland vrouwelijk | Nee — het is een output, geen input |
| Meestal weet je het al | Ja — uit het verzendadres, het domein of het IP | Nee — dit is precies wat je koopt |
| Credits | Gratis — een parameter, geen query | 2 per naam |
Wat het niet is
Een naam is bewijs over een naam. Hem behandelen als bewijs over een persoon is waar dit soort data ontspoort, dus het is de moeite waard om de grenzen ronduit te noemen voordat je erop bouwt.
Iemand die Nguyen heet kan in Melbourne geboren zijn, en iemand die Smith heet is misschien nooit in een Engelstalig land geweest. Het endpoint antwoordt op “waar komt deze naam vandaan”, en dat is de enige vraag die het antwoordt.
- Het is geen nationaliteit, geen staatsburgerschap en geen geboorteplaats — en geen bewijs van een van de drie.
- Het is niet de etniciteit van de persoon. De etnische verdeling beschrijft hoe de naam over groepen verdeeld is: een eigenschap van de naam.
- Het hoort niets over een individu te beslissen — geen prijs, geen sollicitatie, geen risicoscore. Gegevens die op etnische afkomst wijzen zijn een bijzondere categorie onder artikel 9 van de GDPR, en die beslissing is aan jou als verwerkingsverantwoordelijke, niet aan ons.
- Het is geen gok. Waar we te weinig hebben, is result_found false en zegt het aantal samples dat ook — in plaats van een plausibel land te verzinnen om het veld te vullen.
Aan onze kant: we zijn een Duits bedrijf, alle servers staan in Duitsland, de data wordt binnen de EU verwerkt, en een verwerkersovereenkomst kun je in je account aanvragen. Het volledige beeld staat op het privacyoverzicht.
Waar het echt voor gebruikt wordt
- De aanhef goed krijgen. Weten dat een naam Italiaans is en niet Duits maakt van “Andrea” de juiste in plaats van de verkeerde begroeting — en de geslachtsbepaling in dezelfde respons is het deel dat er iets mee doet.
- Markt- en doelgroepanalyse op geaggregeerd niveau. In welke taal je een campagne vertaalt, welke regio's een mailinglijst werkelijk bereikt, waar een klantenbestand gegroeid is.
- Datakwaliteit. Een lijst waarin de herkomstverdeling plots van vorm verandert betekent meestal dat een import misging, niet dat het publiek verhuisd is.
- Onderzoek en demografie, waar een verdeling op naamniveau over een heel cohort de analyse-eenheid is en er geen conclusie over individuen wordt getrokken.
- Transliteratie en matching, waar de waarschijnlijke herkomst van een naam het aantal plausibele spellingen beperkt.
Het over een lijst laten lopen
De batch-vorm neemt tot 100 namen per request, zonder plafond op het aantal requests. De payload is een simpele JSON-array.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- In plaats van een voornaam werkt ook een volledige naam of een e-mailadres — de naam wordt eerst uitgehaald, daarna wordt de herkomst bepaald.
- Officiële clients voor PHP, Python, Node, Java, Go, Ruby, Rust, Perl en .NET.
- Voor een eenmalige lijst in plaats van een integratie, zie geslachtsbepaling in bulk — dezelfde credits, geen code.
- Elk veld, elke fout en een OpenAPI-beschrijving: de v2-referentie.
Veelgestelde vragen
Kun je de nationaliteit van iemand aan zijn naam zien?
Nee, en geen enkele eerlijke dienst kan dat. Wat je krijgt is waar de naam voorkomt en hoe sterk, gerangschikt per land — een statistiek over de naam, geen feit over de persoon die hem draagt. Heel veel mensen dragen een naam waarvan de herkomst niets te maken heeft met hun geboorteplaats.
Wat geeft het endpoint terug?
Een gerangschikte lijst van maximaal 25 landen, elk met een waarschijnlijkheid, een ISO-landcode, een landnaam en — als het land ze heeft vastgelegd — de continentale en statistische regio. Dezelfde respons bevat ook het geslacht, de taal van herkomst, de betekenis van de naam en de verdeling over etnische groepen.
Hoe wordt de waarschijnlijkheid berekend?
Uit twee signalen: welk deel van de records die we voor die naam hebben uit welk land komt, en hoe groot elk van die bevolkingen is. Beide worden per land gemiddeld, landen op één procent of minder vallen af, en de rest wordt gesorteerd. Elke waarde is een aandeel in het geheel en geen score voor dat land op zichzelf — lees ze dus ten opzichte van elkaar. Ze tellen niet precies op tot 1: alles onder één procent blijft weg, en alles na het vijfentwintigste land ook.
Wat kost een opvraging van het land van herkomst?
Twee credits per naam, want het is een zwaardere query dan een gewone geslachtsbepaling. Credits beginnen bij €0.35 per 1.000, je koopt ze vooraf en ze verlopen niet.
Is dit hetzelfde als de country-parameter die ik verstuur?
Nee — dat zijn tegengestelde richtingen. De country, locale of ip die je verstuurt beschrijft waar de persoon nu is en verandert welk geslacht je terugkrijgt. Het land van herkomst dat je terugkrijgt beschrijft waar de naam vandaan komt en hangt niet af van waar de persoon woont.
Kan ik er een hele lijst door halen?
Ja. De batch-variant neemt tot 100 namen per request, zonder plafond op het aantal requests, en hetzelfde endpoint antwoordt net zo goed op één naam.
Mag je onder de GDPR herkomst uit een naam afleiden?
Dat hangt af van wat je ermee doet, en het is jouw beslissing als verwerkingsverantwoordelijke, niet de onze. Gegevens die op etnische afkomst wijzen zijn een bijzondere categorie onder artikel 9, dus ze gebruiken om beslissingen over individuele personen te nemen vraagt een rechtsgrond die je kunt aantonen. Geaggregeerde analyses en de juiste aanhef zijn de gewone toepassingen. We zijn een Duits bedrijf, alle servers staan in Duitsland, en een verwerkersovereenkomst kun je in je account aanvragen.
PROBEER HET OP NAMEN DIE JE AL KENT
100 gratis opvragingen per maand, zonder creditcard. Begin met namen waarvan je de herkomst zelf kunt nagaan — dat is de snelste manier om te zien wat de verdeling je vertelt.
