Nacionalidade a partir de um nome: o que um nome pode e não pode dizer
Uma chamada de API transforma um nome ou sobrenome em uma lista ordenada dos países de onde ele vem, com uma probabilidade em cada. Ela responde a uma pergunta sobre o nome — que é uma pergunta diferente de onde a pessoa mora, e diferente ainda de quem ela é.
A resposta curta
- Você recebe uma lista ordenada de até 25 países, cada um com uma probabilidade, um código ISO, um nome de país e, quando o país os tem registrados, sua região continental e estatística.
- A mesma resposta também traz o gênero, o idioma de origem, o significado do nome e sua distribuição entre grupos étnicos, a partir de um banco de dados que cobre 192 países.
- Custa 2 credits por nome — o dobro de uma simples determinação de gênero, porque é uma consulta mais pesada. Os credits são comprados antecipadamente e não expiram.
- É uma estatística sobre o nome, não uma afirmação sobre a pessoa. Use para formas de tratamento, análise agregada e qualidade de dados — não para decidir nada sobre uma pessoa específica.
De onde vem o número?
Aqui nenhum modelo adivinha, e nada é gerado. A probabilidade é aritmética sobre registros que realmente temos, e é por isso que o mesmo nome devolve a mesma lista hoje, no mês que vem e no ano que vem.
Entram dois sinais. O primeiro é como os registros desse nome se distribuem entre os países — um nome que temos principalmente da Polônia tende ao polonês. O segundo é o tamanho de cada uma dessas populações, o que impede um país pequeno com um nome bem amostrado de passar um país grande só por volume. Os dois são combinados em média por país, tudo abaixo de um por cento é descartado, e o que sobra é ordenado.
Como é uma distribuição, um nome comum em dois países responde com dois países em vez de escolher um vencedor. É justamente essa a parte útil: a forma da lista diz o quanto você pode confiar na primeira entrada.
O que volta
Um POST, um nome, uma resposta. A lista abaixo está encurtada; a real vai até os 25 países mais prováveis.
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" }
}Repare nos dois campos que tornam a resposta auditável: samples diz sobre quantos registros ela se apoia, e credits_used confirma os dois credits. Uma resposta com poucas amostras não é escondida de você.
- Com continental_region e statistical_region você agrupa a lista por região sem manter o seu próprio mapeamento.
- A resposta também contém um link para um mapa interativo desse nome, a forma mais rápida de conferir um resultado no olho.
- Cada campo está documentado na referência v2.
Origem não é residência
Esse é o mal-entendido mais comum, e ele acontece nos dois sentidos. Dois campos diferentes, dois significados diferentes, direções opostas.
| Pergunta | O país que você envia | O país que você recebe |
|---|---|---|
| Campo | country, locale, ip |
country_of_origin |
| Significa | Onde a pessoa está agora | De onde o nome vem |
| Muda a resposta de gênero | Sim — Andrea é masculino na Itália e feminino na Alemanha | Não — é uma saída, não uma entrada |
| Normalmente você já sabe | Sim — pelo endereço de entrega, pelo domínio ou pelo IP | Não — é justamente isso que você está comprando |
| Credits | Grátis — um parâmetro, não uma consulta | 2 por nome |
O que isso não é
Um nome é evidência sobre um nome. Tratá-lo como evidência sobre uma pessoa é onde esse tipo de dado dá errado, então vale ser direto sobre os limites antes de construir em cima.
Uma pessoa chamada Nguyen pode ter nascido em Melbourne, e uma pessoa chamada Smith pode nunca ter pisado em um país de língua inglesa. O endpoint responde “de onde vem este nome”, e essa é a única pergunta que ele responde.
- Não é uma nacionalidade, nem uma cidadania, nem um local de nascimento — e não é prova de nenhum dos três.
- Não é a etnia da pessoa. A distribuição étnica descreve como o nome se distribui entre grupos: uma propriedade do nome.
- Não deveria decidir nada sobre uma pessoa específica — nem um preço, nem uma candidatura, nem uma pontuação de risco. Dados que apontam para origem étnica são uma categoria especial pelo Artigo 9 do GDPR, e essa decisão é sua como controlador, não nossa.
- Não é um chute. Onde temos pouco demais, result_found é false e o número de amostras diz isso, em vez de inventar um país plausível para preencher o campo.
Do nosso lado: somos uma empresa alemã, todos os servidores estão na Alemanha, os dados são processados dentro da UE, e um acordo de processamento de dados pode ser solicitado na sua conta. O quadro completo está na visão geral de privacidade.
Para que isso serve de verdade
- Acertar a forma de tratamento. Saber que um nome é italiano e não alemão é o que transforma “Andrea” da saudação errada na certa — e a determinação de gênero na mesma resposta é a parte que aplica isso.
- Análise de mercado e de público em agregado. Para qual idioma traduzir uma campanha, quais regiões uma lista de e-mails realmente alcança, onde uma base de clientes cresceu.
- Qualidade de dados. Uma lista em que a distribuição de origem muda de forma de repente costuma significar que uma importação deu errado, não que o público se mudou.
- Pesquisa e demografia, onde uma distribuição no nível do nome sobre uma coorte inteira é a unidade de análise e nenhuma conclusão individual é tirada.
- Transliteração e correspondência, onde conhecer a provável origem de um nome reduz as grafias plausíveis dele.
Rodar sobre uma lista
A forma em lote aceita até 100 nomes por requisição, sem teto no número de requisições. O payload é um simples array JSON.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Em vez de um primeiro nome também funciona um nome completo ou um endereço de e-mail — o nome é extraído primeiro, depois a origem é resolvida.
- Clientes oficiais para PHP, Python, Node, Java, Go, Ruby, Rust, Perl e .NET.
- Para uma lista pontual em vez de uma integração, veja determinação de gênero em massa — os mesmos credits, sem código.
- Cada campo, cada erro e uma descrição OpenAPI: a referência v2.
Perguntas frequentes
Você consegue dizer a nacionalidade de uma pessoa pelo nome dela?
Não, e nenhum serviço honesto consegue. O que você recebe é onde o nome aparece e com que força, ordenado por país — uma estatística sobre o nome, não um fato sobre a pessoa que o carrega. Muita gente carrega um nome cuja origem não tem nada a ver com o lugar onde nasceu.
O que o endpoint retorna?
Uma lista ordenada de até 25 países, cada um com uma probabilidade, um código de país ISO, um nome de país e — quando o país os tem registrados — sua região continental e estatística. A mesma resposta também traz o gênero, o idioma de origem, o significado do nome e sua distribuição entre grupos étnicos.
Como a probabilidade é calculada?
A partir de dois sinais: que parcela dos registros que temos desse nome vem de cada país, e qual o tamanho de cada uma dessas populações. Os dois são combinados em média por país, países com um por cento ou menos são descartados, e o resto é ordenado. Cada valor é uma parcela do total e não uma nota daquele país isoladamente — então leia um em relação ao outro. Eles não vão somar exatamente 1: tudo abaixo de um por cento fica de fora, e também tudo que passa do vigésimo quinto país.
Quanto custa uma consulta de país de origem?
Dois credits por nome, porque é uma consulta mais pesada do que uma simples determinação de gênero. Os credits começam em €0.35 por 1.000, são comprados antecipadamente e não expiram.
Isso é a mesma coisa que o parâmetro country que eu envio?
Não — são direções opostas. O country, locale ou ip que você envia descreve onde a pessoa está agora e muda qual gênero é retornado. O país de origem que você recebe descreve de onde o nome vem e não depende de onde a pessoa mora.
Posso passar uma lista inteira por ele?
Sim. A variante em lote aceita até 100 nomes por requisição, sem teto no número de requisições, e o mesmo endpoint responde igualmente bem a um único nome.
Inferir origem a partir de um nome é lícito sob o GDPR?
Depende do que você faz com isso, e é a sua decisão como controlador, não a nossa. Dados que apontam para origem étnica são uma categoria especial pelo Artigo 9, então usá-los para decidir sobre pessoas específicas exige uma base legal que você possa demonstrar. Análises agregadas e formas de tratamento corretas são os usos comuns. Somos uma empresa alemã, todos os servidores estão na Alemanha, e um acordo de processamento de dados pode ser solicitado na sua conta.
TESTE COM NOMES QUE VOCÊ JÁ CONHECE
100 consultas grátis por mês, sem cartão de crédito. Comece com nomes cuja origem você mesmo pode conferir — é a forma mais rápida de ver o que a distribuição está dizendo.
Documentação da API · Processar uma lista inteira · Fazer uma pergunta
