Referencia de REST API

Inicio rápido

Crea una clave en tu panel de control y envía tu primera solicitud. No necesitas SDK.

curl "https://namegender.com/api/v1/gender?name=Ay%C5%9Fe&country=TR" \
  -H "Authorization: Bearer YOUR_API_KEY"

<?php

$query = http_build_query(['name' => 'Ayşe', 'country' => 'TR']);

$ch = curl_init('https://namegender.com/api/v1/gender?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_API_KEY'],
]);

$result = json_decode(curl_exec($ch), true);

echo $result['gender'];       // female
echo $result['probability'];  // 100

const params = new URLSearchParams({ name: 'Ayşe', country: 'TR' });

const response = await fetch(`https://namegender.com/api/v1/gender?${params}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});

const result = await response.json();

console.log(result.gender);       // "female"
console.log(result.probability);  // 100

import requests

response = requests.get(
    "https://namegender.com/api/v1/gender",
    params={"name": "Ayşe", "country": "TR"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

result = response.json()
print(result["gender"])       # female
print(result["probability"])  # 100

require "net/http"
require "json"

uri = URI("https://namegender.com/api/v1/gender")
uri.query = URI.encode_www_form(name: "Ayşe", country: "TR")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)["gender"]   # female

req, _ := http.NewRequest("GET", "https://namegender.com/api/v1/gender?name=Ay%C5%9Fe&country=TR", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result struct {
    Gender      string `json:"gender"`
    Probability int    `json:"probability"`
}
json.NewDecoder(resp.Body).Decode(&result)

fmt.Println(result.Gender)   // female

Cada endpoint devuelve la misma estructura, así que puedes cambiar entradas sin modificar tu código de análisis.

Autenticación

Cada solicitud lleva tu clave de API en un encabezado. Usa Authorization: Bearer por defecto, o X-Api-Key si tu cliente HTTP reserva el encabezado Authorization para otra cosa. Una clave colocada en la URL se rechaza: las URL acaban copiadas en registros de proxy, herramientas de analítica y el historial del navegador.

Authorization: Bearer ng_live_xxxxxxxxxxxx

X-Api-Key: ng_live_xxxxxxxxxxxx

Puedes restringir una clave a direcciones IP específicas desde el panel de control.

Bibliotecas cliente

Envolturas delgadas sobre la API REST. Envían tu clave, construyen cada petición y convierten las respuestas de error en excepciones.

npm install namegender

npm install -g namegender

composer require namegender/namegender

pip install namegender-client

gem install namegender

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

<dependency>
  <groupId>com.github.anpekesen</groupId>
  <artifactId>namegender-java</artifactId>
  <version>v0.9.0</version>
</dependency>

dotnet add package NameGender --version 0.6.0

go get github.com/anpekesen/namegender-go@v0.7.0

remotes::install_github('anpekesen/namegender-r', ref = 'v0.7.0')

Install-Module NameGender

cargo add namegender

No las necesitas. La API son unos pocos endpoints de JSON simple; una biblioteca te ahorra una tarde, no un proyecto. Si tu lenguaje no está listado, la referencia REST tiene ejemplos para copiar y pegar.

Asistentes de IA (MCP)

Usa NameGender desde Claude, Cursor y cualquier otro cliente compatible con el Model Context Protocol. Pregúntale al asistente por una lista de nombres y llamará a la API por ti, con la evidencia junto a cada respuesta.

claude mcp add namegender -e NAMEGENDER_API_KEY=ng_live_... -- npx -y namegender-mcp

{
    "mcpServers": {
        "namegender": {
            "command": "npx",
            "args": [
                "-y",
                "namegender-mcp"
            ],
            "env": {
                "NAMEGENDER_API_KEY": "ng_live_..."
            }
        }
    }
}

Herramientas

gender_from_name

Género a partir de un nombre de pila o un nombre completo.

gender_from_email

Lee el nombre de una dirección de email; las direcciones genéricas como info@ devuelven desconocido.

gender_from_username

Lee el nombre de un nombre de usuario o handle.

gender_bulk

Hasta 100 valores en una sola solicitud, con un resumen de la tasa de coincidencia.

name_countries

Países donde un nombre está registrado. No es una afirmación sobre su origen.

salutation

Saludo inicial de una carta en el idioma de la carta; la forma neutra cuando el género no es seguro.

name_check

Si un nombre escrito en un formulario parece real, con los motivos. Nunca califica un nombre de falso.

age_from_name

Edad mediana y rangos de edad de las personas con un nombre de pila en Estados Unidos, Francia y Noruega.

account_status

Créditos restantes y la asignación gratuita de hoy.

Cada consulta usa créditos de la cuenta propietaria de la clave, exactamente igual que una llamada directa a la API. Publicado en el registro oficial de MCP como io.github.anpekesen/namegender. Paquete npm · Código fuente

Género a partir del nombre

Acepta un nombre de pila o un nombre completo. Los títulos, nombres intermedios y apellidos se eliminan antes de la búsqueda, así que "Dr. Ayşe Yılmaz" y "Ayşe" dan la misma respuesta.

curl "https://namegender.com/api/v1/gender?name=Jordan" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49999,
  "request_id": "req_4b7e0c2d9a1f6358",
  "query": "Jordan",
  "name": "Jordan",
  "first_name": "Jordan",
  "middle_name": null,
  "last_name": null,
  "name_type": "personal",
  "gender": "male",
  "country": null,
  "sample_size": 62240,
  "probability": 84,
  "took_ms": 1,
  "confidence": "high",
  "source": "db",
  "matched_as": null
}

Género a partir del correo electrónico

Extrae la persona de la parte local de la dirección y luego la clasifica. "ayse.yilmaz84@example.com" se resuelve a Ayşe.

best_guess actúa sobre el nombre leído de la dirección, no sobre la dirección en sí. Si no se puede leer ningún nombre, no hay nada que forzar y gender sigue siendo null. Ten en cuenta que aquí una respuesta forzada se apoya en una extracción que también puede ser errónea.

curl "https://namegender.com/api/v1/gender/email?email=ayse.yilmaz84%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49998,
  "query": "ayse.yilmaz84@example.com",
  "name": "Ayse",
  "gender": "female",
  "sample_size": 655,
  "probability": 100,
  "took_ms": 1,
  "confidence": "high",
  "source": "db"
}

Género a partir del nombre de usuario

Maneja camelCase, snake_case, dígitos finales y signos @ iniciales. "AyseYilmaz84" se resuelve a Ayşe.

curl "https://namegender.com/api/v1/gender/username?username=AyseYilmaz84" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49997,
  "query": "AyseYilmaz84",
  "name": "Ayse",
  "gender": "female",
  "sample_size": 655,
  "probability": 100,
  "took_ms": 1,
  "confidence": "high",
  "source": "db"
}

Solicitud en lote

Envía hasta 100 nombres en una solicitud. Usa esto en lugar de hacer un bucle: una llamada en lote para 100 nombres es un único viaje de ida y vuelta y una búsqueda deduplicada única.

curl -X POST "https://namegender.com/api/v1/gender/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names": ["Ayşe", "Mehmet", "Priya", "Wei"]}'

<?php

$ch = curl_init('https://namegender.com/api/v1/gender/bulk');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'names' => ['Ayşe', 'Mehmet', 'Priya', 'Wei'],
    ]),
]);

$data = json_decode(curl_exec($ch), true);

foreach ($data['results'] as $row) {
    printf("%-8s %-7s %d%%\n", $row['query'], $row['gender'] ?? '?', $row['probability']);
}

const response = await fetch('https://namegender.com/api/v1/gender/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ names: ['Ayşe', 'Mehmet', 'Priya', 'Wei'] }),
});

const { results, summary } = await response.json();

console.log(summary.match_rate);   // 100
results.forEach(r => console.log(r.query, r.gender, r.probability));

import requests

response = requests.post(
    "https://namegender.com/api/v1/gender/bulk",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"names": ["Ayşe", "Mehmet", "Priya", "Wei"]},
)

data = response.json()
print(data["summary"]["match_rate"])   # 100

for row in data["results"]:
    print(row["query"], row["gender"], row["probability"])

{
  "credits_charged": 4,
  "credits_remaining": 49995,
  "request_id": "req_71d0a9e3c5b24f86",
  "took_ms": 2,
  "summary": {
    "total": 4,
    "identified": 4,
    "unknown": 0,
    "match_rate": 100
  },
  "results": [
    { "query": "Ayşe",   "gender": "female", "probability": 100, "sample_size":  655, "confidence": "high", "source": "db" },
    { "query": "Mehmet", "gender": "male",   "probability": 100, "sample_size": 1130, "confidence": "high", "source": "db" },
    { "query": "Priya",  "gender": "female", "probability": 100, "sample_size": 2993, "confidence": "high", "source": "db" },
    { "query": "Wei",    "gender": "male",   "probability":  86, "sample_size":  136, "confidence": "high", "source": "db" }
  ]
}

Los resultados vuelven en el mismo orden en que los enviaste. Los créditos se cobran por nombre, y toda la solicitud se rechaza antes de cualquier trabajo si tu saldo es insuficiente, así que nunca obtendrás un lote procesado parcialmente.

El bloque de resumen te muestra la tasa de coincidencia de un vistazo, para que puedas decidir si la entrada necesita limpieza antes de procesar el resto.

Trabajos de archivo

Sube un archivo CSV o XLSX de hasta 100 MB y 1.000.000 filas y recíbelo con columnas de género añadidas a cada fila. Un crédito por fila, cobrado solo si el trabajo se completa.

1. 1. POST /batches Envía el archivo y name_column. El trabajo se pone en cola de inmediato.
2. 2. GET /batches/{id} Consulta el trabajo hasta que status sea completed o failed. poll_after_seconds indica cuánto esperar entre consultas.
3. 3. GET /batches/{id}/result Descarga el resultado. Vuelve en el formato que subiste.

# 1. Upload and start
curl -X POST "https://namegender.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 6f1c2e0a-customers-2026-09" \
  -F "file=@customers.csv" \
  -F "name_column=first_name" \
  -F "country_column=country"

# 2. Poll until status is completed or failed
curl "https://namegender.com/api/v1/batches/B-7K2M9QX4TA" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Download the result
curl "https://namegender.com/api/v1/batches/B-7K2M9QX4TA/result" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o customers-gender.csv

import { NameGender } from 'namegender';
import { openAsBlob } from 'node:fs';
import { writeFile } from 'node:fs/promises';

const client = new NameGender(process.env.NAMEGENDER_API_KEY);

const job = await client.batches.create(await openAsBlob('customers.csv'), {
  filename: 'customers.csv',
  name_column: 'first_name',
  country_column: 'country',
});

const done = await client.batches.wait(job.id);
if (done.status === 'failed') throw new Error(done.error.code);

const file = await client.batches.download(done.id);
await writeFile('customers-gender.csv', Buffer.from(await file.arrayBuffer()));

from namegender import NameGender

client = NameGender("YOUR_API_KEY")

job = client.batches.create("customers.csv", name_column="first_name", country_column="country")

done = client.batches.wait(job["id"])
if done["status"] == "failed":
    raise RuntimeError(done["error"]["code"])

client.batches.download(done["id"], "customers-gender.csv")

{
  "id": "B-7K2M9QX4TA",
  "status": "completed",
  "source": "api",
  "file": { "name": "customers.csv", "format": "csv" },
  "columns": { "name": "first_name", "country": "country" },
  "rows": { "total": 200000, "processed": 200000, "identified": 187412 },
  "progress": 100,
  "credits": { "reserved": 200000, "charged": 200000 },
  "summary": { "male": 96120, "female": 91292, "unknown": 12588, "from_llm": 0 },
  "error": null,
  "result": {
    "url": "https://namegender.com/api/v1/batches/B-7K2M9QX4TA/result",
    "format": "csv",
    "expires_at": "2026-10-01T10:04:12Z"
  },
  "poll_after_seconds": null
}

name_column es obligatorio para iniciar: una columna adivinada que resulte incorrecta gastaría créditos en los datos equivocados. Envía start=false para ver primero las columnas, una vista previa y el coste, y luego inicia el trabajo.

Envía una cabecera Idempotency-Key. Un reintento con la misma clave devuelve el primer trabajo en lugar de abrir otro.

Puede haber hasta 3 trabajos en cola o en ejecución a la vez. Un trabajo que no ha empezado se puede cancelar y se devuelve su crédito; uno en proceso no se puede detener.

Webhooks

Añade un endpoint en Webhooks de tu panel y le enviaremos un POST firmado cuando un trabajo de archivo termine o falle, sin que tengas que consultar.

Verifica cada petición

v1 es el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar, con el secreto de tu endpoint. Compara en tiempo constante, acepta la petición si coincide algún v1 y rechaza una marca de tiempo que difiera más de cinco minutos de tu reloj. Las bibliotecas cliente hacen todo esto en una llamada.

import express from 'express';
import { webhooks, NameGenderWebhookError } from 'namegender';

const app = express();

// express.raw, not express.json: the signature covers the exact bytes.
app.post('/namegender', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = await webhooks.verify(
      req.body,
      req.get('NameGender-Signature'),
      process.env.NAMEGENDER_WEBHOOK_SECRET,
    );
  } catch (error) {
    if (error instanceof NameGenderWebhookError) return res.sendStatus(400);
    throw error;
  }

  res.sendStatus(204);   // answer first, then do the work

  if (event.type === 'batch.completed') {
    const job = event.data.object;   // same object as GET /batches/{id}
  }
});

import os
from flask import Flask, request
from namegender import webhooks, WebhookVerificationError

app = Flask(__name__)

@app.post("/namegender")
def namegender_webhook():
    try:
        event = webhooks.verify(
            request.get_data(),   # raw bytes, not request.json
            request.headers.get("NameGender-Signature"),
            os.environ["NAMEGENDER_WEBHOOK_SECRET"],
        )
    except WebhookVerificationError:
        return "", 400

    if event["type"] == "batch.completed":
        job = event["data"]["object"]   # same object as GET /batches/{id}
    return "", 204

<?php

$body   = file_get_contents('php://input');   // raw body, before json_decode
$header = $_SERVER['HTTP_NAMEGENDER_SIGNATURE'] ?? '';
$secret = getenv('NAMEGENDER_WEBHOOK_SECRET');

parse_str(str_replace(',', '&', $header), $parts);   // t=…&v1=…
preg_match_all('/v1=([0-9a-f]{64})/', $header, $m);

$t = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$valid = abs(time() - $t) <= 300
    && array_filter($m[1], fn ($sig) => hash_equals($expected, $sig));

if (! $valid) {
    http_response_code(400);
    exit;
}

http_response_code(204);
$event = json_decode($body, true);

{
  "id": "evt_16f7c01502fda5436e8b7c4e",
  "type": "batch.completed",
  "created_at": "2026-09-24T10:04:12Z",
  "api_version": "v1",
  "data": {
    "object": {
      "id": "B-7K2M9QX4TA",
      "status": "completed",
      "rows": { "total": 200000, "processed": 200000, "identified": 187412 },
      "credits": { "reserved": 200000, "charged": 200000 },
      "result": { "url": "…/api/v1/batches/B-7K2M9QX4TA/result", "format": "csv" }
    }
  }
}

• Responde con cualquier 2xx en menos de 10 segundos y haz el trabajo después.
• Cualquier otra respuesta, redirecciones incluidas, se reintenta hasta 7 veces durante unas 45 horas. Si un endpoint sigue fallando tres días, se desactiva y te enviamos un correo.
• Un reintento lleva el mismo id y el orden no está garantizado. Deduplica por NameGender-Event-Id y lee el trabajo con GET cuando necesites su estado actual.
• Al renovar el secreto en el panel, el anterior sigue firmando 24 horas, así actualizas tu servidor sin perder eventos.
• Pueden añadirse nuevos tipos de evento. Responde 2xx a un tipo que no gestiones e ignóralo.

Distribución por país

Devuelve los países donde se registra un nombre. Se devuelven dos listas que deliberadamente no se fusionan: `registrations` es el volumen medido, comparable solo entre los once países que publican estadísticas de nombres contabilizadas, y `attested_in` es presencia, sin ponderación asignada.

curl "https://namegender.com/api/v1/gender/countries?name=Mehmet" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49994,
  "took_ms": 3,
  "name": "Mehmet",
  "basis": {
    "counted_sources": ["ssa", "ons", "nrs", "nisra", "insee", "statcan", "ine", "cso", "ssb", "statat", "pesel", "bfs"],
    "counted_countries": 8,
    "attested_countries": 16,
    "note": "Shares are calculated only across countries that publish counted name statistics…"
  },
  "registrations": [
    { "country": "CH", "count": 3890, "share": 29.45, "gender": "male", "source": "bfs"    },
    { "country": "FR", "count": 3775, "share": 28.58, "gender": "male", "source": "insee"  },
    { "country": "PL", "count": 1808, "share": 13.69, "gender": "male", "source": "pesel"  }
  ],
  "attested_in": ["AL","AT","AU","BE","CA","CH","ES","FR","GB","KS","MK","NO","PL","SE","TR","US"]
}

Un crédito por solicitud. `share` se calcula sobre todos los países con conteo, así que suma 100 solo cuando `limit` no recorta la lista; `counted_countries` también cuenta antes del recorte. `attested_in` no incluye porcentajes porque no hay conteo detrás de esos registros para calcularlo.

Saludo

Convierte un nombre en un saludo listo para una carta o un correo, en diez idiomas: “Sehr geehrte Frau Dr. Müller,”, “Sayın Ahmet Bey,”, “Madame,”, “山田様”. La consulta de género está incluida y cuesta el mismo crédito. Cada respuesta trae una línea formal, una informal y una neutra, además de las partes de la línea formal.

curl -X POST "https://namegender.com/api/v1/salutation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dr. Anna Müller", "language": "de"}'

{
  "credits_charged": 1,
  "credits_remaining": 49993,
  "language": "de",
  "form": "gendered",
  "reason": null,
  "salutation": {
    "formal": "Sehr geehrte Frau Dr. Müller,",
    "informal": "Liebe Anna,",
    "neutral": "Guten Tag Dr. Anna Müller,"
  },
  "parts": { "opening": "Sehr geehrte", "courtesy": "Frau", "academic": "Dr.", "name": "Müller" },
  "gender": "female",
  "gender_source": "lookup",
  "probability": 99,
  "first_name": "Anna",
  "last_name": "Müller",
  "name_type": "personal"
}

Un género equivocado es peor que ninguno, así que la forma con género solo se usa cuando el género se conoce con al menos `min_probability` y el idioma tiene la parte del nombre que necesita. Si no, `form` es `neutral` y `reason` explica por qué. Las empresas y las direcciones de cargo reciben `form: organization`. `best_guess` y `ai_fallback` no se aplican aquí.

POST /api/v1/salutation/bulk acepta hasta 100 nombres en `names`, un crédito cada uno, con las mismas opciones aplicadas a cada nombre.

Comprobación de nombre

Indica si un nombre escrito en un formulario de registro o de captación parece el nombre de una persona real, y por qué. Detecta tecleo al azar (“asdf qwerty”), valores de relleno (“Test Test”, “John Doe”, “n/a”), personajes de ficción (“Mickey Mouse”), groserías y dígitos, símbolos o direcciones de correo en el campo del nombre. Un crédito por nombre.

curl -X POST "https://namegender.com/api/v1/name-check" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "asdf qwerty"}'

{
  "credits_charged": 1,
  "credits_remaining": 49992,
  "query": "asdf qwerty",
  "assessment": "implausible",
  "score": 0,
  "signals": [
    { "code": "placeholder", "severity": "high", "part": "first_name", "value": "asdf" },
    { "code": "keyboard_pattern", "severity": "high", "part": "first_name", "value": "asdf" },
    { "code": "keyboard_pattern", "severity": "high", "part": "last_name", "value": "qwerty" }
  ],
  "first_name": "Asdf",
  "last_name": "Qwerty",
  "name_type": "personal",
  "evidence": { "first_name_status": "not_found", "first_name_counted_records": 0 }
}

`assessment` es `implausible` cuando hay una señal de gravedad alta (patrón de teclado, letras repetidas, valor de relleno, grosería, correo o URL), `suspicious` con una media (personaje de ficción, dígitos, símbolos, nombre de empresa, sin vocales, muy largo) o dos bajas, y `plausible` en los demás casos. `score` va de 0 a 100 para que fijes tu propio umbral. Un nombre de pila que aparece en registros oficiales de nacimientos lo sube; un nombre que nunca hemos visto no lo baja por sí solo. Los apellidos se juzgan solo por su forma: detrás de este endpoint no hay un conjunto de datos de apellidos.

Probado con 4.610 nombres de pila reales en nueve escrituras, solos y junto a un apellido: ninguno se marcó como sospechoso o inverosímil. Los apellidos como Null, Test o Cockburn, los nombres de dos letras como Ng y los nombres únicos se dejan en paz a propósito.

POST /api/v1/name-check/bulk acepta hasta 100 nombres en `names`, un crédito cada uno, con un resumen de las tres valoraciones.

Edad por nombre

Qué edad tienen las personas vivas con un nombre de pila: la edad mediana, la mitad central (`age_range`) y el 80% central (`age_range_80`). Brittany en Estados Unidos: mediana 36, la mitad entre 32 y 38. Un crédito por nombre.

curl "https://namegender.com/api/v1/age?name=Brittany" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49991,
  "request_id": "req_8f2c1a",
  "name": "Brittany",
  "first_name": "Brittany",
  "gender": null,
  "age": 36,
  "age_range": { "low": 32, "high": 38 },
  "age_range_80": { "low": 28, "high": 41 },
  "birth_year": 1990,
  "sample_size": 353775,
  "births": 361434,
  "country": "US",
  "country_source": "default",
  "source": "ssa",
  "series": "1880-2024",
  "reference_year": 2026,
  "reason": null
}

Método: nacimientos registrados por nombre, sexo y año, con cada año ponderado por la proporción de esa cohorte de nacimiento que sigue viva (tablas de mortalidad por cohorte de la SSA). Fuentes: nacimientos SSA 1880–2024 (US), INSEE 1900–2025 (Francia), SSB 1945–2025 (Noruega). `reason` es `not_found` para un nombre que no está en la serie e `insufficient_data` por debajo de 100 personas vivas.

Los nacimientos en el extranjero no están en ninguna serie, así que los nombres comunes entre inmigrantes parecen más jóvenes de lo que son. La serie de Noruega empieza en 1945, por lo que faltan las personas nacidas antes. La tabla de mortalidad de Estados Unidos se usa también para Francia y Noruega.

POST /api/v1/age/bulk acepta hasta 100 nombres en `names`, un crédito cada uno, en el orden de envío.

Saldo

Consulta tu saldo de créditos y lo que queda de la asignación gratuita de hoy. Esta llamada no se cobra.

curl "https://namegender.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "you@example.com",
  "credits_remaining": 50099,
  "purchased_credits": 50000,
  "free_today": 99,
  "free_daily_limit": 100,
  "lifetime_requests": 12480
}

Escrituras no latinas

Envía un nombre en su escritura original y lo vinculamos con los datos de referencia. Sin parámetros adicionales: detectamos la escritura y elegimos la estrategia correcta.

# Arap yazısı — ünsüz iskeleti üzerinden eşleşir
curl "https://namegender.com/api/v1/gender?name=%D9%85%D8%AD%D9%85%D8%AF" -H "Authorization: Bearer KEY"
# -> { "gender": "male", "probability": 100, "source": "script", "matched_as": "mahamad" }

# Çince — soyadı ayıklanır, verilen ad sorgulanır
curl "https://namegender.com/api/v1/gender?name=%E6%9D%8E%E6%98%8E" -H "Authorization: Bearer KEY"
# -> { "gender": "male", "probability": 92, "source": "db" }

Cuando no podemos convertir un sistema de escritura, la respuesta es gender: null con source: none. Verifica el campo source: script significa que transliteramos, db significa que coincidimos directamente con los caracteres que enviaste. Los dos tienen diferentes niveles de confianza, y te mostramos cuál obtuviste.

Campos de respuesta

Idénticos en todos los endpoints.

Dos campos que otros servicios no ofrecen

source te dice de dónde vino la respuesta: la base de datos de referencia, una coincidencia aproximada o el fallback de IA. matched_as nombra la entrada en la que aterrizó la coincidencia aproximada. Juntos te permiten decidir cuánto confiar en un resultado individual en lugar de aceptarlo sin cuestionarlo.

Códigos de error

El código de estado HTTP te indica que una llamada falló. Después, el cuerpo JSON nombra el motivo en error, lo explica en message y te da un request_id para citar al soporte, además de un enlace a la fila correspondiente más abajo. Decide siempre según error, nunca según message: los mensajes se traducen y pueden redactarse de otra forma.

{
  "error": "no_credits",
  "message": "You are out of credits. Buy more or wait for your daily free quota to reset.",
  "request_id": "req_9c1f5b2a7e0d4a13",
  "docs": "https://namegender.com/docs#error-no_credits"
}

Límites de velocidad

El uso normal no alcanza un límite. El tope existe para evitar que una clave filtrada sea abusada, y se cuenta por clave API en lugar de por IP para que varios clientes en un servidor no consuman la asignación de otros.

Límite actual: 1.200 solicitudes por minuto por clave. ¿Necesitas más? Pregunta y lo aumentaremos en tu cuenta.

Cada respuesta lleva los headers estándar X-RateLimit-Limit y X-RateLimit-Remaining.