REST API Referenz

Schnelleinstieg

Erstellen Sie einen Schlüssel in Ihrem Dashboard und senden Sie Ihre erste Anfrage. Kein SDK erforderlich.

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

Jeder Endpoint gibt die gleiche Struktur zurück, sodass Sie Eingaben wechseln können, ohne Ihren Parse-Code zu ändern.

Authentifizierung

Jede Anfrage trägt Ihren API-Schlüssel in einem Header. Verwenden Sie standardmäßig Authorization: Bearer, oder X-Api-Key, wenn Ihr HTTP-Client den Authorization-Header für etwas anderes reserviert. Ein Schlüssel in der URL wird abgelehnt: URLs landen in Proxy-Logs, Analyse-Tools und im Browser-Verlauf.

Authorization: Bearer ng_live_xxxxxxxxxxxx

X-Api-Key: ng_live_xxxxxxxxxxxx

Sie können einen Schlüssel im Dashboard auf bestimmte IP-Adressen beschränken.

Client-Bibliotheken

Dünne Wrapper über der REST API. Sie senden Ihren Schlüssel mit, bauen jede Anfrage auf und wandeln Fehlerantworten in Exceptions um.

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

Sie benötigen keine. Die API besteht aus einer Handvoll einfacher JSON-Endpoints; eine Bibliothek spart Ihnen einen Nachmittag, kein Projekt. Falls Ihre Sprache nicht aufgelistet ist, enthält die REST-Referenz Copy-Paste-Beispiele.

KI-Assistenten (MCP)

Nutzen Sie NameGender aus Claude, Cursor und jedem anderen Client, der das Model Context Protocol unterstützt. Fragen Sie den Assistenten zu einer Liste von Namen, und er ruft die API für Sie auf, mit den Belegen neben jeder Antwort.

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_..."
            }
        }
    }
}

Tools

gender_from_name

Geschlecht aus einem Vornamen oder vollständigen Namen.

gender_from_email

Liest den Namen in einer E-Mail-Adresse; Funktionsadressen wie info@ ergeben „unbekannt“.

gender_from_username

Liest den Namen in einem Benutzernamen oder Handle.

gender_bulk

Bis zu 100 Werte in einer Anfrage, mit einer Zusammenfassung der Trefferquote.

name_countries

Länder, in denen ein Name erfasst ist. Keine Aussage über die Herkunft.

salutation

Anrede für einen Brief in dessen Sprache; die neutrale Form, wenn das Geschlecht nicht sicher ist.

name_check

Ob ein in ein Formular eingetippter Name echt aussieht, mit den Gründen. Bezeichnet nie einen Namen als gefälscht.

age_from_name

Medianalter und Altersspannen der Menschen mit einem Vornamen in den Vereinigten Staaten, Frankreich und Norwegen.

account_status

Verbleibendes Guthaben und das heutige Freikontingent.

Jede Abfrage verbraucht Guthaben des Kontos, dem der Schlüssel gehört, genau wie ein direkter API-Aufruf. In der offiziellen MCP-Registry als io.github.anpekesen/namegender gelistet. npm-Paket · Quelle

Geschlecht aus Name

Akzeptiert einen Vornamen oder einen vollständigen Namen. Titel, Zweitnamen und Nachnamen werden vor der Suche entfernt, sodass "Dr. Ayşe Yılmaz" und "Ayşe" die gleiche Antwort geben.

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
}

Geschlecht aus E-Mail

Extrahiert die Person aus dem lokalen Teil der Adresse und klassifiziert diese dann. "ayse.yilmaz84@example.com" wird zu Ayşe aufgelöst.

best_guess wirkt auf den aus der Adresse gelesenen Vornamen, nicht auf die Adresse selbst. Lässt sich kein Vorname lesen, gibt es nichts zu erzwingen, und gender bleibt null. Beachten Sie: Eine erzwungene Antwort beruht hier auf einer Extraktion, die selbst falsch sein kann.

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"
}

Geschlecht aus Benutzername

Verarbeitet camelCase, snake_case, nachfolgende Ziffern und führende @-Zeichen. "AyseYilmaz84" wird zu Ayşe aufgelöst.

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"
}

Bulk-Anfrage

Senden Sie bis zu 100 Namen in einer Anfrage. Verwenden Sie dies statt einer Schleife: Ein Bulk-Aufruf für 100 Namen ist eine einzelne Roundtrip und eine einzelne deduplizierte Suche.

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" }
  ]
}

Ergebnisse werden in der gleichen Reihenfolge zurückgegeben, in der Sie sie gesendet haben. Guthschriften werden pro Name berechnet, und die gesamte Anfrage wird abgelehnt, bevor eine Arbeit beginnt, wenn Ihr Guthaben nicht ausreichend ist. Sie erhalten daher niemals einen halb verarbeiteten Batch.

Der Summary-Block zeigt Ihnen die Übereinstimmungsquote auf einen Blick, sodass Sie entscheiden können, ob die Eingabe vor der Verarbeitung des Rests bereinigt werden muss.

Dateiaufträge

