GenderAPI.io V2: Abfrage nach Vorname und vollständigem Namen

Vor dem Absenden der Anfrage

Senden Sie Vorhersageanfragen an GenderAPI.io V2 per POST https://api.genderapi.io/api/v2/gender, mit type und value im JSON-Body. Verwenden Sie Ihren vorhandenen GenderAPI.io-Schlüssel in Authorization: Bearer YOUR_API_KEY und Content-Type: application/json. Lesen Sie das Ergebnis aus data und die Angaben zu Zugang und Abrechnung aus meta. Jede Anfrage wird unabhängig verarbeitet.

Wählen Sie im Codebeispiel Ihre Programmiersprache. Setzen Sie GENDERAPI_API_KEY in der Prozessumgebung, bevor Sie es ausführen. Fehlende oder nicht erkannte Schlüssel können den gemeinsamen IP-Testzugang nutzen; prüfen Sie daher bei einer Kontointegration, ob meta.access.mode den Wert api_key hat.

Geschlecht aus einem Namen

Parameter	Typ	Erforderlich	Standardwert	Beschreibung
`type`	`string`	Ja	`—`	Eingabekategorie: name, email oder username.
`value`	`string`	Ja	`—`	Erforderlich. 1–254 Zeichen; nicht leer und ohne Steuerzeichen. E-Mail-Werte müssen eine gültige E-Mail-Syntax haben.
`country`	`string`	Nein	`—`	Optionaler ISO-3166-1-Alpha-2-Code in Großbuchstaben, zum Beispiel TR oder US. Eine länderspezifische Abfrage kann auf den globalen Datensatz zurückgreifen.
`forceToGenderize`	`boolean`	Nein	`false`	Zuerst den Datensatz prüfen, bei fehlendem Ergebnis KI mit Spitznamen-Auswertung. Unterstützt für name, email und username.
`options`	`object`	Nein	`—`	Objekt für die KI-Optionen der jeweiligen Eingabe.
`options.ai_mode`	`string`	Nein	`fallback`	Erlaubte Werte: off, fallback, always. Bei forceToGenderize: true dieses Feld weglassen oder fallback verwenden.
`id`	`string`	Nein	`—`	Optionale Kennung mit 1–64 Zeichen im POST-JSON. Wird neben dem jeweiligen Batch-Ergebnis zurückgegeben und muss innerhalb eines Batches eindeutig sein. Bei Einzelvorhersagen akzeptiert, aber nicht zurückgegeben. In GET-Queries nicht unterstützt.

Senden Sie für einen Vornamen oder vollständigen Namen type: name und die vollständige Eingabe in value an POST https://api.genderapi.io/api/v2/gender. GenderAPI.io V2 verwendet für beide Namensformate dieselben Anfragefelder. Auch eine erfolgreiche Antwort kann data.gender: null enthalten. Einzelanfragen prüfen zuerst den Datensatz und nutzen standardmäßig KI, wenn sich daraus kein Geschlecht ermitteln lässt.

Wählen Sie eine Programmiersprache. Richten Sie Ihren API-Schlüssel ein, und führen Sie dann das Beispiel auf Ihrem Server aus.

Jede Vorhersageanfrage ist ein neuer kostenpflichtiger Vorgang, auch bei Wiederholungen. Diese Beispiele wiederholen Anfragen nicht automatisch. Prüfen Sie den Abrechnungsstatus, bevor Sie eine weitere Anfrage senden.

Vor der Ausführung: Zugang und Fehlerbehandlung

Führen Sie diese Beispiele auf Ihrem Server aus. Setzen Sie GENDERAPI_API_KEY in der Prozessumgebung auf Ihren vorhandenen API-Schlüssel. Prüfen Sie, ob meta.access.mode den Wert api_key hat: Ein nicht erkannter Schlüssel kann in den IP-Testzugang wechseln.

Bei HTTP-4xx- und -5xx-Antworten im JSON-Format bleibt der Fehlerinhalt erhalten, und das Beispiel endet mit einem Exit-Status ungleich null. Prüfen Sie code, action und meta.usage.billing_status, bevor Sie die Anfrage wiederholen.

Anleitung zu Fehlern und Wiederholungen →

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": "Anna",
  "country": "DE"
}'

cURL 7.76+ in einer POSIX-Shell. Im Terminal ausführen. Dokumentation der Laufzeitumgebung

