Grundlegende Nutzung

GenderAPI ermöglicht es dir, das Geschlecht einer Person anhand verschiedener Eingabedaten zu bestimmen. Du kannst direkt Vornamen analysieren oder Namen aus E-Mail-Adressen und Benutzernamen extrahieren. So kannst du starten:

1. Geschlecht anhand des Namens

Sende einen Vornamen an folgende Endpoint-URL:

https://api.genderapi.io/api

Beispiel:

curl "https://api.genderapi.io/api?name=Alice&key=YOUR_API_KEY"

Du kannst auch optionale Parameter hinzufügen:

  • country: Übergebe einen zweistelligen Ländercode ( ISO 3166-1 alpha-2 ) um die Vorhersagegenauigkeit zu verbessern. Zum Beispiel: country=TR für die Türkei.
  • askToAI: Falls auf true gesetzt, wird die API ein KI-Modell befragen, wenn der Name nicht in der Datenbank gefunden wird.
  • forceToGenderize: Falls auf true gesetzt, versucht die API, ein Geschlecht zu erraten, selbst bei Eingaben, die nicht wie reale Personennamen aussehen, z. B. Spitznamen oder Fantasienamen wie sparkling unicorn oder mystic warrior. Dies kann nützlich sein, um Benutzernamen zu analysieren, die Ergebnisse können jedoch weniger genau sein. Hinweis: Dieser Parameter ist im E-Mail-Endpoint nicht verfügbar.

Beispiel mit Parametern:

curl "https://api.genderapi.io/api?name=sparkling%20unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

2. Geschlecht anhand der E-Mail-Adresse

Verwende diesen Endpoint, wenn du nur eine E-Mail-Adresse hast:

https://api.genderapi.io/api/email

Beispiel:

curl "https://api.genderapi.io/api/email?email=alice.smith@example.com&country=TR&askToAI=true&key=YOUR_API_KEY"

Hinweis: Der Parameter forceToGenderize steht für den E-Mail-Endpoint nicht zur Verfügung, da dieser Endpoint zunächst intern den Namen extrahiert.


3. Geschlecht anhand des Benutzernamens

Für Benutzernamen oder Spitznamen verwende:

https://api.genderapi.io/api/username

Beispiel:

curl "https://api.genderapi.io/api/username?username=sparkling_unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

Der Parameter forceToGenderize ist hier besonders nützlich, da Benutzernamen häufig Wörter enthalten, die keine echten Namen sind oder Fantasiebegriffe darstellen. Er zwingt die API, eine Geschlechtsvorhersage zu versuchen, auch wenn die Eingabe kein typischer menschlicher Name ist.

Alle Methoden unterstützen Einzel- oder Massenanfragen. Weitere Details findest du in den jeweiligen Abschnitten im linken Navigationsmenü.


✅ API-Antwort

Beispiel für eine JSON-Antwort für alle Endpoints:

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "michael.smith@example.com",
  "name": "Michael",
  "gender": "male",
  "country": "US",
  "total_names": 325,
  "probability": 98,
  "duration": "4ms"
}

Antwortfelder

Feld Typ Beschreibung
status Boolean true, wenn die Anfrage erfolgreich war. Bei false überprüfe die Fehlermeldungen.
used_credits Integer Anzahl der für diese Anfrage verwendeten Credits.
remaining_credits Integer Verbleibende Credits auf deinem Konto nach dieser Anfrage.
expires Integer (timestamp) Ablaufdatum des Pakets als UNIX-Timestamp (Sekunden).
q String Deine Eingabeanfrage (Name, E-Mail oder Benutzername).
name String Der gefundene oder extrahierte Vorname.
gender Enum[String] Vorhergesagtes Geschlecht. Mögliche Werte: male, female oder null.
country Enum[String] Der wahrscheinlichste Ländercode (z. B. US oder DE).
total_names Integer Anzahl der Samples, die der Vorhersage zugrunde liegen.
probability Integer Wahrscheinlichkeit der Geschlechtsvorhersage in Prozent (z. B. 50-100).
duration String Bearbeitungszeit für die Anfrage (z. B. 4ms).
Warnung: Falls deine Eingabewerte Leerzeichen oder Sonderzeichen enthalten (z. B. sparkling unicorn), solltest du diese immer URL-encoden, bevor du GET-Anfragen ausführst. Andernfalls könnte die Anfrage fehlschlagen oder andere Parameter könnten in deiner Programmiersprache oder HTTP-Bibliothek falsch interpretiert werden.
curl "https://api.genderapi.io/api?name=sparkling unicorn&key=YOUR_API_KEY"
Du solltest stattdessen verwenden:
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&key=YOUR_API_KEY"
oder entsprechende URL-Encodierungsfunktionen in deiner Programmiersprache anwenden.