Laden Sie eine CSV- oder XLSX-Datei mit bis zu 100 MB und 1.000.000 Zeilen hoch und erhalten Sie sie mit Geschlechtsspalten für jede Zeile zurück. Ein Credit pro Zeile, berechnet nur, wenn der Auftrag abgeschlossen wird.

1. 1. POST /batches Senden Sie die Datei und name_column. Der Auftrag wird sofort eingereiht.
2. 2. GET /batches/{id} Lesen Sie den Auftrag, bis status completed oder failed ist. poll_after_seconds gibt an, wie lange zwischen zwei Abfragen zu warten ist.
3. 3. GET /batches/{id}/result Laden Sie das Ergebnis herunter. Es kommt im hochgeladenen Format zurück.

# 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 ist zum Starten erforderlich: Eine geratene Spalte, die sich als falsch herausstellt, würde Credits für die falschen Daten verbrauchen. Senden Sie start=false, um zuerst Spalten, eine Vorschau und die Kosten zu sehen, und starten Sie dann den Auftrag.

Senden Sie einen Idempotency-Key-Header. Ein erneuter Versuch mit demselben Schlüssel liefert den ersten Auftrag, statt einen zweiten zu eröffnen.

Bis zu 3 Aufträge können gleichzeitig eingereiht sein oder laufen. Ein nicht gestarteter Auftrag kann abgebrochen werden und sein Credit wird erstattet; ein laufender Auftrag kann nicht gestoppt werden.

Webhooks

Fügen Sie im Dashboard unter Webhooks einen Endpunkt hinzu; wir senden ihm einen signierten POST, wenn ein Dateiauftrag abgeschlossen ist oder fehlschlägt, damit Sie nicht abfragen müssen.

Jede Anfrage prüfen

v1 ist der HMAC-SHA256 aus Zeitstempel, einem Punkt und dem Roh-Body, mit dem Geheimnis Ihres Endpunkts. Vergleichen Sie in konstanter Zeit, akzeptieren Sie die Anfrage, wenn irgendein v1 passt, und lehnen Sie Zeitstempel ab, die mehr als fünf Minuten von Ihrer Uhr abweichen. Die Client-Bibliotheken erledigen das in einem Aufruf.

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" }
    }
  }
}

• Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx und erledigen Sie die Arbeit danach.
• Alles andere, auch eine Weiterleitung, wird innerhalb von etwa 45 Stunden bis zu 7 Mal wiederholt. Schlägt ein Endpunkt drei Tage lang fehl, wird er abgeschaltet und Sie erhalten eine E-Mail.
• Eine Wiederholung trägt dieselbe Ereignis-ID, und die Reihenfolge ist nicht garantiert. Deduplizieren Sie über NameGender-Event-Id und lesen Sie den Auftrag per GET, wenn Sie seinen aktuellen Stand brauchen.
• Beim Erneuern des Geheimnisses im Dashboard signiert das alte noch 24 Stunden mit, sodass Sie Ihren Server ohne verpasste Ereignisse umstellen können.
• Neue Ereignistypen können hinzukommen. Antworten Sie auf einen Typ, den Sie nicht verarbeiten, mit 2xx und ignorieren Sie ihn.

Länderverteilung

Gibt die Länder zurück, in denen ein Name registriert ist. Es werden zwei Listen zurückgegeben, die absichtlich nicht zusammengeführt werden: `registrations` zeigt das gemessene Volumen und ist nur zwischen den elf Ländern vergleichbar, die gezählte Namensstatistiken veröffentlichen; `attested_in` zeigt die Präsenz ohne Gewichtung.

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"]
}

Ein Guthaben pro Anfrage. `share` wird über alle Länder mit gezählten Daten berechnet und ergibt daher nur dann 100, wenn `limit` die Liste nicht kürzt; auch `counted_countries` zählt vor der Kürzung. `attested_in` enthält keine Prozentsätze, da es keine Zahlen gibt, aus denen man diese berechnen könnte.

Anrede

Macht aus einem Namen eine Anrede, fertig für Brief oder E-Mail, in zehn Sprachen: „Sehr geehrte Frau Dr. Müller,“, „Sayın Ahmet Bey,“, „Madame,“, „山田様“. Die Geschlechtsbestimmung ist enthalten und kostet weiterhin ein Guthaben. Jede Antwort enthält eine formelle, eine informelle und eine neutrale Zeile sowie die Bestandteile der formellen Zeile.

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"
}

Ein falsches Geschlecht ist schlimmer als gar keins. Die geschlechtsspezifische Form wird daher nur verwendet, wenn das Geschlecht mit mindestens `min_probability` bekannt ist und die Sprache den benötigten Namensteil hat. Andernfalls ist `form` gleich `neutral`, und `reason` nennt den Grund. Firmen und Funktionsadressen erhalten `form: organization`. `best_guess` und `ai_fallback` gelten hier nicht.

POST /api/v1/salutation/bulk nimmt bis zu 100 Namen in `names` an, ein Guthaben pro Name, mit denselben Optionen für jeden Namen.

Namensprüfung

