Genre à partir de noms d’utilisateur et de pseudonymes

Entrées d’exemple

Un pseudonyme n’est pas une vérification d’identité

@alice_smith peut correspondre à un élément nominal. Avec prenses et forceToGenderize, une estimation peut être renvoyée alors que le prénom reste à null. user47291 peut rester inconnu. Ce sont des exemples d’entrée ; aucun résultat de genre ne leur est attribué à l’avance.

Logique d’analyse

Comment fonctionne l’estimation du genre à partir d’un nom d’utilisateur ?

Le système examine les éléments nominaux lisibles et d’autres indices linguistiques dans le nom d’utilisateur ou le nom d’affichage. L’IA standard recherche un prénom réel exploitable ; avec forceToGenderize, elle peut interpréter le pseudonyme sans prénom réel. Le résultat est renvoyé avec ses champs de contexte ; une entrée aléatoire ou insuffisante ne doit pas être forcée à produire un résultat.

01Nom d’utilisateurPseudonyme ou nom d’affichage

02Analyse des signauxPrénom et contexte

03EstimationGenre et confiance

Canaux d’utilisation

Choisissez la méthode adaptée à vos données

Requête individuelleAnalysez un nom d’utilisateur via la REST API.Voir le guide de l’API →Requête par lotEnvoyez plusieurs enregistrements dans une requête structurée.Voir le guide des lots →Flux Excel/CSVTraitez votre fichier sans développer d’intégration.Ouvrir l’outil →

Traitement en volume sans code

Analysez les noms d’utilisateur d’un fichier Excel ou CSV en quatre étapes

01
Ouvrez l’outil Excel/CSV
Accédez à l’outil d’import de GenderAPI et chargez le fichier à traiter.
02
Sélectionnez la colonne source
Associez la colonne qui contient les noms d’utilisateur, les pseudonymes ou les noms d’affichage.
03
Activez l’analyse des pseudonymes
Activez l’option qui interprète les alias et les noms utilisés sur les réseaux sociaux.
04
Testez un échantillon, puis exportez
Contrôlez d’abord un ensemble représentatif, puis traitez le fichier complet et téléchargez les données enrichies.

Les nouveaux comptes incluent 200 crédits API gratuits par jour : vous pouvez donc valider le flux sur un échantillon avant de traiter le fichier complet.

Cas d’usage

Utilisez-le comme signal auxiliaire en l’absence de prénom réel

L’analyse des noms d’utilisateur peut être utile pour les données de réseaux sociaux, de communautés, de jeux vidéo et de profils créés par les utilisateurs lorsque le champ prénom est vide. Si vous disposez d’une source plus directe et autorisée, comme un vrai prénom ou une adresse e-mail, utilisez l’endpoint approprié.

Limites

Ne traitez pas le résultat comme une identité vérifiée

Tous les pseudonymes ne contiennent pas un prénom réel, les associations culturelles varient et une même expression peut avoir des sens différents selon la langue. Acceptez un résultat vide lorsque le signal est insuffisant, au lieu de transformer des données faibles en conclusion définitive.

Guide de mise en œuvre V2

Stockez séparément les données d’origine et l’estimation

Conservez l’identifiant d’origine de la fiche. L’API n’ouvre aucun profil, ne vérifie pas la titularité d’un compte et ne vérifie l’identité de personne. N’envoyez un contexte pays que si vous disposez d’une information fiable ; ne le déduisez ni du domaine ni de la langue de la page.

Exemple d’entrée	Champ ou option	Comment l’interpréter
@alice_smith	data.name / data.match	Conservez le nom d’utilisateur d’origine ; ne traitez pas le fragment correspondant comme un prénom vérifié.
prenses	forceToGenderize: true	Permet d’interpréter le pseudonyme sans prénom réel. Un genre peut être renvoyé avec data.name à null ; n’inventez pas de prénom pour la personne.
user47291	data.result_status: unknown	Les entrées opaques ou insuffisantes peuvent rester inconnues. Ce n’est pas une raison de relancer automatiquement la requête.