// 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": "Anna",
  "country": "DE"
};

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+; integriertes fetch. Als example.mjs speichern und node example.mjs ausführen. Dokumentation der Laufzeitumgebung

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\":\"Anna\",\"country\":\"DE\"}")

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+; Standardbibliothek. Als example.py speichern und python3 example.py ausführen. Dokumentation der Laufzeitumgebung

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Anna","country":"DE"}', 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+ mit der cURL-Erweiterung. Als example.php speichern und php example.php ausführen. Dokumentation der Laufzeitumgebung

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\":\"Anna\",\"country\":\"DE\"}";
        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+; Standard-HTTP-Client. Als GenderApiExample.java speichern und java GenderApiExample.java ausführen. Dokumentation der Laufzeitumgebung

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\":\"Anna\",\"country\":\"DE\"}", 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.
}

Konsolenanwendung mit .NET 8+. Als Program.cs in einem Konsolenprojekt verwenden und dann dotnet run ausführen. Dokumentation der Laufzeitumgebung

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\":\"Anna\",\"country\":\"DE\"}"
    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+; Standardbibliothek. Als main.go speichern und go run main.go ausführen. Dokumentation der Laufzeitumgebung

Beispielantwort

Dies ist eine echte Antwort, die am 1. Oktober 2026 mit einem API-Schlüssel abgerufen wurde; nur das Kontoguthaben wurde ersetzt. Sie ist kein Maß für die Genauigkeit, und eine Live-Anfrage kann ein anderes Ergebnis liefern. Anfragen mit API-Schlüssel melden meta.access.mode: api_key und null in den Kontingentfeldern, die nur für den Testzugang gelten; Anfragen über den IP-Testzugang melden ip_trial. Lesen Sie data für die Vorhersage und meta.usage für das Abrechnungsergebnis des Vorgangs.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Anna",
      "country": "DE"
    },
    "name": "anna",
    "gender": "female",
    "country": "DE",
    "confidence": 0.9956427015250545,
    "confidence_kind": "observed_frequency",
    "sample_count": 918,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "anna",
      "method": "normalized",
      "scope": "country",
      "country": "DE"
    }
  },
  "meta": {
    "request_id": "5fa436aa-39e5-4785-9889-ad1b00be076d",
    "duration_ms": 11,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Antwortfelder und Konfidenz

Felder der Vorhersageantwort

Feld	Typ	Kann null sein	Beispiel	Beschreibung
`data.input`	`object`	Nein	`{"type":"name","value":"Anna","country":"DE"}`	Eingabetyp, Wert und Land. forceToGenderize ist enthalten, wenn es true ist.
`data.name`	`string`	Ja	`"anna"`	Gefundener oder extrahierter Vorname; null, wenn keiner verfügbar ist.
`data.gender`	`string`	Ja	`"male"`	male, female oder JSON null. Eine Vorhersage, keine bestätigte persönliche Identität.
`data.result_status`	`string`	Nein	`"identified"`	identified, wenn ein Geschlecht zurückgegeben wird; sonst unknown.
`data.reason`	`string`	Ja	`null`	null bei identified. Gründe für unknown: not_found, no_name_candidate, ambiguous oder insufficient_evidence.
`data.confidence`	`number`	Ja	`0.95`	Wert von 0–1 oder null. Ist gender null, ist auch die Konfidenz null.
`data.confidence_kind`	`string`	Ja	`"observed_frequency"`	observed_frequency: dominante Anzahl im Datensatz geteilt durch die Gesamtzahl. model_reported: KI-Wert, keine kalibrierte Wahrscheinlichkeit. null, wenn nicht verfügbar.
`data.sample_count`	`integer`	Ja	`1200`	Stichprobengröße im Datensatz oder null. KI erfindet keine Stichprobenzahl.
`data.source`	`string`	Nein	`"dataset"`	dataset, ai oder none.
`data.country`	`string`	Ja	`"DE"`	Länderzuordnung aus dataset oder ai_association, oder null. Belegt weder Nationalität noch Wohnsitz oder ethnische Zugehörigkeit.
`data.country_source`	`string`	Ja	`"dataset"`	Quelle der Länderzuordnung: dataset, ai_association oder null.
`data.match`	`object`	Nein	`{"name":"anna","method":"normalized","scope":"country","country":"DE"}`	Gefundener Name im Datensatz, Methode (normalized, token, substring oder model_inference), Geltungsbereich country oder global und zugeordnetes Land. Fehlende Belege sind null.

Zugang, Abrechnung und Anfragemetadaten

Feld	Typ	Kann null sein	Beispiel	Beschreibung
`meta.request_id`	`string`	Nein	`"550e8400-e29b-41d4-a716-446655440000"`	Eindeutige Kennung dieses HTTP-Versuchs; auch in X-Request-ID enthalten.
`meta.duration_ms`	`integer`	Nein	`42`	Bearbeitungszeit der Anfrage in Millisekunden.
`meta.access.mode`	`string`	Nein	`"api_key"`	api_key, ip_trial oder unauthenticated. Prüfen Sie bei einem bezahlten Konto, ob api_key gemeldet wird.
`meta.access.reason`	`string`	Ja	`null`	Grund für den Wechsel in den Testzugang: api_key_missing, api_key_invalid oder api_key_not_found; sonst null.
`meta.usage.charged_credits`	`integer`	Ja	`1`	Netto abgebuchte Credits. 0 vor der Abbuchung oder nach einer bestätigten vollständigen Erstattung; null bei unbestätigter Abrechnung.
`meta.usage.remaining_credits`	`integer`	Ja	`99`	Guthaben beim Abschluss des Vorgangs. Kann negativ sein; null, wenn nicht verfügbar oder die Abrechnung unbestätigt ist.
`meta.usage.billing_status`	`string`	Nein	`"confirmed"`	not_charged, confirmed oder unconfirmed. Prüfen Sie dies, bevor Sie eine fehlgeschlagene Vorhersage wiederholen.
`meta.usage.resets_at`	`string`	Ja	`"2026-09-27T12:00:00.000Z"`	Zeitpunkt des Zurücksetzens des IP-Testzugangs in UTC (ISO 8601); null bei Konten mit API-Schlüssel oder wenn unbekannt.
`meta.usage.limit`	`integer`	Ja	`10`	Kontingent des IP-Testzugangs; null bei Konten mit API-Schlüssel.
`meta.usage.period_seconds`	`integer`	Ja	`86400`	Zeitfenster des IP-Testzugangs in Sekunden; null bei Konten mit API-Schlüssel.

Länderkontext und unbekannte Namen

Geben Sie country nur an, wenn Sie über relevanten Kontext verfügen. Die API kann eine länderspezifische Zeile des Datensatzes auswählen oder auf eine globale Zeile zurückgreifen. data.match.scope zeigt, welche ausgewählt wurde; das zurückgegebene Land belegt nicht, wo die Person lebt.

Einzelanfragen nutzen standardmäßig den KI-Fallback für insgesamt 1 Credit. Um nur den Datensatz zu verwenden, senden Sie options: {"ai_mode": "off"}. Nicht aufgelöste Eingaben können gender: null zurückgeben und sind trotzdem kostenpflichtig, wenn der Vorgang erfolgreich ist. Ein vollständiger Name kann über einen seiner Bestandteile zugeordnet werden; data.match enthält den ausgewählten Kandidaten und die Abgleichsmethode.

Für spitznamenartige Namenswerte ermöglicht forceToGenderize: true eine Vorhersage ohne echten Vornamen: Ein im Datensatz aufgelöstes Ergebnis kostet 1 Credit, andernfalls kostet KI mit Spitznamen-Auswertung insgesamt 2 Credits. Ein positives Anfangsguthaben genügt, und das resultierende Guthaben kann negativ werden.

Einen vollständigen Namen abfragen, ohne anzunehmen, dass das erste Wort entscheidet

Senden Sie den ursprünglichen Namen in Unicode. Der Abgleich mit dem Datensatz wendet NFKC-Normalisierung, Kleinschreibung und die Extraktion einzelner Bestandteile an; Sie müssen den Namen nicht in ASCII umwandeln. Unter den verfügbaren Kandidaten wählt die API den Datensatzeintrag mit der größten gespeicherten Gesamtzahl. Dieser Kandidat kann ein späterer Bestandteil des Namens sein; gehen Sie daher nicht davon aus, dass das erste Wort oder der Vorname ausgewählt wurde.

Diese Anfrage nur mit dem Datensatz macht die ausgewählten Belege leichter nachvollziehbar. Lesen Sie data.input.value für den übermittelten vollständigen Namen, data.match.name für den abgefragten Kandidaten und data.match.method für die Abgleichsmethode. Das Beispiel verspricht weder ein bestimmtes Geschlecht noch einen bestimmten ausgewählten Bestandteil. Kandidaten aus dem Datensatz müssen länger als zwei Zeichen sein; kurze Eingaben können unaufgelöst bleiben. Nutzen Sie den gewöhnlichen KI-Fallback, wenn diese zusätzliche Vorhersage für Ihre Anwendung angemessen ist.

Wählen Sie eine Programmiersprache. Richten Sie Ihren API-Schlüssel ein, und führen Sie dann das Beispiel auf Ihrem Server aus.

Vor der Ausführung: Zugang und Fehlerbehandlung

Anleitung zu Fehlern und Wiederholungen →

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": "Ayşe Yılmaz",
  "country": "TR",
  "options": {
    "ai_mode": "off"
  }
}'

