API de Género por Nombre | Solicitud Individual

Resumen de la solicitud

Envía un nombre por solicitud

Envía un objeto JSON con un nombre y autentica la solicitud mediante un token Bearer. Añade el código de país cuando los patrones regionales puedan mejorar la estimación.

MétodoPOST

Tipo de contenidoapplication/json

AutenticaciónToken Bearer

Coste en créditos1 consulta

HDR

Headers HTTP obligatorios

Autoriza la solicitud

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

Guarda la clave API en variables de entorno del servidor. Consulta la guía de autenticación para proteger las credenciales.

Cuerpo JSON de la solicitud

Parámetros

Parámetro	Tipo	Requisito	Descripción
`name`	string	Obligatorio	Nombre que se analizará. Envía un nombre limpio, sin títulos ni prefijos.
`country`	string	Opcional	Código de país ISO 3166-1 alfa-2, como ES o US, para añadir contexto regional.
`askToAI`	boolean	Opcional	Si es true, utiliza el soporte de IA cuando el nombre no aparece en la base de datos.
`forceToGenderize`	boolean	Opcional	Si es true, intenta obtener un resultado para alias o entradas que no parecen nombres habituales.

Acerca del soporte de IA

askToAI solo se aplica cuando la base de datos no devuelve resultados. Las estimaciones forzadas para entradas poco habituales pueden ser menos fiables; considera probability una señal importante.

Ejemplos de código

Realiza una solicitud individual

Todos los ejemplos envían la misma solicitud con autenticación Bearer.

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Alice","country":"US","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "US", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "US", "askToAI": True}
)
print(response.json())

Respuesta 200

Resultado de la estimación

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "US",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

Campos de respuesta

Campo	Tipo	Descripción
`status`	boolean	Indica si la solicitud se ha completado correctamente.
`used_credits`	integer	Créditos consumidos por esta solicitud.
`remaining_credits`	integer	Créditos disponibles después de la solicitud.
`expires`	integer	Vencimiento del paquete como marca de tiempo UNIX.
`q`	string	Nombre enviado originalmente en la solicitud.
`name`	string	Nombre analizado por GenderAPI.
`gender`	string \| null	Valor estimado: male, female o null.
`country`	string	Código de país considerado para la estimación.
`total_names`	integer	Número de muestras que respaldan la estimación.
`probability`	integer	Confianza de la estimación expresada en porcentaje.
`duration`	string	Tiempo de procesamiento en el servidor.

Envía datos limpios y correctamente codificados

Utiliza un nombre sin títulos ni prefijos. Los clientes JSON gestionan la codificación automáticamente, pero valida siempre las entradas externas antes de crear el cuerpo de la solicitud.

Siguiente guía

Analiza varios nombres

Solicitud con varios nombresProcesa varios nombres en una sola solicitud →AutenticaciónRevisa la seguridad de la clave API →