GenderAPI.io V2: consultas por nombre y nombre completo

Antes de enviar la solicitud

Envía las consultas de GenderAPI.io V2 a POST https://api.genderapi.io/api/v2/gender con type y value en el cuerpo JSON. Utiliza tu clave actual en Authorization: Bearer YOUR_API_KEY y Content-Type: application/json. Lee el resultado en data y la información de acceso y cobro en meta. Cada solicitud se procesa de forma independiente.

Elige tu idioma en el ejemplo de código. Configura GENDERAPI_API_KEY en el entorno del proceso antes de ejecutarlo. Las claves faltantes o no reconocidas pueden usar la versión de prueba compartida de IP, así que confirme que meta.access.mode es api_key al integrar una cuenta.

Género de un nombre

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
`type`	`string`	Sí	`—`	Categoría de entrada: name, email o username.
`value`	`string`	Sí	`—`	Requerido. 1–254 caracteres; no en blanco, sin caracteres de control. Los valores de correo electrónico deben tener una sintaxis de correo electrónico válida.
`country`	`string`	No	`—`	Código ISO 3166-1 alpha-2 en mayúsculas opcional, por ejemplo TR o US. La búsqueda específica de un país puede recurrir al conjunto de datos global.
`forceToGenderize`	`boolean`	No	`false`	Consulta primero el conjunto de datos y después la IA para apodos si no hay resultado. Compatible con name, email y username.
`options`	`object`	No	`—`	Objeto con las opciones de IA de cada entrada.
`options.ai_mode`	`string`	No	`fallback`	Valores permitidos: off, fallback, always. Con forceToGenderize: true, omite este campo o utiliza fallback.
`id`	`string`	No	`—`	Identificador opcional con entre 1 y 64 caracteres en el cuerpo POST JSON. Debe ser único dentro de un lote y se devuelve con el resultado del lote. Las solicitudes individuales aceptan este identificador pero no lo incluyen en la respuesta. Las consultas GET no lo admiten.

Para consultar un nombre o nombre completo, envía type: name y la entrada completa en value a POST https://api.genderapi.io/api/v2/gender. GenderAPI.io V2 utiliza los mismos campos para ambos formatos. Una respuesta completada puede contener data.gender: null. Las consultas individuales buscan primero en el conjunto de datos y recurren a la IA de forma predeterminada si no hay predicción.

Elige un lenguaje de programación. Configura tu clave API, luego ejecuta el ejemplo en tu servidor.

Cada solicitud de predicción es una nueva operación facturable, incluidos los reintentos. Estos ejemplos no se reintentan automáticamente. Comprueba el estado de facturación antes de enviar otra solicitud.

Antes de ejecutar: acceso y manejo de errores

Ejecuta estos ejemplos en tu servidor. Configura GENDERAPI_API_KEY en el entorno de proceso con tu clave API existente. Confirma que meta.access.mode es api_key: una clave no reconocida puede recurrir a la prueba IP.

Las respuestas HTTP 4xx y 5xx JSON conservan el cuerpo del error y devuelven un estado de salida distinto de cero. Comprueba code, action y meta.usage.billing_status antes de volver a intentarlo.

Guía de errores y reintentos →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "Javier",
  "country": "ES"
}'

cURL 7.76+ en un shell POSIX. Ejecuta en tu terminal. Documentación del entorno de ejecución

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "name",
  "value": "Javier",
  "country": "ES"
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+; fetch integrado. Guarda como example.mjs y ejecuta node example.mjs. Documentación del entorno de ejecución

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"name\",\"value\":\"Javier\",\"country\":\"ES\"}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+; biblioteca estándar. Guarda como example.py y ejecuta python3 example.py. Documentación del entorno de ejecución

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Javier","country":"ES"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+ con la extensión cURL. Guarda como example.php y ejecuta php example.php. Documentación del entorno de ejecución

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"name\",\"value\":\"Javier\",\"country\":\"ES\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+; cliente estándar HTTP. Guarda como GenderApiExample.java y ejecuta java GenderApiExample.java. Documentación del entorno de ejecución

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"Javier\",\"country\":\"ES\"}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

Aplicación de consola .NET 8+. Úsalo como Program.cs en un proyecto de consola, luego ejecuta dotnet run. Documentación del entorno de ejecución

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"name\",\"value\":\"Javier\",\"country\":\"ES\"}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+; biblioteca estándar. Guarda como main.go y ejecuta go run main.go. Documentación del entorno de ejecución

Ejemplo de respuesta

