Rozdziel pełne nazwisko na imię i nazwisko
Jedno połączone pole nazwy, jedno wywołanie API, dwa czyste pola — cząstki, tytuły i odwrócona kolejność, na których wykłada się samodzielnie napisany podział, są już obsłużone, a płeć jest w tej samej odpowiedzi.
Krótka odpowiedź
- Wyślij połączone pole, otrzymaj first_name i last_name — a do tego płeć, dokładność i liczbę próbek, w tej samej odpowiedzi, za jeden credit.
- Cząstki nazwiskowe („van der“, „von den“, „de la“) oraz tytuły akademickie i zawodowe są obsługiwane, a nie stanowią przeszkody — i odwrócone „Rossi, Andrea“ też się rozwiązuje, z danych o nazwach, a nie z przecinka.
- Tam, gdzie obie połowy mogłyby być jednym albo drugim, decyduje to, jak często każda część występuje jako imię względem tego, jak często występuje jako nazwisko — a nie jej pozycja w ciągu znaków.
- Tryb strict zwraca puste nazwisko zamiast domysłu, gdy nazwiska nie ma w bazie — dzięki temu widzisz lukę.
Dlaczego podział na spacji nie działa
Prawie każda baza kodu ma swoją wersję: weź pole nazwy, podziel na białych znakach, pierwszy element to imię, ostatni to nazwisko. Przechodzi review, bo dane testowe są angielskie, i po cichu psuje się przy pierwszym kliencie, który nie jest.
Kosztowny jest sposób, w jaki to zawodzi. Nic nie zgłasza wyjątku. Zostajesz z bazą pełną ludzi o nazwisku „van“, korespondencją seryjną, która tak ich wita, i bez ani jednej linii logu wskazującej przyczynę.
Co decyduje o podziale
Cztery rzeczy, w tej kolejności — a ostatniej podział oparty na regułach mieć nie może, bo wymaga wiedzy o tym, jak nazwy naprawdę się rozkładają.
- Tytuły schodzą pierwsze. „Prof. Dr.“, „Dipl.-Ing.“, „Managing Director“ i resztę utrzymywanej listy usuwamy przed jakąkolwiek inną decyzją, żeby nigdy nie wylądowały w polu nazwy.
- Cząstki zostają przy nazwisku. „van“, „van der“, „van den“, „von“, „von der“, „de“, „de la“, „du“, „le“, „di“, „des“ i im podobne są rozpoznawane jako część nazwiska, do którego należą.
- Interpunkcji nie powierzamy kolejności. Przecinek w „Rossi, Andrea“ jest usuwany razem z tytułami, a kolejność czytana potem z danych o nazwach — przecinek to nawyk formatowania, a wiele list stosuje go niekonsekwentnie. We wgrywaniu CSV i Excela możesz zamiast tego podać kolejność kolumny, a podana kolejność jest używana tak, jak ją podałeś.
- Niejednoznaczność rozstrzygają dane. Każda część kandydująca jest sprawdzana i w bazie imion, i w bazie nazwisk, a ta, która zachowuje się znacznie bardziej jak nazwisko niż jak imię, jest nazwiskiem.
Podaj kod kraju i to samo porównanie odbędzie się względem tego kraju, a nie wszystkich krajów naraz — a tego właśnie chcesz, gdy już wiesz, skąd wzięła się lista.
Jak to wywołać
Robią to dwa endpointy, a który wybierzesz, zależy od tego, czy potrzebujesz trybu strict.
v2 — aktualne API
POST https://gender-api.com/v2/gender/by-full-name
{ "full_name": "Anna van der Berg", "country": "NL" }{
"result_found": true,
"first_name": "Anna",
"last_name": "van der Berg",
"gender": "female",
"probability": 0.98,
"details": { "credits_used": 1, "samples": 8961, "duration": "33ms" }
}v1 — gdy potrzebujesz trybu strict
Tryb strict istnieje tylko na endpointzie podziału v1. Jeśli puste nazwisko liczy się dla Ciebie bardziej niż nowsze API, weź ten.
GET https://gender-api.com/get?split=Anna%20van%20der%20Berg&strict=true&key=…- dokumentacja v2 dla pełnego nazwiska — pola, błędy, opis OpenAPI.
- dokumentacja v1 dla podziału — parametr strict i jego dokładne odpowiedzi.
- Oficjalne klienty dla PHP, Python, Node, Java, Go, Ruby, Rust, Perl i .NET.
Najpierw: czy w tej kolumnie naprawdę są pełne imiona i nazwiska?
Warto wiedzieć, zanim przetworzysz plik, którego sam nie utworzyłeś. Wyślij próbkę maksymalnie 100 wartości i dostaniesz odpowiedź, czy wyglądają na pełne imiona i nazwiska — i nie kosztuje to credits.
POST https://gender-api.com/v2/name-format-detect
{ "names": ["Sophie Jones", "Lorenzo Carlos", "Anna van der Berg"] }{
"is_fullname": true,
"fullname_probability": 1,
"validHints": [ … ]
}Miej jasność, co to mierzy: fullname_probability to udział wysłanych wartości, które mają więcej niż jedno słowo, a is_fullname to ten udział powyżej 0,6. To ocena kolumny, nie każdej pojedynczej nazwy — dokładnie to, czego potrzebujesz przy decyzji, czy w ogóle dzielić, i nie zastępuje samego podziału.
Mieszana kolumna to też prawidłowa odpowiedź: niektóre listy mają obok siebie „Thomas“ i „John Smith“, a podział radzi sobie z jednym i drugim, bez wstępnego sortowania.
Gdzie nadal potrzebuje Twojej pomocy
Podział, który twierdziłby, że radzi sobie z każdym nazwiskiem na świecie, kłamałby. Oto przypadki, w których żadna reguła nie rozwiąże ciągu znaków sama.
Jeśli kontrolujesz formularz, najtańsze rozwiązanie to wcale nie API: dwa pola zamiast jednego albo wskazówka, że format to „imię, nazwisko“. Wszystko poniżej dotyczy sytuacji, gdy go nie kontrolujesz.
- Nazwisko najpierw. Z przecinkiem czy bez, wygrywa odczyt, który wspierają dane o nazwach, a nie reguła o pozycji — i trafia znacznie częściej, niż się myli, ale to nie gwarancja. Jeśli wiesz, że cała kolumna ma nazwisko najpierw, podaj to przy wgrywaniu, zamiast polegać na interpunkcji.
- Nazwy jednowyrazowe. W mononimie nie ma nazwiska do znalezienia. Nazwisko wraca puste, zamiast rozcinać imię na pół.
- Niekonsekwentna transliteracja. To samo imię zapisane w liście na trzy sposoby rozwiązuje się jako trzy imiona, bo w danych właśnie tym jest.
- Imiona złożone bez łącznika. „Anna Maria“ zostaje razem tam, gdzie dane to wspierają, ale lista mieszająca „Anna Maria Rossi“ i „Anna Rossi“ nie będzie jednolita.
We wszystkich czterech przypadkach kod kraju zawęża problem, a tryb strict czyni niepewne wiersze widocznymi, zamiast po cichu prawdopodobnymi. Puste pole, które da się odfiltrować, jest lepsze niż błędne, którego nie wychwycisz.
Cała kolumna od razu
Jeśli nazwy są w arkuszu, a nie w aplikacji, API nie jest Ci potrzebne. Wgraj plik, wskaż kolumnę z połączonymi nazwami, a rozdzielone części wrócą jako nowe kolumny obok Twoich danych — do 10,000,000 wierszy na CSV lub 100,000 na arkusz Excela, a Twój arkusz wróci nietknięty.
- Wgraj plik CSV lub Excel — bez kodu, z zachowanym oryginalnym formatowaniem.
- Masowe określanie płci — limity, cena przy dużych wolumenach i odpowiedzi dla działu zakupów.
- Pracujesz w arkuszu albo w CRM? Są gotowe integracje dla Excela, Google Sheets, Shopify, HubSpot, Salesforce, Zapier i innych.
Często zadawane pytania
Dlaczego nie podzielić po prostu na spacji?
Bo spacja nie jest granicą. „Anna van der Berg“ daje na pierwszej spacji nazwisko „van“, a na ostatniej imię „Anna van der“. Oba są błędne, oba wyglądają dobrze w teście z angielskimi nazwiskami i oba zawodzą w milczeniu w chwili, gdy pojawia się nazwisko niderlandzkie, niemieckie, francuskie, hiszpańskie lub portugalskie.
Co decyduje o miejscu podziału?
Najpierw usuwane są znane tytuły, a cząstki nazwiskowe takie jak „van der“, „von den“ i „de la“ zostają przy nazwisku. Potem waży się, jak często każda część występuje jako imię, względem tego, jak często występuje jako nazwisko — to więc nie pozycja słowa o tym decyduje, ani interpunkcja: przecinek jest usuwany razem z tytułami, a nie czytany jako znacznik „nazwisko najpierw“. We wgrywaniu CSV i Excela możesz wprost podać kolejność kolumny, i wtedy jest używana tak, jak ją podałeś.
Co się dzieje, gdy nazwiska nie ma w bazie?
Do tego służy tryb strict, na endpointzie v1. Przy włączonym trybie strict nazwisko wraca puste, a nie zgadnięte, więc luka jest widoczna w Twoich danych. Bez niego nazwisko i tak zostanie wyciągnięte, na tyle dobrze, na ile to możliwe.
Czy dostanę też płeć?
Tak, w tej samej odpowiedzi i za ten sam jeden credit — razem z liczbą próbek i dokładnością, która za tym stoi. Podzielenie imienia i określenie płci to jedno wywołanie, nie dwa.
Skąd mam wiedzieć, czy moja kolumna w ogóle zawiera pełne imiona i nazwiska?
Wyślij próbkę maksymalnie 100 wartości na endpoint name-format-detect. Nie kosztuje credits i odpowiada, czy kolumna wygląda na pełne imiona i nazwiska, same imiona, czy mieszankę — przydatne, zanim zdecydujesz, jak przetworzyć plik.
Ile kosztuje podział?
Jeden credit za imię, tyle samo co zwykłe określenie płci, od €0.35 za 1000. Credits kupuje się z góry i nie tracą ważności.
Czy poradzi sobie z nazwiskami niezachodnimi?
Częściowo — i lepiej znać granice. Nazwiska pisane najpierw, bez separatora, nazwy jednowyrazowe i imiona transliterowane niekonsekwentnie to trudne przypadki; żadna reguła nie rozwiąże ich z samego ciągu znaków. Wysłanie kodu kraju pomaga, bo zapytanie waży wtedy części względem tego kraju, a nie względem wszystkiego.
WYPRÓBUJ NA NAZWACH, NA KTÓRYCH WYKŁADA SIĘ TWÓJ PODZIAŁ
100 bezpłatnych zapytań miesięcznie, bez karty. Weź te dwadzieścia wierszy, które Twój obecny kod robi źle, i zacznij od nich.
Dokumentacja API · Zamiast tego prześlij plik · Zadaj pytanie
