Uso Básico

O GenderAPI permite que você determine o gênero de uma pessoa usando diferentes tipos de dados de entrada. Você pode analisar diretamente nomes próprios ou extrair nomes a partir de endereços de e-mail e nomes de usuário. Veja como começar:

1. Gênero a partir do Nome

Envie um primeiro nome para o seguinte endpoint: 

https://api.genderapi.io/api

Exemplo: 

curl "https://api.genderapi.io/api?name=Alice&key=YOUR_API_KEY"

Você também pode adicionar parâmetros opcionais:

  • country: Informe um código de país com duas letras ( ISO 3166-1 alpha-2 ) para melhorar a precisão da previsão. Por exemplo: country=TR para a Turquia.
  • askToAI: Se definido como true, a API consultará um modelo de IA para determinar o gênero caso o nome não seja encontrado no banco de dados.
  • forceToGenderize: Se definido como true, a API tentará adivinhar o gênero mesmo para entradas que não parecem nomes reais, como apelidos ou nomes fantasiosos, por exemplo sparkling unicorn ou mystic warrior. Isso pode ser útil para analisar nomes de usuário, mas os resultados podem ser menos precisos. Nota: Esse parâmetro não está disponível no endpoint de e-mail.

Exemplo com parâmetros: 

curl "https://api.genderapi.io/api?name=sparkling%20unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

2. Gênero a partir do Endereço de E-mail

Use este endpoint caso você tenha apenas um endereço de e-mail: 

https://api.genderapi.io/api/email

Exemplo: 

curl "https://api.genderapi.io/api/email?email=alice.smith@example.com&country=TR&askToAI=true&key=YOUR_API_KEY"

Nota: O parâmetro forceToGenderize não está disponível para o endpoint de e-mail, pois esse endpoint primeiro extrai o nome internamente.


3. Gênero a partir do Nome de Usuário

Para nomes de usuário ou apelidos, utilize: 

https://api.genderapi.io/api/username

Exemplo: 

curl "https://api.genderapi.io/api/username?username=sparkling_unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

O parâmetro forceToGenderize é especialmente útil aqui, pois nomes de usuário frequentemente contêm palavras que não são nomes reais ou termos fantasiosos. Esse parâmetro força a API a tentar prever o gênero, mesmo que a entrada não seja um nome humano típico.

Todos os métodos suportam requisições individuais ou em lote. Para mais detalhes, consulte as seções específicas no menu de navegação à esquerda.


✅ Resposta da API

Exemplo de resposta JSON para todos os endpoints: 

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "michael.smith@example.com",
  "name": "Michael",
  "gender": "male",
  "country": "US",
  "total_names": 325,
  "probability": 98,
  "duration": "4ms"
}

Campos da Resposta

Campo Tipo Descrição
status Boolean true se a requisição foi bem-sucedida. Verifique erros se for false.
used_credits Integer Número de créditos utilizados para esta requisição.
remaining_credits Integer Créditos restantes na sua conta após esta requisição.
expires Integer (timestamp) Data de expiração do pacote em formato UNIX timestamp (segundos).
q String Sua consulta de entrada (nome, e-mail ou nome de usuário).
name String O nome encontrado ou extraído.
gender Enum[String] Gênero previsto. Valores possíveis: male, female ou null.
country Enum[String] Código do país mais provável (ex.: US ou DE).
total_names Integer Número de amostras usadas para a previsão.
probability Integer Porcentagem de probabilidade para a previsão de gênero (ex.: 50-100).
duration String Tempo de processamento da requisição (ex.: 4ms).
Atenção: Se os seus valores de entrada contiverem espaços ou caracteres especiais (ex.: sparkling unicorn), sempre faça o URL encoding antes de realizar requisições GET. Caso contrário, a requisição pode falhar ou outros parâmetros podem ser interpretados incorretamente pela sua linguagem de programação ou biblioteca HTTP. 
curl "https://api.genderapi.io/api?name=sparkling unicorn&key=YOUR_API_KEY"
você deve usar: 
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&key=YOUR_API_KEY"
ou aplicar as funções adequadas de URL encoding na sua linguagem de programação.