Separar um nome completo em nome e sobrenome
Um campo de nome combinado, uma chamada de API, dois campos limpos — as partículas, os títulos e a ordem invertida que quebram uma divisão escrita à mão já estão resolvidos, e o gênero está na mesma resposta.
A resposta curta
- Envie o campo combinado e receba first_name e last_name — além do gênero, da precisão e do número de amostras, na mesma resposta, por um credit.
- Partículas nobiliárquicas (“van der”, “von den”, “de la”) e títulos acadêmicos e profissionais são tratados em vez de virarem tropeço — e um “Rossi, Andrea” invertido também se resolve, a partir dos dados de nomes e não da vírgula.
- Onde as duas metades poderiam ser qualquer uma das duas, a decisão vem de com que frequência cada parte aparece como nome contra com que frequência aparece como sobrenome — não da posição dela na string.
- O modo strict devolve um sobrenome vazio em vez de um chute quando o sobrenome não está no banco de dados, então você vê a lacuna.
Por que dividir no espaço não funciona
Quase toda base de código tem uma versão disso: pega o campo de nome, divide nos espaços, o primeiro elemento é o nome, o último é o sobrenome. Passa no review porque os dados de teste são em inglês, e dá errado em silêncio no primeiro cliente que não é.
O caro é o jeito como falha. Nada levanta uma exceção. Você fica com um banco de dados cheio de gente cujo sobrenome é “van”, um disparo em massa que as cumprimenta assim, e nenhuma linha de log apontando a causa.
O que decide a divisão
Quatro coisas, nesta ordem — e a última é a que uma divisão baseada em regras não pode ter, porque exige saber como os nomes realmente se distribuem.
- Os títulos saem primeiro. “Prof. Dr.”, “Dipl.-Ing.”, “Managing Director” e o resto de uma lista mantida são removidos antes de qualquer outra decisão, para nunca acabarem num campo de nome.
- As partículas ficam com o sobrenome. “van”, “van der”, “van den”, “von”, “von der”, “de”, “de la”, “du”, “le”, “di”, “des” e suas vizinhas são reconhecidas como parte do sobrenome a que pertencem.
- Não se confia na pontuação para carregar a ordem. A vírgula em “Rossi, Andrea” é removida junto com os títulos, e a ordem é depois lida dos dados de nomes — uma vírgula é um hábito de formatação, e muitas listas a usam de forma inconsistente. No upload de CSV e Excel você pode declarar a ordem da coluna em vez disso, e uma ordem declarada é usada como declarada.
- A ambiguidade é resolvida pelos dados. Cada parte candidata é procurada tanto no banco de nomes quanto no de sobrenomes, e a parte que se comporta muito mais como sobrenome do que como nome é o sobrenome.
Passe um código de país e a mesma comparação acontece contra aquele país em vez de contra todos ao mesmo tempo — que é o que você quer quando já sabe de onde a lista veio.
Como chamar
Dois endpoints fazem isso, e qual você quer depende de precisar ou não do modo strict.
v2 — a API atual
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 — quando você precisa do modo strict
O modo strict existe apenas no endpoint de divisão v1. Se um sobrenome vazio importa mais para você do que estar na API mais nova, use este.
GET https://gender-api.com/get?split=Anna%20van%20der%20Berg&strict=true&key=…- referência v2 de nome completo — campos, erros, descrição OpenAPI.
- referência v1 de divisão — o parâmetro strict e suas respostas exatas.
- Clientes oficiais para PHP, Python, Node, Java, Go, Ruby, Rust, Perl e .NET.
Primeiro: essa coluna contém mesmo nomes completos?
Bom saber antes de processar um arquivo que você não criou. Envie uma amostra de até 100 valores e você recebe se eles parecem nomes completos — e não custa 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": [ … ]
}Fique claro sobre o que isso mede: fullname_probability é a parcela dos valores enviados que tem mais de uma palavra, e is_fullname é essa parcela acima de 0,6. É um julgamento sobre a coluna, não sobre cada nome — exatamente o que você precisa ao decidir se vale dividir, e não um substituto da divisão em si.
Uma coluna mista também é uma resposta válida: algumas listas têm “Thomas” e “John Smith” lado a lado, e a divisão resolve os dois sem você ordenar antes.
Onde ainda precisa da sua ajuda
Uma divisão que dissesse resolver todos os nomes do mundo estaria mentindo. Estes são os casos em que nenhuma regra resolve a string sozinha.
Se você controla o formulário, a solução mais barata não é uma API: dois campos em vez de um, ou uma indicação de que o formato é “nome, sobrenome”. Tudo o que vem abaixo vale para quando você não controla.
- Sobrenome primeiro. Com vírgula ou sem, ganha a leitura que os dados de nomes sustentam, e não uma regra de posição — o que acerta muito mais vezes do que erra, mas não é garantia. Se você sabe que toda a coluna tem o sobrenome primeiro, declare isso no upload em vez de confiar na pontuação.
- Nomes de uma só palavra. Um mononome não tem sobrenome a encontrar. O sobrenome volta vazio em vez de cortar o nome ao meio.
- Transliteração inconsistente. O mesmo nome escrito de três formas numa lista se resolve como três nomes, porque nos dados é exatamente isso.
- Nomes compostos sem hífen. “Anna Maria” é mantido junto onde os dados sustentam, mas uma lista que mistura “Anna Maria Rossi” e “Anna Rossi” não será uniforme.
Nos quatro casos um código de país estreita o problema, e o modo strict torna as linhas incertas visíveis em vez de silenciosamente plausíveis. Um campo vazio que você pode filtrar vale mais que um errado que você não percebe.
Uma coluna inteira de uma vez
Se os nomes estão numa planilha e não numa aplicação, você não precisa da API. Faça o upload do arquivo, aponte a coluna com os nomes combinados, e as partes separadas voltam como novas colunas ao lado dos seus dados — até 10,000,000 linhas por CSV ou 100,000 por pasta de trabalho do Excel, e sua pasta volta intacta.
- Enviar um arquivo CSV ou Excel — sem código, com a formatação original preservada.
- Determinação de gênero em massa — os limites, o preço por volume e as respostas para compras.
- Trabalha numa planilha ou num CRM? Existem integrações prontas para Excel, Google Sheets, Shopify, HubSpot, Salesforce, Zapier e mais.
Perguntas frequentes
Por que não simplesmente dividir no espaço?
Porque o espaço não é a fronteira. “Anna van der Berg” dá o sobrenome “van” no primeiro espaço e o nome “Anna van der” no último. Os dois estão errados, os dois parecem ótimos num teste com nomes ingleses, e os dois falham em silêncio no momento em que chega um sobrenome holandês, alemão, francês, espanhol ou português.
O que decide onde a divisão acontece?
Primeiro os títulos conhecidos são removidos, e partículas nobiliárquicas como “van der”, “von den” e “de la” ficam com o sobrenome. Depois se pesa com que frequência cada parte aparece como nome contra com que frequência aparece como sobrenome — então não é a posição da palavra que decide, nem a pontuação: uma vírgula é removida junto com os títulos em vez de ser lida como marcador de “sobrenome primeiro”. No upload de CSV e Excel você pode declarar diretamente a ordem da coluna, e então ela é usada como declarada.
O que acontece quando o sobrenome não está no banco de dados?
É para isso que existe o modo strict, no endpoint v1. Com o modo strict ativado, o sobrenome volta vazio em vez de adivinhado, então a lacuna fica visível nos seus dados. Sem ele, um sobrenome é extraído de qualquer forma, o melhor possível.
Ele também me dá o gênero?
Sim, na mesma resposta e pelo mesmo credit — junto com o número de amostras e a precisão por trás. Dividir o nome e determinar o gênero é uma chamada, não duas.
Como eu sei se a minha coluna contém nomes completos?
Envie uma amostra de até 100 valores para o endpoint name-format-detect. Ele não custa credits e diz se a coluna parece conter nomes completos, primeiros nomes ou uma mistura — útil antes de decidir como processar o arquivo.
Quanto custa dividir?
Um credit por nome, o mesmo que uma simples determinação de gênero, a partir de €0.35 por 1.000. Os credits são comprados antecipadamente e não expiram.
Ele funciona com nomes não ocidentais?
Em parte, e é melhor conhecer os limites. Nomes escritos com o sobrenome primeiro sem separador, nomes de uma só palavra e nomes transliterados de forma inconsistente são os casos difíceis — nenhuma regra os resolve só a partir da string. Enviar um código de país ajuda, porque a consulta passa a pesar as partes contra aquele país em vez de contra tudo.
TESTE COM OS NOMES QUE QUEBRAM A SUA DIVISÃO
100 consultas grátis por mês, sem cartão de crédito. Pegue as vinte linhas que o seu código atual erra e comece por elas.
Documentação da API · Em vez disso, faça o upload de um arquivo · Fazer uma pergunta
