Pular para o conteúdo
POST AI agent ready /v1/nationality/estimate

API de previsão de nacionalidade - Estimar país de origem a partir do nome

Estima os países de origem mais prováveis ​​para um determinado nome usando modelos estatísticos treinados em dados demográficos globais. Retorna uma matriz de países classificados por probabilidade com códigos ISO 3166-1 alfa-2. Útil para localização, análise demográfica e internacionalização.

Parameters

stringrequired

Name (first or last) to predict nationality for.

Code examples

curl -X POST https://api.botoi.com/v1/nationality/estimate \
  -H "Content-Type: application/json" \
  -d '{"name":"Tanaka"}'

When to use this API

Seleção automática de localidade e idioma

Quando um novo usuário se inscreve apenas com seu nome, preveja seu provável país de origem e padronize o idioma da interface e as configurações de localidade de acordo. Um usuário chamado "Tanaka" veria o japonês como idioma sugerido, evitando uma etapa de seleção manual.

Pesquisa de mercado e análise de público

Analise a distribuição de nacionalidade de sua base de usuários ou lista de e-mail executando nomes em lote por meio desse endpoint. Identifique em quais países seu produto tem maior repercussão e aloque orçamentos de marketing para as regiões com maiores oportunidades.

Pré-triagem KYC e verificação de identidade

Durante a integração KYC, compare a nacionalidade prevista com o país de residência declarado ou país do passaporte. Uma grande incompatibilidade não é uma fraude por si só, mas pode desencadear etapas adicionais de verificação no seu modelo de risco.

Frequently asked questions

Posso usar nomes, sobrenomes ou nomes completos?
O endpoint funciona com qualquer entrada de nome. Os sobrenomes (sobrenomes) geralmente produzem sinais de nacionalidade mais distintos do que os primeiros nomes. Você pode passar o nome, o sobrenome ou o nome completo, embora as entradas de token único (um nome por vez) tendam a ser mais precisas.
O que significa a pontuação de probabilidade?
Cada país na resposta tem uma probabilidade entre 0 e 1 que representa a probabilidade de uma pessoa com esse nome ser originária desse país. Uma probabilidade de 0,85 para JP significa que 85% das pessoas com esse nome no conjunto de dados são do Japão.
Quantos países são devolvidos?
A resposta inclui até 5 países classificados por probabilidade. Apenas países com probabilidade não negligenciável (acima de ~0,01) são incluídos. Nomes fortemente associados a um país podem retornar menos resultados.
Por que “Tanaka” mostra o Brasil como partida secundária?
O Brasil tem a maior diáspora japonesa fora do Japão. Nomes como “Tanaka” aparecem nos registros brasileiros devido à imigração japonesa no início do século XX. O modelo reflete as distribuições de nomes do mundo real entre os países.
O nome é normalizado antes do processamento?
Sim. Os nomes estão em letras minúsculas e sem espaços em branco. Os sinais diacríticos são preservados e contribuem para a previsão, uma vez que os caracteres acentuados carregam sinais de nacionalidade (por exemplo, "Muller" vs "Mueller").

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.

Sign up free View full docs