Sagt, ob ein in ein Anmelde- oder Lead-Formular eingetippter Name wie der Name einer echten Person aussieht, und warum. Erkennt wahlloses Tippen auf der Tastatur („asdf qwerty“), Platzhalter („Test Test“, „John Doe“, „n/a“), fiktive Figuren („Mickey Mouse“), Schimpfwörter sowie Ziffern, Symbole oder E-Mail-Adressen im Namensfeld. Ein Guthaben pro Name.

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` ist `implausible` bei einem Signal hoher Schwere (Tastaturmuster, wiederholte Buchstaben, Platzhalter, Schimpfwort, E-Mail oder URL), `suspicious` bei einem mittleren (fiktive Figur, Ziffern, Symbole, Firmenname, keine Vokale, sehr lang) oder zwei niedrigen, sonst `plausible`. `score` reicht von 0 bis 100 für Ihren eigenen Schwellenwert. Ein Vorname aus amtlichen Geburtsregistern erhöht ihn; ein Name, den wir nie gesehen haben, senkt ihn allein nicht. Nachnamen werden nur nach ihrer Form beurteilt: Hinter diesem Endpoint steht kein Nachnamen-Datensatz.

Getestet mit 4.610 echten Vornamen in neun Schriften, allein und mit Nachnamen: Keiner wurde als verdächtig oder unplausibel markiert. Nachnamen wie Null, Test oder Cockburn, zweibuchstabige Namen wie Ng und Einzelnamen bleiben bewusst unbeanstandet.

POST /api/v1/name-check/bulk nimmt bis zu 100 Namen in `names` an, ein Guthaben pro Name, mit einer Zusammenfassung der drei Bewertungen.

Alter aus dem Namen

Wie alt die lebenden Menschen mit einem Vornamen sind: das Medianalter, die mittlere Hälfte (`age_range`) und die mittleren 80% (`age_range_80`). Brittany in den Vereinigten Staaten: Median 36, die Hälfte zwischen 32 und 38. Ein Guthaben pro Name.

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
}

Methode: registrierte Geburten nach Name, Geschlecht und Jahr, jedes Jahr gewichtet mit dem Anteil dieses Geburtsjahrgangs, der noch lebt (Kohortensterbetafeln der SSA). Quellen: SSA-Geburten 1880–2024 (US), INSEE 1900–2025 (Frankreich), SSB 1945–2025 (Norwegen). `reason` ist `not_found` für einen Namen, der nicht in der Reihe steht, und `insufficient_data` bei weniger als 100 lebenden Personen.

Im Ausland Geborene stehen in keiner Reihe, daher wirken unter Eingewanderten verbreitete Namen jünger, als sie sind. Die norwegische Reihe beginnt 1945, früher Geborene fehlen also. Die US-Sterbetafel wird auch für Frankreich und Norwegen verwendet.

POST /api/v1/age/bulk nimmt bis zu 100 Namen in `names` an, ein Guthaben pro Name, in der gesendeten Reihenfolge.

Guthaben

Fragen Sie Ihr Guthaben und den Rest des heutigen Freikontingents ab. Dieser Aufruf wird nicht berechnet.

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
}

Nicht-lateinische Schriftsysteme

Senden Sie einen Namen in seiner eigenen Schrift und wir verbinden ihn mit den Referenzdaten. Kein zusätzlicher Parameter erforderlich: Wir erkennen das Schriftsystem und wählen die passende Strategie.

# 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" }

Wenn wir eine Schrift überhaupt nicht zuordnen können, ist die Antwort gender: null mit source: none. Prüfen Sie das source-Feld: script bedeutet, wir haben transliteriert, db bedeutet, wir haben die Zeichen, die Sie gesendet haben, direkt abgeglichen. Die beiden haben unterschiedliche Konfidenz, und wir zeigen Ihnen, welche Sie erhalten haben.

Antwortfelder

Identisch über alle Endpoints.

Zwei Felder, die andere Services nicht bieten

source zeigt dir, woher die Antwort stammt: aus der Referenzdatenbank, einem unscharfen Match oder dem KI-Fallback. matched_as benennt den Datensatz, auf den das unscharfe Match traf. Zusammen ermöglichen sie dir zu entscheiden, wie sehr du einem einzelnen Ergebnis vertraust, statt es blind zu akzeptieren.

Fehlercodes

Der HTTP-Statuscode zeigt dir, dass ein Aufruf fehlgeschlagen ist. Der JSON-Body nennt dann den Grund in error, erklärt ihn in message und liefert eine request_id für den Support sowie einen Link zur passenden Zeile weiter unten. Verzweige immer anhand von error, nie anhand von message: Meldungen werden übersetzt und können umformuliert werden.

{
  "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"
}

Rate Limits

Normale Nutzung erreicht kein Limit. Die Obergrenze verhindert Missbrauch durch einen durchgesickerten Schlüssel und wird pro API-Schlüssel gezählt, nicht pro IP, damit mehrere Kunden auf einem Server die Quote des jeweils anderen nicht verbrauchen.

Aktuelles Limit: 1.200 Anfragen pro Minute pro Schlüssel. Brauchst du mehr? Frag uns, wir erhöhen das Limit für dein Konto.

Jede Antwort enthält die Standard-Header X-RateLimit-Limit und X-RateLimit-Remaining.