JSON-Antwort verstehen
Einzelvorhersagen von GenderAPI.io V2 liefern ein data-Objekt für das Ergebnis und ein meta-Objekt für Angaben zu Anfrage, Zugang und Abrechnung. Lesen Sie data.gender und data.confidence zusammen mit data.confidence_kind und data.source. Das folgende Datensatzbeispiel ist eine echte Antwort, die am 1. Oktober 2026 mit einem API-Schlüssel abgerufen wurde; nur das Kontoguthaben wurde ersetzt. Es gibt keine gemessene Produktgenauigkeit wieder, und eine Live-Anfrage kann ein anderes Ergebnis liefern. Anfragen mit API-Schlüssel melden access.mode: api_key und null in den Kontingentfeldern, die nur für den Testzugang gelten; Anfragen über den IP-Testzugang melden ip_trial mit dem Testlimit und dem Zeitpunkt der Zurücksetzung.
{
"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
}
}
}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. |
Zurückgegebene Eingabefelder
| Feld | Typ | Kann null sein | Beispiel | Beschreibung |
|---|---|---|---|---|
data.input.type | string | Nein | "name" | Eingabekategorie: name, email oder username. |
data.input.value | string | Nein | "Anna" | Der übermittelte Wert für die Vorhersage. |
data.input.country | string | Ja | "DE" | Übermittelter Länderkontext; null, wenn weggelassen. |
data.input.forceToGenderize | boolean | Nein | true | Nur bei aktiviertem Spitznamenmodus vorhanden; sonst weggelassen. |
Felder zum Datensatz-Abgleich
| Feld | Typ | Kann null sein | Beispiel | Beschreibung |
|---|---|---|---|---|
data.match.name | string | Ja | "anna" | Ausgewählter Kandidat aus dem Datensatz; null, wenn keine Datensatzzeile ausgewählt wurde. |
data.match.method | string | Ja | "normalized" | normalized, token, substring oder model_inference; null, wenn nicht verfügbar. |
data.match.scope | string | Ja | "country" | country oder global bei Datensatzabfragen; null bei KI oder fehlenden Belegen. |
data.match.country | string | Ja | "DE" | Land der ausgewählten Datensatzzeile; null bei globalen Zeilen oder KI. |
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. |
Ein erfolgreiches unbekanntes Ergebnis
HTTP 200 bedeutet, dass der Vorgang abgeschlossen wurde; ein Geschlecht ist damit nicht garantiert. Behalten Sie JSON null bei, statt es in male, female, eine leere Zeichenkette oder eine Konfidenz von null umzuwandeln. Prüfen Sie data.result_status und data.reason getrennt von HTTP-Fehlern.
Dieses echte Beispiel nur mit dem Datensatz, abgerufen am 1. Oktober 2026, liefert source: none und reason: not_found und kostet trotzdem 1 Credit. Eine Datensatzzeile mit Gleichstand kann reason: ambiguous liefern, wobei sample_count erhalten bleibt. Ein unbekanntes KI-Ergebnis verwendet source: ai und reason: insufficient_evidence.
{
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
},
"meta": {
"request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Konfidenz und Abgleichsbelege interpretieren
Eine Konfidenz von 0.9 liegt auf einer Skala von 0–1. Bei observed_frequency bedeutet sie die dominante Anzahl geteilt durch die Gesamtzahl der ausgewählten Datensatzzeile; sie ist keine gemessene End-to-End-Produktgenauigkeit. Ein model_reported-Wert stammt von der KI und ist nicht an den Häufigkeiten im Datensatz kalibriert.
Legen Sie Schwellenwerte für Ihre Anwendung anhand eigener Bewertungsdaten und confidence_kind fest. Stellen Sie Datensatz- und KI-Werte nicht direkt in eine Rangfolge, als würden sie dasselbe messen. Bei KI sind match.name, match.scope und match.country null, weil keine Datensatzzeile ausgewählt wurde; match.method ist model_inference.
Bei vollständigen Namen kann ein Datensatzergebnis von einem Bestandteil statt von der gesamten Zeichenkette stammen. data.input enthält den übermittelten Wert; data.name beschreibt den zurückgegebenen Namen, data.match den Kandidaten und den Geltungsbereich der Abfrage.
Entscheiden, was Ihre Anwendung als Nächstes tun soll
Behandeln Sie zuerst Fehler der Anfrage und einzelner Einträge und prüfen Sie dann result_status. Lesen Sie bei einer Einzelvorhersage data; wenden Sie bei einem Batch dieselbe Entscheidung auf data jedes erfolgreichen Eintrags an. Behalten Sie unbekannte Ergebnisse in Ihrer Anwendung bei, statt eine Kennzeichnung als male oder female zu erzwingen.
| Ergebnis | Bedeutung | Empfohlenes Vorgehen |
|---|---|---|
| identified; gender: male oder female | Die Vorhersage hat ein Geschlecht ergeben, gestützt auf Belege aus dem Datensatz oder der KI. | Wenden Sie eine für diesen confidence_kind bewertete Regel an; behalten Sie source und die Abgleichsbelege bei. |
| unknown; reason: not_found | Kein gespeicherter Datensatzeintrag passte zu den ermittelten Kandidaten. | Behalten Sie gender als null bei. Eine bewusste Anfrage mit anderen KI-Optionen ist ein neuer kostenpflichtiger Vorgang. |
| unknown; reason: no_name_candidate | Die Auswertung für den Datensatz hat keinen verwertbaren Namenskandidaten ergeben. | Behalten Sie null bei; prüfen Sie Eingabetyp und Wert, bevor Sie eine zusätzliche Vorhersage wählen. |
| unknown; reason: ambiguous | Die ausgewählte Datensatzzeile hat gleich viele männliche und weibliche Einträge; sample_count kann trotzdem vorhanden sein. | Lösen Sie den Gleichstand nicht selbst auf und wandeln Sie die null-Konfidenz nicht in 0 um. |
| unknown; reason: insufficient_evidence | Die KI hat die Anfrage abgeschlossen, ohne genügend Belege für ein Geschlecht zu finden. | Behandeln Sie dies als abgeschlossenes unbekanntes Ergebnis, nicht als Anbieterfehler oder Kandidaten für eine automatische Wiederholung. |
| Problem Details oder error eines Eintrags | Die Ausführung ist fehlgeschlagen, zum Beispiel wegen ai_upstream_error oder prediction_timeout. | Bewahren Sie Fehlercode und Anfrage-ID auf, prüfen Sie die Abrechnung und folgen Sie den Hinweisen zu Wiederholungen. |
Schwellenwerte anhand Ihrer eigenen Bewertung wählen
Es gibt keinen universellen Konfidenz-Schwellenwert, der eine Vorhersage richtig macht. Bewerten Sie observed_frequency und model_reported getrennt anhand repräsentativer, unabhängig gekennzeichneter Beispiele aus Ihrem Anwendungsfall. Eine Häufigkeit im Datensatz und ein von der KI selbst gemeldeter Wert sind unterschiedliche Signale, auch wenn beide zufällig 0.9 betragen. Messen Sie, wie oft Ihre Regel eine Antwort gibt und wie oft diese Antworten richtig sind; sehen Sie für alles andere ein unbekanntes Ergebnis oder eine manuelle Prüfung vor.
Ist result_status zum Beispiel identified, confidence_kind aber model_reported, wenden Sie Ihre bewertete KI-Regel an und nicht den Schwellenwert für den Datensatz. Wurde forceToGenderize verwendet, ist name: null zusammen mit einem Geschlecht ungleich null gültig: Ein Alias kann ausgewertet werden, ohne dass ein echter Vorname extrahiert wird. Prüfen Sie gender und result_status, nicht nur name, um zu entscheiden, ob die Vorhersage ein Ergebnis geliefert hat. Das Ergebnis bleibt eine Schätzung und keine Bestätigung der Identität einer Person.