전체 이름을 이름과 성으로 분리하기
결합된 이름 필드 하나, API 호출 한 번, 깔끔한 필드 둘 — 직접 작성한 분할 처리를 망가뜨리는 전치사, 호칭, 뒤바뀐 순서는 이미 처리돼 있고, 성별도 같은 응답에 있어
짧은 답
- 결합된 필드를 보내면 first_name과 last_name이 돌아와 — 여기에 성별, 정확도, 표본 수까지, 같은 응답에서, 1 credit으로
- 전치사(“van der”, “von den”, “de la”)와 학위·직함은 걸림돌이 되는 대신 처리돼 — 뒤바뀐 “Rossi, Andrea”도 해결되는데, 쉼표가 아니라 이름 데이터에서 나와
- 양쪽 모두 어느 쪽이든 될 수 있는 경우, 판단은 각 부분이 이름으로 나타나는 빈도와 성으로 나타나는 빈도의 비교에서 나와 — 문자열 안의 위치에서 나오지 않아
- strict mode는 성이 데이터베이스에 없을 때 추측 대신 빈 성을 반환해서, 빈칸이 보이게 해
공백으로 나누는 게 통하지 않는 이유
거의 모든 코드베이스에 이런 버전이 있어. 이름 필드를 가져와서 공백으로 나누고, 첫 요소가 이름, 마지막 요소가 성. 테스트 데이터가 영어라서 리뷰를 통과하고, 영어가 아닌 첫 고객에서 조용히 어긋나
비싸지는 건 실패하는 방식 때문이야. 아무것도 예외를 던지지 않아. 성이 “van”인 사람들로 가득한 데이터베이스, 그렇게 인사하는 대량 발송, 그리고 원인을 가리키는 로그 한 줄도 없는 상태가 남아
분할을 결정하는 것
네 가지가 이 순서로 작동해 — 그리고 마지막 것은 규칙 기반 분할 처리가 가질 수 없는 거야. 이름이 실제로 어떻게 분포하는지를 알아야 하니까
- 호칭이 먼저 떨어져 나가. “Prof. Dr.”, “Dipl.-Ing.”, “Managing Director”, 그리고 관리되는 목록의 나머지는 다른 무엇이 정해지기 전에 제거돼서, 이름 필드에 들어가는 일이 없어
- 전치사는 성과 함께 남아. “van”, “van der”, “van den”, “von”, “von der”, “de”, “de la”, “du”, “le”, “di”, “des”와 그 이웃들은 자기가 속한 성의 일부로 인식돼
- 순서를 구두점에 맡기지 않아. “Rossi, Andrea”의 쉼표는 호칭과 함께 제거되고, 순서는 그다음 이름 데이터에서 읽어 — 쉼표는 서식 습관이고, 많은 목록이 일관되지 않게 써. CSV와 Excel 업로드에서는 대신 열의 순서를 지정할 수 있고, 지정된 순서는 지정된 대로 쓰여
- 애매함은 데이터가 정리해. 후보가 되는 각 부분을 이름 데이터베이스와 성 데이터베이스 양쪽에서 조회하고, 이름보다 성처럼 훨씬 더 많이 행동하는 부분이 성이야
국가 코드를 넘기면 같은 비교가 모든 국가가 아니라 그 국가에 대해 이뤄져 — 목록이 어디에서 왔는지 이미 알고 있을 때 원하는 동작이야
호출 방법
이걸 하는 엔드포인트는 두 개고, 어느 걸 쓸지는 strict mode가 필요한지에 달렸어
v2 — 현재 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 — strict mode가 필요할 때
strict mode는 v1 분할 엔드포인트에만 있어. 더 새로운 API를 쓰는 것보다 빈 성이 돌아오는 게 더 중요하면 이걸 써
GET https://gender-api.com/get?split=Anna%20van%20der%20Berg&strict=true&key=…- v2 전체 이름 레퍼런스 — 필드, 오류, OpenAPI 설명
- v1 분할 레퍼런스 — strict 파라미터와 정확한 응답
- PHP, Python, Node, Java, Go, Ruby, Rust, Perl, .NET용 공식 클라이언트.
먼저, 그 열이 애초에 전체 이름이야?
직접 만들지 않은 파일을 처리하기 전에 알아둘 만해. 최대 100개 값의 표본을 보내면 전체 이름처럼 보이는지 돌려받아 — 그리고 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": [ … ]
}이게 무엇을 재는지 분명히 해 두자. fullname_probability는 보낸 값 중 두 단어 이상으로 된 것의 비율이고, is_fullname은 그 비율이 0.6을 넘는지야. 열에 대한 판단이고, 각 이름에 대한 판단이 아니야 — 애초에 나눌지 말지를 정할 때 필요한 건 바로 이거고, 분할 자체를 대신하지는 않아
섞인 열도 정당한 답이야. 어떤 목록은 “Thomas”와 “John Smith”가 나란히 들어 있고, 분할 처리는 미리 정렬하지 않아도 둘 다 처리해
아직 네 손이 필요한 곳
세상의 모든 이름을 처리한다고 말하는 분할 처리가 있다면 거짓말이야. 다음은 어떤 규칙으로도 문자열만으로는 풀 수 없는 경우들이야
폼을 네가 관리한다면 가장 싼 해결책은 API가 아예 아니야. 필드 하나 대신 둘로 하거나, 형식이 “이름, 성”이라고 알려주는 거야. 아래 내용은 모두 폼을 관리하지 않을 때의 이야기야
- 성이 먼저인 형식. 쉼표가 있든 없든, 이름 데이터가 뒷받침하는 해석이 위치 규칙을 이겨 — 틀리는 경우보다 맞는 경우가 훨씬 많지만, 보장은 아니야. 열 전체가 성이 먼저라는 걸 알고 있다면, 구두점에 기대는 대신 업로드에서 그렇게 지정해
- 한 단어짜리 이름. 단일명에는 찾을 성이 없어. 이름을 반으로 자르는 대신 성이 비어서 돌아와
- 일관되지 않은 음역. 한 목록에서 세 가지로 표기된 같은 이름은 세 개의 이름으로 해석돼. 데이터상으로는 정확히 그렇기 때문이야
- 하이픈 없는 복합 이름. 데이터가 뒷받침하는 경우 “Anna Maria”는 하나로 유지되지만, “Anna Maria Rossi”와 “Anna Rossi”가 섞인 목록은 균일해지지 않아
네 경우 모두 국가 코드가 문제를 좁혀주고, strict mode는 불확실한 행을 조용히 그럴듯하게 두는 대신 눈에 보이게 해. 걸러낼 수 있는 빈 필드가, 눈에 띄지 않는 틀린 필드보다 나아
열 전체를 한 번에
이름이 애플리케이션이 아니라 스프레드시트에 있다면 API는 필요 없어. 파일을 올리고, 결합된 이름이 든 열을 지정하면, 나뉜 부분이 데이터 옆에 새 열로 돌아와 — CSV 하나당 최대 10,000,000행, Excel 통합 문서 하나당 100,000행까지고, 통합 문서는 그대로 돌아와
- CSV 또는 Excel 파일 올리기 — 코드 없이, 원래 서식은 그대로 유지
- 대량 성별 조회 — 한도, 대량 시 가격, 구매 부서용 답변
- 스프레드시트나 CRM에서 작업 중이야? Excel, Google Sheets, Shopify, HubSpot, Salesforce, Zapier 등을 위한 바로 쓰는 연동이 있어
자주 묻는 질문
그냥 공백으로 나누면 안 돼?
공백이 경계가 아니라서 그래. “Anna van der Berg”는 첫 공백에서 나누면 성이 “van”이 되고, 마지막 공백에서 나누면 이름이 “Anna van der”가 돼. 둘 다 틀렸고, 둘 다 영어 이름 테스트에서는 멀쩡해 보이고, 둘 다 네덜란드·독일·프랑스·스페인·포르투갈 성이 들어오는 순간 조용히 실패해
어디에서 나눌지는 무엇이 결정해?
먼저 알려진 호칭·직함을 제거하고, “van der”, “von den”, “de la” 같은 전치사는 성과 함께 남겨. 그다음 각 부분이 이름으로 나타나는 빈도와 성으로 나타나는 빈도를 견줘 — 그러니까 단어의 위치가 결정하지 않고, 구두점도 결정하지 않아. 쉼표는 “성이 먼저”라는 표시로 읽히는 대신 호칭과 함께 제거돼. CSV와 Excel 업로드에서는 열의 순서를 직접 지정할 수 있고, 그러면 지정한 대로 쓰여
성이 데이터베이스에 없으면 어떻게 돼?
그게 v1 엔드포인트의 strict mode가 있는 이유야. strict mode를 켜면 성이 추측되지 않고 비어서 돌아와서, 빈칸이 데이터에서 보여. 끄면 그래도 최선을 다해 성을 뽑아내
성별도 같이 줘?
응, 같은 응답에서 같은 1 credit으로 — 그 뒤의 표본 수와 정확도까지 함께. 이름을 나누고 성별을 판정하는 건 호출 한 번이고, 두 번이 아니야
내 열에 애초에 전체 이름이 들어 있는지 어떻게 알아?
최대 100개 값의 표본을 name-format-detect 엔드포인트로 보내. credits가 들지 않고, 그 열이 전체 이름인지, 이름만인지, 섞여 있는지 답해줘 — 파일을 어떻게 처리할지 정하기 전에 유용해
나누는 건 얼마야?
이름당 1 credit, 일반 성별 조회와 같고, 1,000건당 €0.35부터야. credits는 미리 구매하며 만료되지 않아
서양식이 아닌 이름도 처리해?
부분적으로는 그래. 그리고 한계를 아는 게 나아. 구분자 없이 성이 먼저 쓰인 이름, 한 단어짜리 이름, 음역이 일관되지 않은 이름이 어려운 경우야 — 문자열만으로 그걸 풀어내는 규칙은 없어. 국가 코드를 보내면 도움이 돼. 조회가 각 부분을 전체가 아니라 그 국가에 견주게 되니까