Esta es una respuesta real capturada el 1 de octubre de 2026 con una clave de API; solo se sustituyó el saldo de la cuenta. No es una medida de precisión, y una consulta real puede devolver un resultado distinto. Las solicitudes con clave de API indican meta.access.mode: api_key y null en los campos exclusivos de la prueba; las solicitudes de prueba por IP indican ip_trial. Lee data para la predicción y meta.usage para el resultado del cobro.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Javier",
      "country": "ES"
    },
    "name": "javier",
    "gender": "male",
    "country": "ES",
    "confidence": 0.9955271565495207,
    "confidence_kind": "observed_frequency",
    "sample_count": 6260,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "javier",
      "method": "normalized",
      "scope": "country",
      "country": "ES"
    }
  },
  "meta": {
    "request_id": "48437027-f346-4e88-904f-5e2cd896d661",
    "duration_ms": 15,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Campos de respuesta y confianza

Campos de la respuesta de predicción

Campo	Tipo	¿Admite null?	Ejemplo	Descripción
`data.input`	`object`	No	`{"type":"name","value":"Javier","country":"ES"}`	Tipo de entrada, valor y país. forceToGenderize se incluye cuando true.
`data.name`	`string`	Sí	`"javier"`	Nombre de pila coincidente o extraído; null cuando no hay ninguno disponible.
`data.gender`	`string`	Sí	`"male"`	male, female o JSON null. Esta es una predicción, no una prueba de la identidad de una persona.
`data.result_status`	`string`	No	`"identified"`	identified si se devuelve un género; unknown en caso contrario.
`data.reason`	`string`	Sí	`null`	null en resultados identified. Para unknown: not_found, no_name_candidate, ambiguous o insufficient_evidence.
`data.confidence`	`number`	Sí	`0.95`	Puntuación entre 0 y 1, o null. Si gender es null, confidence también lo es.
`data.confidence_kind`	`string`	Sí	`"observed_frequency"`	observed_frequency: el recuento de género dominante dividido por el recuento total en el conjunto de datos seleccionado. model_reported: una puntuación de IA, no una probabilidad calibrada. El valor es null cuando no está disponible.
`data.sample_count`	`integer`	Sí	`1200`	Tamaño de muestra del conjunto de datos o null. La IA no inventa un recuento de muestras.
`data.source`	`string`	No	`"dataset"`	dataset, ai o none.
`data.country`	`string`	Sí	`"ES"`	Asociación de país del conjunto de datos o ai_association, o null. No establece nacionalidad, residencia ni etnia.
`data.country_source`	`string`	Sí	`"dataset"`	Origen de la asociación de país: dataset, ai_association o null.
`data.match`	`object`	No	`{"name":"javier","method":"normalized","scope":"country","country":"ES"}`	Nombre coincidente en el conjunto de datos, método (normalized, token, substring o model_inference), ámbito (country o global) y país de la coincidencia. La información no disponible se representa con null.

Acceso, facturación y metadatos de la solicitud

Campo	Tipo	¿Admite null?	Ejemplo	Descripción
`meta.request_id`	`string`	No	`"550e8400-e29b-41d4-a716-446655440000"`	Identificador único de este intento HTTP; también se envía en X-Request-ID.
`meta.duration_ms`	`integer`	No	`42`	Tiempo de procesamiento de la solicitud en milisegundos.
`meta.access.mode`	`string`	No	`"api_key"`	api_key, ip_trial o unauthenticated. Comprueba api_key para cualquier integración de cuenta, gratuita o de pago.
`meta.access.reason`	`string`	Sí	`null`	Motivo del acceso de prueba: api_key_missing, api_key_invalid o api_key_not_found; null en otros casos.
`meta.usage.charged_credits`	`integer`	Sí	`1`	Créditos netos cobrados. Cero antes del cobro o tras un reembolso completo confirmado; null si el cobro no está confirmado.
`meta.usage.remaining_credits`	`integer`	Sí	`99`	Saldo al finalizar la operación. Puede ser negativo; null si no está disponible o el cobro no está confirmado.
`meta.usage.billing_status`	`string`	No	`"confirmed"`	not_charged, confirmed o unconfirmed. Compruébelo antes de reintentar una predicción fallida.
`meta.usage.resets_at`	`string`	Sí	`"2026-09-27T12:00:00.000Z"`	Reinicio de la prueba por IP en UTC (ISO 8601); null para cuentas con clave API o si se desconoce.
`meta.usage.limit`	`integer`	Sí	`10`	Créditos de la prueba por IP; null para cuentas con clave API.
`meta.usage.period_seconds`	`integer`	Sí	`86400`	Duración de la prueba por IP en segundos; null para cuentas con clave API.

Contexto del país y nombres desconocidos

Proporciona el país solo cuando tenga un contexto relevante. La API puede seleccionar una fila del conjunto de datos específica de un país o recurrir a una fila global. data.match.scope muestra cuál fue seleccionado; el país devuelto no establece dónde vive la persona.

De forma predeterminada, una sola solicitud utiliza IA cuando el conjunto de datos no puede determinar un género, para un total de 1 crédito. Para utilizar solo el conjunto de datos, envía options: {"ai_mode": "off"}. Una solicitud completa todavía cuesta créditos si devuelve gender: null. Una búsqueda de nombre completo puede coincidir con una parte del nombre. data.match registra el candidato elegido y el método de coincidencia.

Para un apodo proporcionado como nombre, forceToGenderize: true permite la inferencia de IA sin un nombre real. Un género identificado en el conjunto de datos cuesta 1 crédito. Si se necesita IA, el coste total es de 2 créditos. Cualquier saldo inicial positivo es suficiente; el saldo final puede ser negativo.

Consulta un nombre completo sin dar por hecho que se elige la primera palabra

Envía el nombre con sus caracteres Unicode originales. La búsqueda en el conjunto de datos aplica normalización NFKC, conversión a minúsculas y extracción de componentes; no necesitas convertir el nombre a ASCII. Entre los candidatos disponibles, la API selecciona el registro con el mayor recuento total almacenado. Puede ser un componente posterior del nombre: no presupongas que se eligió la primera palabra o el nombre de pila.

Esta solicitud consulta solo el conjunto de datos para facilitar la revisión de la coincidencia. data.input.value contiene el nombre completo enviado; data.match.name, el candidato seleccionado; y data.match.method, el método de coincidencia. El ejemplo no garantiza un género ni un componente concreto. Los candidatos del conjunto de datos deben tener más de dos caracteres; las entradas cortas pueden quedar sin resolver. Activa el recurso habitual a la IA si esa inferencia adicional es adecuada para tu aplicación.