cURL 7.76+ in einer POSIX-Shell. Im Terminal ausführen. Dokumentation der Laufzeitumgebung

// 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": "Ayşe Yılmaz",
  "country": "TR",
  "options": {
    "ai_mode": "off"
  }
};

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+; integriertes fetch. Als example.mjs speichern und node example.mjs ausführen. Dokumentation der Laufzeitumgebung

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}")

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+; Standardbibliothek. Als example.py speichern und python3 example.py ausführen. Dokumentation der Laufzeitumgebung

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Ayşe Yılmaz","country":"TR","options":{"ai_mode":"off"}}', 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+ mit der cURL-Erweiterung. Als example.php speichern und php example.php ausführen. Dokumentation der Laufzeitumgebung

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}";
        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+; Standard-HTTP-Client. Als GenderApiExample.java speichern und java GenderApiExample.java ausführen. Dokumentation der Laufzeitumgebung

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}", 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.
}

Konsolenanwendung mit .NET 8+. Als Program.cs in einem Konsolenprojekt verwenden und dann dotnet run ausführen. Dokumentation der Laufzeitumgebung

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}"
    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+; Standardbibliothek. Als main.go speichern und go run main.go ausführen. Dokumentation der Laufzeitumgebung

Prüfen, welcher Länderkontext tatsächlich beigetragen hat

