이름으로 국적 추정하기: 이름이 알려줄 수 있는 것과 없는 것
API 호출 한 번이면 이름이나 성이, 그것이 유래한 국가들의 정렬된 목록으로 바뀌어. 각각에 확률이 붙어. 이건 이름에 관한 질문의 답이야 — 그 사람이 어디 사는지와는 다른 질문이고, 그 사람이 누구인지와는 또 다른 질문이야
짧은 답
- 최대 25개 국가의 정렬된 목록을 받아. 각각에 확률, ISO 코드, 국가명, 그리고 해당 국가에 기록이 있으면 대륙 지역과 통계 지역이 붙어
- 같은 응답에는 성별, 유래 언어, 이름의 의미, 민족 집단별 분포도 담겨. 192개 국가를 포괄하는 데이터베이스에서 나온 거야
- 이름당 2 credits야 — 일반 성별 조회의 두 배인데, 더 무거운 질의라서 그래. credits는 미리 구매하며 만료되지 않아
- 이건 이름에 관한 통계이고, 사람에 관한 주장이 아니야. 호칭, 집계 분석, 데이터 품질에 써 — 개인에 관해 무언가를 결정하는 데는 쓰지 마
이 숫자는 어디에서 나와?
여기에는 추측하는 모델이 없고, 아무것도 생성되지 않아. 확률은 실제로 보유한 레코드 위의 산술이야. 그래서 같은 이름은 오늘도, 다음 달에도, 내년에도 같은 목록을 반환해
두 가지 신호가 들어가. 첫째는 그 이름의 레코드가 국가별로 어떻게 퍼져 있는지야 — 주로 폴란드에서 보유한 이름은 폴란드 쪽으로 기울어. 둘째는 각 인구의 규모인데, 표본이 많은 이름을 가진 작은 국가가 양만으로 큰 국가를 앞지르지 못하게 막아줘. 둘을 국가별로 평균하고, 1퍼센트 미만은 모두 빼고, 남은 걸 정렬해
분포이기 때문에, 두 국가에서 흔한 이름은 승자를 하나 고르는 대신 두 국가로 답해. 바로 그게 유용한 부분이야. 목록의 모양이 첫 항목을 얼마나 믿어도 되는지를 알려줘
돌아오는 것
POST 하나, 이름 하나, 응답 하나. 아래 목록은 줄인 거야. 실제로는 상위 25개 국가까지 이어져
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" }
}답을 검증 가능하게 만드는 두 필드를 봐. samples는 그 답이 몇 개의 레코드에 근거하는지 알려주고, credits_used는 2 credits를 확인해줘. 표본이 적은 답을 숨기지는 않아
- continental_region과 statistical_region을 쓰면 자체 매핑을 관리하지 않고도 목록을 지역 단위로 합칠 수 있어
- 응답에는 그 이름의 인터랙티브 지도 링크도 들어 있어. 결과를 눈으로 확인하는 가장 빠른 방법이야
- 모든 필드는 v2 레퍼런스에 정리돼 있어
출신은 거주지가 아니야
가장 흔한 오해이고, 양방향으로 일어나. 서로 다른 두 필드, 서로 다른 두 의미, 반대 방향이야
| 항목 | 보내는 국가 | 돌려받는 국가 |
|---|---|---|
| 필드 | country, locale, ip |
country_of_origin |
| 의미 | 그 사람이 지금 있는 곳 | 이름이 유래한 곳 |
| 성별 답을 바꿈 | 그래 — Andrea는 이탈리아에서는 남성 이름, 독일에서는 여성 이름이야 | 아니 — 이건 출력이고, 입력이 아니야 |
| 보통은 이미 알고 있어 | 그래 — 배송 주소, 도메인, IP에서 | 아니 — 바로 이게 네가 사는 부분이야 |
| Credits | 무료 — 질의가 아니라 파라미터야 | 이름당 2 |
이것이 아닌 것
이름은 이름에 관한 근거야. 그걸 사람에 관한 근거로 다루는 순간 이런 종류의 데이터는 어긋나기 시작해. 그래서 그 위에 무언가를 만들기 전에 한계를 분명히 말해 두는 게 좋아
Nguyen이라는 이름의 사람이 멜버른에서 태어났을 수도 있고, Smith라는 이름의 사람이 영어권 국가에 한 번도 발을 들이지 않았을 수도 있어. 엔드포인트가 답하는 건 “이 이름은 어디에서 왔나”이고, 그게 답하는 유일한 질문이야
- 이건 국적도, 시민권도, 출생지도 아니고, 그 셋 어느 것의 증거도 아니야
- 이건 그 사람의 민족 정체성이 아니야. 민족 분포는 이름이 집단 사이에 어떻게 퍼져 있는지를 설명하는 거고, 이름의 속성이야
- 개별 사람에 관해 아무것도 결정해서는 안 돼 — 가격도, 지원서도, 위험 점수도. 민족적 출신을 가리키는 데이터는 GDPR 제9조상 특별한 범주이고, 그 판단은 우리가 아니라 컨트롤러인 네 몫이야
- 추측이 아니야. 보유량이 너무 적은 경우에는 result_found가 false가 되고 표본 수가 그걸 말해줘. 필드를 채우려고 그럴듯한 국가를 만들어내지는 않아
우리 쪽은 이래. 독일 회사이고, 서버는 모두 독일에 있고, 데이터는 EU 안에서 처리되고, 데이터 처리 계약은 계정에서 요청할 수 있어. 전체 그림은 개인정보 개요에 있어
실제로 쓰이는 용도
- 호칭을 제대로 맞추는 것. 어떤 이름이 독일어가 아니라 이탈리아어라는 걸 아는 게 “Andrea”를 잘못된 인사에서 맞는 인사로 바꿔줘 — 그리고 같은 응답의 성별 조회가 그걸 실행하는 부분이야
- 집계 수준의 시장·오디언스 분석. 캠페인을 어떤 언어로 번역할지, 메일링 리스트가 실제로 어느 지역에 닿는지, 고객 기반이 어디에서 성장했는지
- 데이터 품질. 출신 분포의 모양이 갑자기 바뀐 목록은 보통 임포트가 잘못됐다는 뜻이고, 오디언스가 이사했다는 뜻이 아니야
- 연구와 인구통계. 코호트 전체에 대한 이름 단위 분포가 분석 단위이고, 개인에 관한 결론은 내리지 않아
- 음역과 매칭. 이름의 가능한 출신을 알면 있을 수 있는 표기가 좁혀져
목록 전체에 돌리기
배치 형식은 요청당 최대 100개의 이름을 받고, 요청 수에는 상한이 없어. 페이로드는 순수한 JSON 배열이야
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]자주 묻는 질문
이름으로 그 사람의 국적을 알 수 있어?
아니야, 그리고 정직한 서비스라면 어느 것도 못 해. 받는 건 그 이름이 어디에 얼마나 강하게 나타나는지를 국가별로 정렬한 결과야 — 이름에 관한 통계이고, 그 이름을 가진 사람에 관한 사실이 아니야. 태어난 곳과 아무 상관 없는 유래의 이름을 가진 사람은 아주 많아
엔드포인트는 무엇을 반환해?
최대 25개 국가의 정렬된 목록이고, 각각에 확률, ISO 국가 코드, 국가명, 그리고 해당 국가에 기록이 있으면 대륙 지역과 통계 지역이 붙어. 같은 응답에는 성별, 유래 언어, 이름의 의미, 민족 집단별 분포도 함께 담겨
확률은 어떻게 계산돼?
두 가지 신호에서 나와. 그 이름으로 보유한 레코드 중 각 국가에서 온 비율, 그리고 각 인구 규모야. 둘을 국가별로 평균하고, 1퍼센트 이하인 국가는 빼고, 나머지를 정렬해. 각 값은 그 국가 단독의 점수가 아니라 전체에 대한 몫이니까 서로 비교해서 읽어. 합이 정확히 1이 되지는 않아. 1퍼센트 미만은 모두 빠지고, 25번째 국가 이후도 마찬가지야
출신 국가 조회는 얼마야?
이름당 2 credits야. 일반 성별 조회보다 무거운 질의라서 그래. credits는 1,000건당 €0.35부터 시작하고, 미리 구매하며 만료되지 않아
이게 내가 보내는 country 파라미터와 같은 거야?
아니야 — 방향이 반대야. 네가 보내는 country, locale, ip는 그 사람이 지금 어디에 있는지를 나타내고, 어떤 성별이 돌아오는지를 바꿔. 돌려받는 출신 국가는 이름이 어디에서 왔는지를 나타내고, 그 사람이 어디 사는지와는 무관해
목록 전체를 통과시킬 수 있어?
응. 배치 방식은 요청당 최대 100개의 이름을 받고, 요청 수에는 상한이 없어. 같은 엔드포인트가 이름 하나에도 똑같이 잘 답해
이름으로 출신을 추론하는 게 GDPR상 적법해?
그건 그걸로 무엇을 하느냐에 달렸고, 우리가 아니라 컨트롤러인 네가 판단할 일이야. 민족적 출신을 가리키는 데이터는 제9조상 특별한 범주라서, 개별 사람에 관한 결정에 쓰려면 입증할 수 있는 법적 근거가 필요해. 집계 분석과 올바른 호칭이 일반적인 용도야. 우리는 독일 회사이고, 서버는 모두 독일에 있고, 데이터 처리 계약은 계정에서 요청할 수 있어
이미 아는 이름으로 시험해 봐
매달 100건 무료 조회, 신용카드 없이. 출신을 직접 확인할 수 있는 이름부터 시작해 봐 — 분포가 무슨 말을 하는지 알아보는 가장 빠른 방법이야
API 문서 · 목록 전체 처리하기 · 질문하기