Envoyez le nom d’utilisateur avec type: username ; n’envoyez pas l’URL du profil. La recherche dans le jeu de données supprime le @ initial, normalise le texte et génère des candidats à partir des séparateurs et des chiffres. La requête standard peut ajouter un nombre limité de correspondances par préfixe et suffixe ; forceToGenderize n’utilise pas ces fragments supplémentaires. Si plusieurs enregistrements correspondent, celui dont l’effectif enregistré est le plus élevé est retenu. Utilisez type: email pour les adresses e-mail et type: name pour les vrais noms.

Choisissez le mode de traitement et son coût en crédits

Option	Traitement	Coût par élément abouti
options.ai_mode: off	Jeu de données uniquement	1 crédit
options.ai_mode: fallback	D’abord le jeu de données, puis l’IA standard si aucun genre n’est trouvé	1 crédit au total, IA comprise
options.ai_mode: always	Directement l’IA	2 crédits
forceToGenderize: true	D’abord le jeu de données, puis interprétation du pseudonyme sans exiger de prénom réel	1 si le jeu de données suffit ; 2 au total si l’IA est utilisée

Pour une requête individuelle, la valeur par défaut est fallback ; pour les éléments d’un lot, c’est off. forceToGenderize est facultatif pour les noms, les adresses e-mail et les noms d’utilisateur ; dans ce cas, omettez ai_mode ou utilisez fallback, car l’option est incompatible avec off et always. Les résultats unknown aboutis sont également facturés. Un solde de départ positif suffit pour commencer ; à la fin de l’opération, le solde peut passer sous zéro.

Attribuez des options propres à chaque élément du lot

Les entrées d’exemple ne garantissent aucune estimation particulière. Définissez GENDERAPI_API_KEY dans l’environnement du serveur et n’incluez pas la clé dans du code client public. V1 et V2 partagent la même clé de compte et le même solde. Vérifiez la clé avec /api/v2/usage et assurez-vous que meta.access.mode vaut api_key.

Choisissez un langage de programmation. Configurez votre clé API, puis exécutez l'exemple sur votre serveur.

Chaque requête de prédiction est une nouvelle opération facturable, y compris les nouvelles tentatives. Ces exemples ne réessaient pas automatiquement. Vérifiez le statut de facturation avant d'envoyer une autre requête.

Avant l'exécution : accès et gestion des erreurs

Exécutez ces exemples sur votre serveur. Définissez GENDERAPI_API_KEY dans l'environnement du processus avec votre clé API existante. Vérifiez que meta.access.mode vaut api_key : une clé non reconnue peut basculer vers l'essai par IP.

Pour les réponses JSON HTTP 4xx et 5xx, les exemples conservent le corps de l'erreur et renvoient un code de sortie non nul. Vérifiez code, action et meta.usage.billing_status avant de réessayer. Pour une réponse de lot HTTP 200, examinez aussi data ou error dans chaque élément.