Verwenden Sie einen ISO-Ländercode nur, wenn Sie über relevanten Kontext verfügen; leiten Sie ihn nicht aus dem vorhergesagten Ergebnis ab. Für jeden Kandidaten hat eine vorhandene Länderzeile Vorrang vor seiner globalen Zeile. Gibt es keine Länderzeile, kann der Kandidat eine globale Zeile verwenden. Eine Länderzeile mit Gleichstand wird nicht durch ihre globale Zeile ersetzt: Hat die ausgewählte Zeile einen Gleichstand, ist das Ergebnis aus dem Datensatz unknown, und ein aktivierter KI-Fallback kann ausgeführt werden.

Beleg in der Antwort	Bedeutung	Vorgehen in der Anwendung
match.scope: country; match.country: TR	Der ausgewählte Kandidat aus dem Datensatz stammt aus der Zeile des angefragten Landes.	Speichern Sie den ausgewählten Kandidaten und den Länderbezug zusammen mit der Vorhersage.
match.scope: global; match.country: null	Der ausgewählte Kandidat stammt aus einer globalen Zeile, auch wenn die Anfrage ein Land enthielt.	Kennzeichnen Sie das Ergebnis nicht als länderspezifischen Treffer.
country_source: dataset oder ai_association	Erklärt die Herkunft von data.country, nicht den Geltungsbereich der Datensatzabfrage oder die Nationalität der Person.	Lesen Sie das Feld getrennt von match.country; keines der beiden Felder belegt Wohnsitz oder Nationalität.
source: ai; match.scope: null	Die endgültige Antwort stammt von der KI, daher enthält sie keine ausgewählte Datensatzzeile.	Wenden Sie die Hinweise zur KI-Konfidenz an und behalten Sie unbekannte Ergebnisse bei.

Vor dem Absenden der Anfrage

Geschlecht aus einem Namen

Beispielantwort

Felder der Vorhersageantwort

Zugang, Abrechnung und Anfragemetadaten

Länderkontext und unbekannte Namen

Einen vollständigen Namen abfragen, ohne anzunehmen, dass das erste Wort entscheidet

Prüfen, welcher Länderkontext tatsächlich beigetragen hat

Verwandte Anleitungen