Národnost ze jména: co jméno prozradit může a co ne
Jedno volání API změní jméno nebo příjmení na seřazený seznam zemí, ze kterých pochází, s pravděpodobností u každé. Odpovídá na otázku o jménu — a to je jiná otázka než to, kde člověk žije, a ještě jiná než to, kdo je.
Krátká odpověď
- Dostanete seřazený seznam až 25 zemí, každá s pravděpodobností, kódem ISO, názvem země a, pokud je země má zaznamenané, se svým kontinentálním a statistickým regionem.
- Stejná odpověď obsahuje také pohlaví, jazyk původu, význam jména a jeho rozložení mezi etnickými skupinami, z databáze pokrývající 192 zemí.
- Stojí to 2 kredity za jméno — dvojnásobek běžného určení pohlaví, protože je to těžší dotaz. Kredity se kupují předem a nepropadají.
- Je to statistika o jménu, ne tvrzení o člověku. Používejte to pro oslovení, agregovanou analýzu a kvalitu dat — ne k rozhodování o jednotlivém člověku.
Odkud se to číslo bere?
Tady nic nehádá žádný model a nic se negeneruje. Pravděpodobnost je aritmetika nad záznamy, které skutečně máme — proto stejné jméno vrátí stejný seznam dnes, příští měsíc i příští rok.
Vstupují dva signály. První je, jak jsou záznamy daného jména rozloženy mezi zeměmi — jméno, které máme převážně z Polska, se kloní k polskému. Druhý je, jak velká je každá z těch populací, což zabrání malé zemi s dobře podloženým jménem předběhnout velkou zemi jen díky objemu. Oba se zprůměrují po zemích, vše pod jedním procentem vypadne a co zbude, se seřadí.
Protože jde o rozložení, jméno běžné ve dvou zemích odpoví dvěma zeměmi, místo aby vybíralo vítěze. Právě to je užitečné: tvar seznamu vám řekne, jak moc můžete věřit první položce.
Co se vrací
Jeden POST, jedno jméno, jedna odpověď. Seznam níže je zkrácený; ten skutečný sahá k 25 nejpravděpodobnějším zemím.
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" }
}Všimněte si dvou polí, která odpověď činí ověřitelnou: samples vám řekne, na kolika záznamech stojí, a credits_used potvrdí dva kredity. Odpověď opřenou o malý počet vzorků před vámi neschováváme.
- Pomocí continental_region a statistical_region můžete seznam shrnout po regionech, aniž byste udržovali vlastní mapování.
- Odpověď obsahuje také odkaz na interaktivní mapu daného jména — nejrychlejší způsob, jak výsledek zkontrolovat okem.
- Každé pole je popsáno v referenci v2.
Původ není místo pobytu
Toto je zdaleka nejčastější nedorozumění a funguje v obou směrech. Dvě různá pole, dva různé významy, opačné směry.
| Otázka | Země, kterou posíláte | Země, kterou dostanete zpět |
|---|---|---|
| Pole | country, locale, ip |
country_of_origin |
| Znamená | Kde se člověk nachází teď | Odkud jméno pochází |
| Mění odpověď o pohlaví | Ano — Andrea je v Itálii mužské a v Německu ženské | Ne — je to výstup, ne vstup |
| Obvykle to už víte | Ano — z doručovací adresy, domény nebo IP | Ne — právě toto si kupujete |
| Kredity | Zdarma — parametr, nikoli dotaz | 2 za jméno |
Čím to není
Jméno je důkazem o jménu. Zacházet s ním jako s důkazem o člověku je místo, kde se tento druh dat pokazí — vyplatí se tedy o hranicích mluvit natvrdo, ještě než na tom začnete stavět.
Člověk jménem Nguyen se mohl narodit v Melbourne a člověk jménem Smith možná nikdy nevkročil do anglicky mluvící země. Endpoint odpovídá na otázku „odkud toto jméno pochází“ — a to je jediná otázka, na kterou odpovídá.
- Není to národnost, ani státní příslušnost, ani místo narození — a není to důkaz ani jednoho z toho.
- Není to etnická příslušnost člověka. Etnické rozložení popisuje, jak je jméno rozprostřeno mezi skupinami: vlastnost jména.
- Nemělo by rozhodovat nic o jednotlivém člověku — ani cenu, ani žádost, ani rizikové skóre. Údaje ukazující na etnický původ jsou zvláštní kategorií podle článku 9 GDPR a toto rozhodnutí je vaše jako správce, ne naše.
- Není to dohad. Tam, kde máme příliš málo, je result_found false a počet vzorků to říká — místo aby se vymyslela pravděpodobná země, jen aby se pole vyplnilo.
Na naší straně: jsme německá společnost, všechny servery stojí v Německu, data se zpracovávají v EU a smlouvu o zpracování osobních údajů si můžete vyžádat ve svém účtu. Celý obraz najdete v přehledu ochrany osobních údajů.
K čemu to lidé skutečně používají
- Trefit správné oslovení. Vědomí, že jméno je italské, a ne německé, je to, co změní „Andrea“ ze špatného oslovení na správné — a určení pohlaví ve stejné odpovědi je ta část, která to provede.
- Analýza trhu a publika na agregované úrovni. Do jakého jazyka přeložit kampaň, do kterých regionů mailing list skutečně dosáhne, kde zákaznická báze vyrostla.
- Kvalita dat. Seznam, u kterého rozložení původu náhle změní tvar, obvykle znamená, že se pokazil import, ne že se publikum přestěhovalo.
- Výzkum a demografie, kde rozložení na úrovni jmen za celou kohortu je jednotkou analýzy a o jednotlivcích se nevyvozují žádné závěry.
- Transliterace a párování, kde znalost pravděpodobného původu jména zúží jeho možné podoby zápisu.
Průchod celým seznamem
Dávková forma přijme až 100 jmen na požadavek, bez stropu na počet požadavků. Payload je jednoduché pole JSON.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Místo křestního jména funguje i celé jméno nebo e-mailová adresa — nejprve se jméno vyextrahuje, pak se určí původ.
- Oficiální klienti pro PHP, Python, Node, Java, Go, Ruby, Rust, Perl a .NET.
- Pro jednorázový seznam místo integrace se podívejte na hromadné určení pohlaví — stejné kredity, bez kódu.
- Každé pole, každá chyba a popis OpenAPI: reference v2.
Často kladené otázky
Poznáte národnost člověka z jeho jména?
Ne, a nedokáže to žádná poctivá služba. Dostanete informaci, kde se jméno vyskytuje a jak silně, seřazenou podle zemí — statistiku o jménu, ne fakt o člověku, který ho nosí. Mnoho lidí nosí jméno, jehož původ nemá nic společného s místem jejich narození.
Co endpoint vrací?
Seřazený seznam až 25 zemí, každá s pravděpodobností, kódem země ISO, názvem země a — pokud je země má zaznamenané — se svým kontinentálním a statistickým regionem. Stejná odpověď obsahuje také pohlaví, jazyk původu, význam jména a jeho rozložení mezi etnickými skupinami.
Jak se pravděpodobnost počítá?
Ze dvou signálů: jaká část záznamů, které k danému jménu máme, pochází z které země, a jak velká je každá z těch populací. Oba se zprůměrují po zemích, země s jedním procentem a méně vypadnou a zbytek se seřadí. Každá hodnota je podílem na celku, ne známkou pro zemi samu o sobě — čtěte je tedy ve vzájemném vztahu. Nesečtou se přesně na 1: vše pod jedním procentem zůstává mimo, a stejně tak vše po dvacáté páté zemi.
Kolik stojí dotaz na zemi původu?
Dva kredity za jméno, protože je to těžší dotaz než běžné určení pohlaví. Kredity začínají na €0.35 za 1 000, kupují se předem a nepropadají.
Je to totéž jako parametr country, který posílám?
Ne — jsou to opačné směry. Parametr country, locale nebo ip, který posíláte, popisuje, kde se člověk nachází teď, a mění, jaké pohlaví se vrátí. Zemi původu, kterou dostanete zpět, popisuje, odkud jméno pochází, a nezávisí na tom, kde člověk žije.
Mohu jím protáhnout celý seznam?
Ano. Dávková varianta přijme až 100 jmen na požadavek, bez stropu na počet požadavků, a stejný endpoint odpoví stejně dobře i na jedno jméno.
Je vyvozování původu ze jména podle GDPR přípustné?
Záleží na tom, co s tím děláte, a je to vaše rozhodnutí jako správce, ne naše. Údaje ukazující na etnický původ jsou zvláštní kategorií podle článku 9, takže jejich použití k rozhodování o konkrétních osobách vyžaduje právní základ, který dokážete prokázat. Agregované analýzy a správné oslovení jsou běžná využití. Jsme německá společnost, všechny servery stojí v Německu a smlouvu o zpracování osobních údajů si můžete vyžádat ve svém účtu.
VYZKOUŠEJTE TO NA JMÉNECH, KTERÁ UŽ ZNÁTE
100 dotazů zdarma měsíčně, bez platební karty. Začněte jmény, jejichž původ si dokážete ověřit sami — je to nejrychlejší cesta, jak zjistit, co vám rozložení říká.
