GenderAPI.io V2 Hilfe
Häufig gestellte Fragen
Antworten zu V2-Anfragen, Konfidenz, unbekannten Ergebnissen, Credits, Datenschutz und Konto. Wenn Sie eine Integration mit der vorherigen Version pflegen, nutzen Sie die V1-Dokumentation.
Ergebnisse und Konfidenz
Vorhersagen und ihre Grenzen verstehen
Länderkontext, Konfidenzwerte und unbekannte Ergebnisse in API V2.
Bestimmt ein GenderAPI-Ergebnis das Geschlecht einer Person?
Nein. GenderAPI leitet das Geschlecht aus namensbezogenen Hinweisen ab oder, wenn diese Option aktiviert ist, aus Hinweisen in Spitznamen. Eine Vorhersage ist keine geprüfte Tatsache über eine Person. Bewahren Sie die Unsicherheit, respektieren Sie die Geschlechtsidentität, die eine Person selbst angibt, und stützen Sie Entscheidungen mit erheblichen Auswirkungen nicht allein auf diese Einschätzung.
Wie beeinflusst der Länderkontext ein Ergebnis?
Ein optionaler ISO-Ländercode in Großbuchstaben liefert regionalen Kontext für die Anfrage. Geben Sie ihn nur an, wenn er relevant und bekannt ist. Derselbe Name kann in verschiedenen Regionen unterschiedlich verwendet werden; das zurückgegebene Land beschreibt eine Zuordnung des Namens und ist kein Nachweis von Staatsangehörigkeit oder Wohnsitz.
Was bedeutet der Konfidenzwert in V2?
confidence ist ein Wert von 0 bis 1 oder null, wenn kein Wert verfügbar ist. Lesen Sie ihn zusammen mit confidence_kind: observed_frequency beschreibt die Anzahl der dominanten Kategorie im Datensatz geteilt durch die Gesamtanzahl; model_reported ist ein von der KI gemeldeter Wert. Diese Werte sind keine kalibrierten Wahrscheinlichkeiten über eine Person und keine gemessene Produktgenauigkeit. Legen Sie Prüfschwellen anhand repräsentativer Daten fest.
Was bedeutet gender: null, und wird ein solches Ergebnis berechnet?
Ein erfolgreiches V2-Ergebnis mit gender: null bedeutet, dass die verfügbaren Hinweise kein Geschlecht ermitteln konnten. Es handelt sich um den nativen JSON-Wert null, nicht um die Zeichenkette "null". Ein erfolgreiches unbekanntes Ergebnis wird zum Tarif des gewählten Modus abgerechnet. Behandeln Sie es als unbekannt; ein Anbieter- oder Anfragefehler ist ein separater Fehlerfall.
Kann ich Namen in verschiedenen Schriftsystemen senden?
Ja. Senden Sie Namen als Unicode mit ihren ursprünglichen Zeichen und bedeutungstragenden Akzenten. Abdeckung und Konfidenz hängen von Name, Region und verfügbaren Hinweisen ab. Testen Sie daher eine repräsentative Stichprobe der Schriftsysteme und Länder, die Ihre Anwendung abdeckt.
API und KI
Anfrageart und KI-Option wählen
V2-Anfragearten, Batches, KI-Verhalten und Nutzungslimits.
Kann ich Namen, E-Mail-Adressen und Benutzernamen in einem Batch auswerten?
Ja. POST /api/v2/gender/batch akzeptiert bis zu 50 Einträge mit API-Schlüssel oder 10 im IP-Testzugang. Jeder Eintrag hat eigene Felder type und value, ein optionales country und eigene KI-Einstellungen. Standardmäßig ist KI für Batch-Einträge deaktiviert. Prüfen Sie jedes Ergebnis: Ein Batch kann HTTP 200 zurückgeben, auch wenn einzelne Einträge fehlgeschlagen sind. Credits werden pro erfolgreich verarbeitetem Eintrag berechnet, auch für unbekannte Ergebnisse.
Wie funktioniert eine Anfrage mit einer E-Mail-Adresse?
Verwenden Sie type: email mit einer gültigen Adresse. Die API sucht im lokalen Teil vor dem @-Zeichen nach einem verwertbaren Namenssignal; die Domain sagt nichts über die Identität oder das Land einer Person aus. Gemeinsam genutzte Postfächer und nicht aussagekräftige Adressen können ein unbekanntes Ergebnis liefern. Eine Einzelanfrage nutzt standardmäßig KI, wenn der Datensatz kein Ergebnis liefert.
Wie funktioniert eine Anfrage mit einem Benutzernamen?
Verwenden Sie type: username. Eine gewöhnliche Anfrage sucht in einem Handle oder Anzeigenamen nach einem erkennbaren Vornamen. Abstrakte Aliase können ein unbekanntes Ergebnis liefern. Aktivieren Sie forceToGenderize, wenn nach einer ergebnislosen Prüfung des Datensatzes eine KI mit Spitznamen-Auswertung eingesetzt werden soll; so kann ein Geschlecht ermittelt werden, ohne dass ein echter Vorname extrahiert wird.
Wann nutzt V2 KI?
Einzelanfragen verwenden standardmäßig options.ai_mode: fallback: Zuerst wird der Datensatz geprüft; wird kein Geschlecht ermittelt, kommt KI zum Einsatz, für insgesamt 1 Credit. off nutzt nur den Datensatz für 1 Credit; always überspringt den Datensatz und nutzt KI für 2 Credits. Batch-Einträge verwenden standardmäßig off und können KI einzeln aktivieren. Keiner dieser Modi garantiert ein Ergebnis ungleich null.
Was bewirkt forceToGenderize?
Dieses optionale Flag funktioniert mit Namen, E-Mail-Adressen und Benutzernamen, auch in einzelnen Batch-Einträgen. Ein im Datensatz ermitteltes Ergebnis kostet 1 Credit. Andernfalls wird KI mit Spitznamen-Auswertung verwendet, insgesamt für 2 Credits, auch wenn das erfolgreiche Ergebnis unbekannt bleibt. Ein echter Vorname ist nicht erforderlich. Lassen Sie ai_mode weg oder verwenden Sie fallback; die Kombination des Flags mit off oder always führt zu 422.
Wie werden Credits in V2 abgebucht?
Lesen Sie meta.usage.charged_credits für die tatsächlich berechneten Credits eines Vorgangs und billing_status für deren Bestätigung. Gewöhnliche Vorhersagen aus dem Datensatz und im Modus fallback kosten 1 Credit pro erfolgreich verarbeitetem Eintrag; always und KI mit Spitznamen-Auswertung kosten 2 Credits. Eine abgeschlossene Validierung einer Telefonnummer kostet 1 Credit, auch bei ungültigem Ergebnis. Ein positives Startguthaben genügt, daher kann die endgültige Abbuchung das Guthaben negativ werden lassen. Credits für fehlgeschlagene Vorhersagen werden erstattet; eine unbestätigte Abrechnung muss vom Support geprüft werden.
Gibt es in V2 Anfragelimits?
Ja. Die aktuellen Standardwerte sind 120 Anfragen pro Minute und Konto, 600 pro Minute und IP-Adresse sowie 2 gleichzeitige Vorgänge pro Konto. Zusätzlich gilt die gemeinsam genutzte Kapazität des Dienstes. POST-Anfragen sind auf 64 KiB begrenzt; Batches erlauben 50 Einträge mit Schlüssel oder 10 im IP-Testzugang. Beachten Sie HTTP 429 und Retry-After, statt davon auszugehen, dass Anfragen bis zu diesen Obergrenzen immer angenommen werden.
Kann ich eine fehlgeschlagene oder abgelaufene Anfrage wiederholen?
Jede Vorhersageanfrage ist ein neuer Vorgang und wird regulär abgerechnet. Eine Zeitüberschreitung oder eine verlorene Antwort beweist nicht, dass keine Credits abgebucht wurden. Prüfen Sie vor einer Wiederholung billing_status; ist die Abrechnung nicht bestätigt, wenden Sie sich mit der request_id an den Support. Wiederholen Sie bei einem teilweise fehlgeschlagenen Batch nur die fehlgeschlagenen Einträge, sobald die Abrechnung bestätigt ist. Beachten Sie bei 429 den Header Retry-After.
Wo finde ich Codebeispiele und Tools für V2?
Die V2-Anleitungen enthalten Beispiele in cURL, JavaScript, Python, PHP, Java, C# und Go. Swagger und Postman verwenden denselben V2-Vertrag. Wählen Sie die Art der Eingabe und bewahren Sie Ihren API-Schlüssel in der serverseitigen Konfiguration auf.
Kann ich V1 weiterhin verwenden?
Ja. Bestehende V1-Integrationen behalten ihre bisherigen Endpunkte und Antwortformate. V1 und V2 verwenden denselben API-Schlüssel und dasselbe Guthaben, unterscheiden sich aber bei Anfragefeldern, Antworten und Fehlern. Nutzen Sie die separate V1-Dokumentation, um einen bestehenden Client zu pflegen, und die Migrationsanleitung, wenn Sie ihn umstellen möchten.
Datenschutz und Dateien
Datenverarbeitung verstehen
Wo Sie aktuelle Informationen zu Verarbeitung, Aufbewahrung und Löschung finden.
Werden erfolgreiche GenderAPI-Anfragen gespeichert?
Die Datenschutzerklärung erläutert, welche Anfragedaten, Betriebsdaten und Sicherheitsprotokolle aufbewahrt werden können, zu welchem Zweck sie verarbeitet werden und wie die Löschung erfolgt. Prüfen Sie diese Angaben für Ihre Integration und senden Sie keine unnötigen personenbezogenen Daten.
Werden E-Mail-Adressen aus Anfragen gespeichert?
Den aktuellen Umgang mit E-Mail-Adressen aus Anfragen und zugehörigen technischen Daten beschreibt die Datenschutzerklärung. Eine E-Mail-Adresse kann ein personenbezogenes Datum sein: Senden Sie nur, was die Anfrage erfordert, und speichern Sie keine vollständigen Adressen in Ihren eigenen Diagnoseprotokollen.
Wie lange werden hochgeladene Excel- oder CSV-Dateien aufbewahrt?
Die Datenschutzerklärung legt Aufbewahrung, Löschung und Sicherungskopien hochgeladener Dateien fest. Exportieren Sie die benötigten Ergebnisse und löschen Sie die Datei über die Funktionen im Arbeitsbereich, sobald Sie sie nicht mehr benötigen. Bei Fragen zu den Aufbewahrungsanforderungen Ihrer Organisation wenden Sie sich an den Support.
Dürfen Dienstleister Daten aus Anfragen oder hochgeladenen Dateien verarbeiten?
Die Datenschutzerklärung und die Informationen zu Unterauftragsverarbeitern beschreiben die Verarbeitung durch Dienstleister und die geltenden Schutzmaßnahmen. Prüfen Sie diese Unterlagen sowie jede für Ihr Konto geltende Vereinbarung, wenn Sie beurteilen, wo Ihre Daten verarbeitet werden.
Datenschutzerklärung →Unterauftragsverarbeiter →DSGVO-Informationen →
Konto und Support
Schlüssel verbinden und Konto verwalten
Kostenloser Zugang, Authentifizierung, Guthabenabfrage und Support.
Kann ich GenderAPI kostenlos testen?
Ja. Ein registriertes kostenloses Konto enthält 200 Credits pro Tag. Unabhängig davon bietet der V2-Testzugang ohne Schlüssel 10 Credits pro öffentlicher IP-Adresse innerhalb von 24 Stunden, die mit V1 und anderen Nutzern dieser IP-Adresse geteilt werden. In beiden Fällen gelten die regulären Tarife; die Anzahl der Credits entspricht nicht immer der Anzahl der HTTP-Anfragen.
Wie authentifiziere ich mich und schütze meinen API-Schlüssel?
Verwenden Sie Authorization: Bearer YOUR_API_KEY in vertrauenswürdigem serverseitigem Code; POST-Anfragen benötigen zusätzlich Content-Type: application/json. Halten Sie den echten Schlüssel aus Browser-Code, öffentlichen Repositorys und Protokollen heraus. Fehlende, ungültig formatierte oder unbekannte Schlüssel können den IP-Testzugang auslösen; prüfen Sie daher, ob meta.access.mode den Wert api_key hat. Bekannte Schlüssel, die deaktiviert, abgelaufen oder eingeschränkt sind, wechseln nicht in den Testzugang.
Wie prüfe ich meine verbleibenden Credits?
Rufen Sie GET /api/v2/usage mit Ihrem Bearer-Schlüssel auf. Diese Guthabenabfrage ist kostenlos und liefert data.remaining_credits. Ohne Schlüssel wird das gemeinsame Guthaben des IP-Testzugangs gelesen. V1 und V2 verwenden dasselbe Kontoguthaben; der Wert remaining_credits in einer Vorhersage zeigt das Guthaben zum Zeitpunkt des Abschlusses.
Wo kann ich ein Abonnement verwalten oder kündigen?
Melden Sie sich in der GenderAPI-Anwendung an, um das Abonnement zu verwalten, das mit Ihrem API-Schlüssel verknüpft ist. In den aktuellen Kontoeinstellungen sehen Sie Ihr Paket und die Kündigungsoptionen.
Wo kann ich meine Rechnungsdaten ändern?
Abrechnungs- und Zahlungseinstellungen verwalten Sie nach der Anmeldung in der GenderAPI-Anwendung für den jeweiligen API-Schlüssel oder das betreffende Abonnement.
Wie melde ich ein falsches Ergebnis oder erhalte Hilfe bei einer Integration?
Senden Sie dem Support die API-Version, den Endpunkt, die request_id und ein kurzes reproduzierbares Beispiel. Geben Sie den Fehlercode an, sofern vorhanden, entfernen Sie aber Ihren API-Schlüssel und sensible personenbezogene Daten.
Technische Wissensdatenbank
Anleitungen zur Implementierung und verantwortungsvollen Nutzung
Antworten zu Ergebnissen, Datenschutz und dem Betrieb von V2, mit Links zu den Anleitungen und einer Markdown-Version jeder Antwort.
Ergebnisse, Konfidenz und verantwortungsvolle Nutzung
Eine nicht aufgelöste V2-Vorhersage gibt für gender den nativen JSON-Wert null zurück, nicht die Zeichenkette "null". Ein Name kann mehrdeutig sein oder die verfügbaren Hinweise reichen nicht aus; prüfen Sie result_status und reason, sofern vorhanden. Behalten Sie das unbekannte Ergebnis bei, statt es in eine Kategorie zu zwingen. Eine erfolgreiche Vorhersage ohne Ergebnis wird zum Tarif des gewählten Modus abgerechnet. Anfrage- oder Anbieterfehler sind separate Fehlerfälle; Angaben zu ihrer Abrechnung finden Sie in meta.usage.
Vollständige Antwort lesen →Wie wird die Genauigkeit von GenderAPI bewertet?Eine aussagekräftige Bewertung der Genauigkeit nennt die untersuchte Population, das Datum, die Stichprobenmethode, den Anteil unbekannter Ergebnisse sowie Ergebnisse nach Region und Schriftsystem. Die aktuelle Methodikseite beschreibt ein Bewertungsprotokoll, keinen gemessenen Genauigkeitswert in Prozent. Die V2-Felder confidence und confidence_kind erklären, auf welchen Hinweisen ein Ergebnis beruht; sie ersetzen keine Bewertung mit repräsentativen Daten.
Vollständige Antwort lesen →Datenquellen, Datenschutz und Compliance
Die Seite zur Datenherkunft beschreibt den Rahmen für die Dokumentation von Quellkategorien, Auswahlkriterien, Lizenzen sowie geografischen und schriftbezogenen Einschränkungen. Einen geprüften Quellenkatalog veröffentlicht sie derzeit nicht. Lesen Sie diese Seite und wenden Sie sich bei quellenbezogenen Anforderungen Ihrer Integration an den Support; gehen Sie nicht von Quellen, Datensatzgrößen oder Abdeckungswerten aus, die nicht dokumentiert sind.
Vollständige Antwort lesen →Wie oft werden die Namensdaten aktualisiert?Die aktuelle Seite zur Datenherkunft nennt keinen einheitlichen Aktualisierungsplan für alle Namenseinträge oder Verarbeitungsregeln. Wenn die Aktualität für Ihren Anwendungsfall wichtig ist, fragen Sie beim Support nach dem betreffenden Datensatz oder Prozess und prüfen Sie repräsentative Ergebnisse. Das Prüfdatum einer Seite belegt nicht, dass alle zugrunde liegenden Einträge an diesem Tag aktualisiert wurden.
Vollständige Antwort lesen →Wo finde ich Informationen zur DSGVO und zum Auftragsverarbeitungsvertrag?Die Datenschutzerklärung, die DSGVO-Informationen, der Auftragsverarbeitungsvertrag und das Verzeichnis der Unterauftragsverarbeiter beschreiben die veröffentlichten Verarbeitungsbedingungen und Schutzmaßnahmen. Prüfen Sie die aktuellen Dokumente und jede für Ihr Konto geltende Vereinbarung. Bei organisationsspezifischen Fragen, etwa zu Verarbeitungsrollen, Datenübermittlungen oder Anfragen betroffener Personen, wenden Sie sich an GenderAPI; eine allgemeine FAQ ersetzt nicht die geltende Vereinbarung.
Vollständige Antwort lesen →API-Betrieb, Fehler und Abrechnung
Verwenden Sie Authorization: Bearer YOUR_API_KEY in vertrauenswürdigem serverseitigem Code. POST-Anfragen in V2 benötigen zusätzlich Content-Type: application/json. GET /api/v2/gender akzeptiert auch einen Schlüssel als Query-Parameter, doch Header verhindern, dass Zugangsdaten in Browser-URLs sichtbar werden. Fehlende, ungültig formatierte oder unbekannte Schlüssel können den gemeinsamen IP-Testzugang auslösen; prüfen Sie bei einer Kontointegration, ob meta.access.mode den Wert api_key hat. Bekannte Schlüssel, die deaktiviert, abgelaufen oder eingeschränkt sind, wechseln nicht in einen Testzugang.
Vollständige Antwort lesen →Wie gehe ich mit Anfragelimits und Wiederholungen um?V2 wendet Limits für die Anfragerate und für gleichzeitige Anfragen an; beachten Sie HTTP 429 und Retry-After. Jede wiederholte Vorhersage ist ein neuer Vorgang und wird regulär abgerechnet. Wiederholen Sie Anfragen nach einer Zeitüberschreitung, einer verlorenen Antwort oder einer unbestätigten Abrechnung nicht automatisch. Prüfen Sie zuerst code, action und meta.usage.billing_status; wenden Sie sich bei billing_reconciliation_required mit der request_id an den Support. Verwenden Sie ein begrenztes Backoff nur, wenn die Abrechnung bestätigt ist und die dokumentierte action einen neuen Versuch zulässt.
Vollständige Antwort lesen →Wie interpretiere ich V2-Fehler?Fehler der V2-API verwenden HTTP-Fehlerstatuscodes und Problem Details nach RFC 9457 mit stabilen Feldern code und action. Werten Sie diese Felder aus, statt den Wortlaut von detail abzugleichen, und bewahren Sie die request_id für den Support auf. Ein erfolgreiches unbekanntes Ergebnis ist kein Fehler. Batch-Antworten können auch bei HTTP 200 Fehler einzelner Einträge enthalten. Ein Proxy kann einen Fehler in einem anderen Format als JSON zurückgeben, und eine verlorene oder unlesbare Antwort belegt nicht, dass keine Credits abgebucht wurden.
Vollständige Antwort lesen →Wie prüfe ich meine verbleibenden Credits?Rufen Sie GET /api/v2/usage mit Ihrem API-Schlüssel im Bearer-Header aus vertrauenswürdigem serverseitigem Code auf. Diese Anfrage ist kostenlos und liefert data.remaining_credits; ohne Schlüssel wird der gemeinsame IP-Testzugang gelesen. V1 und V2 verwenden dasselbe Kontoguthaben. Das Feld meta.usage einer Vorhersage nennt die Kosten dieses Vorgangs und das Guthaben zum Zeitpunkt des Abschlusses, das sich bei gleichzeitigen Anfragen ändern kann. Halten Sie Zugangsdaten aus Protokollen heraus und werten Sie eine Guthabenabfrage nicht als Beleg dafür, dass eine bestimmte Anfrage mit verlorener Antwort nicht abgerechnet wurde.
Vollständige Antwort lesen →Wie wechsle ich ohne Unterbrechung von V1 zu V2?Erstellen Sie neue Integrationen mit V2 und belassen Sie bestehende V1-Clients auf ihren dokumentierten Endpunkten, bis Sie sie umstellen möchten. Beide Versionen verwenden dieselben API-Schlüssel und Credits, unterscheiden sich aber bei Anfragefeldern, Antwortstrukturen und Fehlerformaten. Folgen Sie der Migrationsanleitung, testen Sie erfolgreiche, unbekannte und fehlerhafte Ergebnisse und passen Sie Ihre Antwortverarbeitung an, bevor Sie den Endpunkt wechseln. Die V1-Dokumentation bleibt für bestehende Integrationen verfügbar.
Vollständige Antwort lesen →Wie diagnostiziere ich Fehler und überwache die Verfügbarkeit des Dienstes?Wenn Anfragen fehlschlagen, unterscheiden Sie anhand des zurückgegebenen Fehlercodes zwischen Dienstausfällen, ungültigen Eingaben, Problemen beim Kontozugriff, aufgebrauchten Credits und Anfragelimits. Überwachen Sie Erfolgsquote und Latenz der Anfragen in Ihrer eigenen Integration. Wenden Sie sich bei einem unerklärlichen Fehler oder einer unklaren Abrechnung mit der request_id an den Support. Stützen Sie Aussagen zur Verfügbarkeit auf Messergebnisse; diese FAQ nennt keinen garantierten Verfügbarkeitswert in Prozent.
Vollständige Antwort lesen →Noch Fragen?
Senden Sie uns ein reproduzierbares Beispiel
Nennen Sie Endpunkt, Anfrageparameter und zurückgegebenen Fehler, aber senden Sie keinen produktiven API-Schlüssel und keine sensiblen personenbezogenen Daten.