Guide des erreurs et des nouvelles tentatives →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "profile-001",
      "type": "username",
      "value": "@alice_smith",
      "options": {
        "ai_mode": "off"
      }
    },
    {
      "id": "profile-002",
      "type": "username",
      "value": "alexriver",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "profile-003",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ dans un shell POSIX. À exécuter dans votre terminal. Documentation de l'environnement d'exécution

// 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 = {
  "items": [
    {
      "id": "profile-001",
      "type": "username",
      "value": "@alice_smith",
      "options": {
        "ai_mode": "off"
      }
    },
    {
      "id": "profile-002",
      "type": "username",
      "value": "alexriver",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "profile-003",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  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+ ; fetch intégré. Enregistrez sous example.mjs et exécutez node example.mjs. Documentation de l'environnement d'exécution

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("{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}")

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/batch",
    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+ ; bibliothèque standard. Enregistrez sous example.py et exécutez python3 example.py. Documentation de l'environnement d'exécution

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"profile-001","type":"username","value":"@alice_smith","options":{"ai_mode":"off"}},{"id":"profile-002","type":"username","value":"alexriver","options":{"ai_mode":"fallback"}},{"id":"profile-003","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
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+ avec l'extension cURL. Enregistrez sous example.php et exécutez php example.php. Documentation de l'environnement d'exécution

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 = "{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}";
        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/batch"))
            .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+ ; client HTTP standard. Enregistrez sous GenderApiExample.java et exécutez java GenderApiExample.java. Documentation de l'environnement d'exécution

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/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}", 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.
}

Application console .NET 8+. Utilisez-le comme Program.cs dans un projet console, puis exécutez dotnet run. Documentation de l'environnement d'exécution

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 := "{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", 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+ ; bibliothèque standard. Enregistrez sous main.go et exécutez go run main.go. Documentation de l'environnement d'exécution

Gérez les résultats de la liste et les nouvelles tentatives

POST /api/v2/gender/batch accepte jusqu’à 50 éléments avec une clé API et 10 avec l’essai partagé par IP. Attribuez à chaque élément ses propres type, value et options. Si vous souhaitez le repli IA standard, indiquez explicitement fallback pour chaque élément. L’id doit être unique dans chaque lot ; index commence à zéro dans le lot envoyé. Conservez à part vos propres identifiants de tâche et de ligne d’origine.

Un HTTP 200 ne signifie pas que tous les éléments ont abouti. Traitez séparément les résultats identified, unknown et error ; meta.summary.succeeded compte à la fois identified et unknown. Évaluez ensemble data.gender, source, confidence_kind, confidence, match et reason. Ne considérez pas le score de l’IA et la fréquence du jeu de données comme équivalents.

Si meta.usage.billing_status est confirmé, renvoyez uniquement les erreurs opérationnelles qui autorisent une nouvelle tentative. Si l’état est unconfirmed ou si la réponse est perdue, arrêtez-vous et rapprochez la facturation. Renvoyer la même fiche, y compris un unknown abouti, crée une nouvelle opération facturable ; ne renvoyez jamais toute la liste à l’aveugle.

Contrat des requêtes par lot · Champs de la réponse · Options d’IA · Évaluation de la précision et de la confiance · Politique de confidentialité

Les compléments Excel et Google Sheets et les autres intégrations prêtes à l’emploi peuvent utiliser leur propre connexion et leur propre format de sortie. Ne supposez pas que leur résultat suit ce schéma JSON V2 ; consultez le guide à jour de chaque intégration.

Questions fréquentes

Estimer le genre à partir d’un nom d’utilisateur ou d’un pseudonyme

Peut-on estimer le genre à partir d’un nom d’utilisateur ?

En V2, si vous activez forceToGenderize, le jeu de données est interrogé en premier ; si aucun genre n’est trouvé, l’IA peut interpréter le pseudonyme sans exiger de prénom réel. Le résultat peut rester unknown et ne constitue pas une identité vérifiée. L’IA standard, elle, a besoin d’un prénom réel exploitable.

Quels noms d’utilisateur donnent les résultats les plus utiles ?

Les valeurs qui contiennent un prénom réel, un surnom lisible ou un élément nominal clair peuvent fournir un signal plus utile. Les chaînes aléatoires et les noms de marque peuvent ne produire aucun résultat.

Puis-je analyser un seul nom d’utilisateur via l’API ?

Oui. L’endpoint individuel analyse un enregistrement. Pour plusieurs enregistrements, un endpoint dédié aux requêtes par lot est disponible.

Puis-je importer un fichier Excel ou CSV ?

Oui. Dans l’outil de fichiers, vous pouvez choisir la colonne du nom d’utilisateur ou du nom d’affichage et activer l’analyse des pseudonymes.

Pourquoi conserver ensemble les champs de confiance et de source de V2 ?

En V2, data.confidence va de 0 à 1. Évaluez-le avec source et confidence_kind, car le score de l’IA et la fréquence du jeu de données ne sont pas la même mesure. Conservez les résultats unknown et le champ reason.

Le résultat peut-il servir à la segmentation ?

Il peut servir de signal auxiliaire pour des analyses agrégées et l’enrichissement de données, mais ne doit pas être utilisé seul pour des décisions à fort impact concernant une personne ni pour présumer de son identité.

Puis-je tester gratuitement ?

Les nouveaux comptes GenderAPI incluent 200 crédits API gratuits par jour pour tester des échantillons représentatifs via l’API ou des fichiers.

Estimer le genre à partir de noms d’utilisateur et de pseudonymes

Analysez les pseudonymes de votre jeu de données