Narodowość z imienia: co imię może powiedzieć, a czego nie
Jedno wywołanie API zamienia imię lub nazwisko w uszeregowaną listę krajów, z których pochodzi, z prawdopodobieństwem dla każdego. Odpowiada na pytanie o imię — a to inne pytanie niż to, gdzie osoba mieszka, i jeszcze inne niż to, kim jest.
Krótka odpowiedź
- Dostajesz uszeregowaną listę maksymalnie 25 krajów, każdy z prawdopodobieństwem, kodem ISO, nazwą kraju oraz, jeśli kraj je ma zapisane, regionem kontynentalnym i statystycznym.
- Ta sama odpowiedź zawiera też płeć, język pochodzenia, znaczenie imienia i jego rozkład w grupach etnicznych — z bazy obejmującej 192 krajów.
- Kosztuje 2 credits za imię — dwa razy tyle co zwykłe określenie płci, bo to cięższe zapytanie. Credits kupuje się z góry i nie tracą ważności.
- To statystyka o imieniu, nie twierdzenie o osobie. Używaj jej do form zwracania się, analiz zbiorczych i jakości danych — nie do decydowania o pojedynczym człowieku.
Skąd bierze się ta liczba?
Tu żaden model nie zgaduje i nic nie jest generowane. Prawdopodobieństwo to arytmetyka na rekordach, które naprawdę mamy — dlatego to samo imię zwraca tę samą listę dziś, w przyszłym miesiącu i w przyszłym roku.
Wchodzą dwa sygnały. Pierwszy to rozkład rekordów tego imienia między krajami — imię, które mamy głównie z Polski, przechyla się w stronę polskiego. Drugi to wielkość każdej z tych populacji, co nie pozwala małemu krajowi z dobrze udokumentowanym imieniem wyprzedzić dużego wyłącznie objętością. Oba są uśredniane na kraj, wszystko poniżej jednego procenta jest odrzucane, a resztę sortujemy.
Ponieważ to rozkład, imię częste w dwóch krajach odpowiada dwoma krajami, zamiast wybierać zwycięzcę. I to jest właśnie użyteczne: kształt listy mówi Ci, na ile możesz zaufać pierwszemu wpisowi.
Co wraca
Jeden POST, jedno imię, jedna odpowiedź. Lista poniżej jest skrócona; prawdziwa sięga 25 najbardziej prawdopodobnych krajów.
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" }
}Zwróć uwagę na dwa pola, które czynią odpowiedź weryfikowalną: samples mówi, na ilu rekordach się opiera, a credits_used potwierdza dwa credits. Odpowiedź opartą na małej liczbie próbek nie ukrywamy przed Tobą.
- Dzięki continental_region i statistical_region zwiniesz listę do regionów bez utrzymywania własnego mapowania.
- Odpowiedź zawiera też link do interaktywnej mapy tego imienia — najszybszy sposób sprawdzenia wyniku okiem.
- Każde pole jest opisane w dokumentacji v2.
Pochodzenie to nie miejsce zamieszkania
To najczęstsze nieporozumienie i działa w obie strony. Dwa różne pola, dwa różne znaczenia, przeciwne kierunki.
| Pytanie | Kraj, który wysyłasz | Kraj, który dostajesz |
|---|---|---|
| Pole | country, locale, ip |
country_of_origin |
| Znaczy | Gdzie osoba jest teraz | Skąd pochodzi imię |
| Zmienia odpowiedź o płci | Tak — Andrea jest we Włoszech męskie, a w Niemczech żeńskie | Nie — to wyjście, nie wejście |
| Zwykle już to wiesz | Tak — z adresu dostawy, domeny lub IP | Nie — to właśnie to kupujesz |
| Credits | Bezpłatnie — parametr, nie zapytanie | 2 za imię |
Czym to nie jest
Imię jest przesłanką o imieniu. Traktowanie go jako przesłanki o osobie to moment, w którym tego typu dane się psują — warto więc wprost powiedzieć o granicach, zanim coś na tym zbudujesz.
Osoba o nazwisku Nguyen mogła urodzić się w Melbourne, a osoba o nazwisku Smith mogła nigdy nie postawić stopy w kraju angielskojęzycznym. Endpoint odpowiada na pytanie „skąd pochodzi to imię“ — i to jedyne pytanie, na które odpowiada.
- To nie narodowość, nie obywatelstwo i nie miejsce urodzenia — ani dowód żadnego z nich.
- To nie pochodzenie etniczne osoby. Rozkład etniczny opisuje, jak imię rozkłada się między grupami — to cecha imienia.
- Nie powinno decydować o niczym w sprawie pojedynczej osoby — ani o cenie, ani o wniosku, ani o ocenie ryzyka. Dane wskazujące na pochodzenie etniczne to szczególna kategoria według artykułu 9 GDPR, a ta decyzja należy do Ciebie jako administratora danych, nie do nas.
- To nie zgadywanie. Tam, gdzie mamy zbyt mało, result_found ma wartość false, a liczba próbek to potwierdza — zamiast wymyślać prawdopodobny kraj, żeby wypełnić pole.
Po naszej stronie: jesteśmy niemiecką firmą, wszystkie serwery stoją w Niemczech, dane są przetwarzane w UE, a umowę powierzenia przetwarzania danych zamówisz w swoim koncie. Pełny obraz znajdziesz w przeglądzie ochrony danych.
Do czego naprawdę się to przydaje
- Trafienie z formą zwracania się. Wiedza, że imię jest włoskie, a nie niemieckie, zamienia „Andrea“ z błędnego powitania we właściwe — a określenie płci w tej samej odpowiedzi jest tym, co to wykonuje.
- Analiza rynku i odbiorców w skali zbiorczej. Na jaki język przetłumaczyć kampanię, które regiony naprawdę osiąga lista mailingowa, gdzie urosła baza klientów.
- Jakość danych. Lista, w której rozkład pochodzenia nagle zmienia kształt, zwykle znaczy, że import się nie udał, a nie że odbiorcy się przeprowadzili.
- Badania i demografia, gdzie rozkład na poziomie imion dla całej kohorty jest jednostką analizy i nie wyciąga się wniosków o pojedynczych osobach.
- Transliteracja i dopasowywanie, gdzie znajomość prawdopodobnego pochodzenia imienia zawęża jego możliwe pisownie.
Przepuszczenie przez całą listę
Forma wsadowa przyjmuje do 100 imion na żądanie, bez limitu liczby żądań. Payload to zwykła tablica JSON.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Zamiast imienia zadziała też pełne imię i nazwisko lub adres e-mail — najpierw wyciągamy imię, potem rozwiązujemy pochodzenie.
- Oficjalne klienty dla PHP, Python, Node, Java, Go, Ruby, Rust, Perl i .NET.
- Jeśli chodzi o jednorazową listę, a nie integrację, zobacz masowe określanie płci — te same credits, bez kodu.
- Każde pole, każdy błąd i opis OpenAPI: dokumentacja v2.
Często zadawane pytania
Czy możesz określić narodowość osoby na podstawie jej imienia?
Nie, i żadna uczciwa usługa tego nie potrafi. Dostajesz informację, gdzie imię występuje i jak silnie, uszeregowaną według krajów — statystykę o imieniu, a nie fakt o osobie, która je nosi. Wiele osób nosi imię, którego pochodzenie nie ma nic wspólnego z miejscem ich urodzenia.
Co zwraca endpoint?
Uszeregowaną listę maksymalnie 25 krajów, każdy z prawdopodobieństwem, kodem kraju ISO, nazwą kraju oraz — jeśli kraj je ma zapisane — regionem kontynentalnym i statystycznym. Ta sama odpowiedź zawiera też płeć, język pochodzenia, znaczenie imienia i jego rozkład w grupach etnicznych.
Jak obliczane jest prawdopodobieństwo?
Z dwóch sygnałów: jaka część rekordów, które mamy dla tego imienia, pochodzi z każdego kraju, i jak duża jest każda z tych populacji. Oba są uśredniane na kraj, kraje z jednym procentem lub mniej są odrzucane, a resztę sortujemy. Każda wartość to udział w całości, a nie ocena kraju samego w sobie — czytaj je więc względem siebie. Nie zsumują się dokładnie do 1: wszystko poniżej jednego procenta zostaje pominięte, podobnie jak wszystko po dwudziestym piątym kraju.
Ile kosztuje zapytanie o kraj pochodzenia?
Dwa credits za imię, bo to cięższe zapytanie niż zwykłe określenie płci. Credits zaczynają się od €0.35 za 1000, kupuje się je z góry i nie tracą ważności.
Czy to to samo co parametr country, który wysyłam?
Nie — to przeciwne kierunki. Wysyłane country, locale lub ip opisuje, gdzie osoba jest teraz, i zmienia zwracaną płeć. Kraj pochodzenia, który dostajesz z powrotem, opisuje, skąd pochodzi imię, i nie zależy od tego, gdzie osoba mieszka.
Czy mogę przepuścić przez to całą listę?
Tak. Wariant wsadowy przyjmuje do 100 imion na żądanie, bez limitu liczby żądań, a ten sam endpoint równie dobrze odpowiada na jedno imię.
Czy wnioskowanie pochodzenia z imienia jest zgodne z GDPR?
To zależy od tego, co z tym robisz, i jest Twoją decyzją jako administratora danych, nie naszą. Dane wskazujące na pochodzenie etniczne to szczególna kategoria według artykułu 9, więc używanie ich do decyzji o konkretnych osobach wymaga podstawy prawnej, którą możesz wykazać. Analizy zbiorcze i poprawne formy zwracania się to zwykłe zastosowania. Jesteśmy niemiecką firmą, wszystkie serwery stoją w Niemczech, a umowę powierzenia przetwarzania danych możesz zamówić w swoim koncie.
WYPRÓBUJ NA IMIONACH, KTÓRE JUŻ ZNASZ
100 bezpłatnych zapytań miesięcznie, bez karty. Zacznij od imion, których pochodzenie sam sprawdzisz — to najszybszy sposób, żeby zobaczyć, co mówi Ci rozkład.
