Uso Básico

GenderAPI te permite determinar el género de una persona utilizando distintos tipos de datos de entrada. Puedes analizar nombres directamente o extraer nombres de direcciones de correo electrónico y nombres de usuario. Aquí te explicamos cómo empezar:

1. Género a partir del Nombre

Envía un nombre al siguiente endpoint: 

https://api.genderapi.io/api

Ejemplo: 

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

También puedes añadir parámetros opcionales:

  • country: Pasa un código de país de dos letras ( ISO 3166-1 alpha-2 ) para mejorar la precisión de la predicción. Por ejemplo: country=TR para Turquía.
  • askToAI: Si se establece en true, la API consultará un modelo de IA para determinar el género si el nombre no se encuentra en la base de datos.
  • forceToGenderize: Si se establece en true, la API intentará adivinar el género incluso para entradas que no parezcan nombres reales de personas, como apodos o nombres ficticios como sparkling unicorn o mystic warrior. Esto puede ser útil para analizar nombres de usuario, pero los resultados pueden ser menos precisos. Nota: Este parámetro no está disponible en el endpoint de correo electrónico.

Ejemplo con 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 de Dirección de Correo Electrónico

Utiliza este endpoint si solo tienes una dirección de correo electrónico: 

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

Ejemplo: 

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

Nota: El parámetro forceToGenderize no está disponible para el endpoint de correo electrónico, ya que este endpoint primero extrae el nombre internamente.


3. Género a partir de Nombre de Usuario

Para nombres de usuario o apodos, usa: 

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

Ejemplo: 

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

El parámetro forceToGenderize es especialmente útil aquí, ya que los nombres de usuario suelen contener palabras que no son nombres reales o términos ficticios. Obliga a la API a intentar predecir el género incluso si la entrada no es un nombre humano típico.

Todos los métodos admiten solicitudes individuales o en lote. Para más detalles, consulta las secciones específicas en el menú de navegación de la izquierda.


✅ Respuesta de la API

Ejemplo de respuesta JSON para todos los 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 de la Respuesta

Campo Tipo Descripción
status Boolean true si la solicitud fue exitosa. Comprueba errores si es false.
used_credits Integer Número de créditos utilizados para esta solicitud.
remaining_credits Integer Créditos restantes en tu cuenta después de esta solicitud.
expires Integer (timestamp) Fecha de expiración del paquete en formato UNIX timestamp (segundos).
q String Tu consulta de entrada (nombre, correo electrónico o nombre de usuario).
name String El nombre encontrado o extraído.
gender Enum[String] Género predicho. Valores posibles: male, female o null.
country Enum[String] Código del país más probable (por ejemplo, US o DE).
total_names Integer Número de muestras utilizadas para la predicción.
probability Integer Porcentaje de probabilidad de la predicción de género (por ejemplo, 50-100).
duration String Tiempo de procesamiento de la solicitud (por ejemplo, 4ms).
Advertencia: Si tus valores de entrada contienen espacios o caracteres especiales (por ejemplo, sparkling unicorn), asegúrate siempre de aplicar URL-encode antes de realizar solicitudes GET. De lo contrario, la solicitud puede fallar o los parámetros pueden interpretarse incorrectamente por tu lenguaje de programación o librería HTTP. 
curl "https://api.genderapi.io/api?name=sparkling unicorn&key=YOUR_API_KEY"
deberías usar: 
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&key=YOUR_API_KEY"
o aplicar funciones de URL-encoding adecuadas en tu lenguaje de programación.