GenderAPI.io V2 · Guide d’utilisation

Estimer le genre à partir de noms indiens

Testez des noms utilisés en Inde avec GenderAPI.io V2. Conservez l’orthographe d’origine, choisissez le contexte IN à bon escient et interprétez les correspondances de noms complets, l’IA et les résultats unknown.

Dernière révision :

Essayez l’API V2

Analysez un nom

Jeu de données + IA

Envoyez une valeur et examinez la réponse complète, y compris les résultats inconnus et les crédits consommés.

Cet outil utilise Inde (IN) comme exemple de contexte pays. Ce n’est ni une valeur par défaut pour tous les noms de cette langue, ni une vérification de la nationalité.

Requête standard : 1 crédit, repli IA et résultats unknown compris. Avec l’analyse des pseudonymes activée : 1 crédit si le jeu de données résout la requête, ou 2 au total si l’IA est utilisée, unknown compris.

La valeur envoyée (nom) est transmise à GenderAPI.io et peut être envoyée au service d’IA configuré si un repli est nécessaire. Détails du traitement des données.

Aucune clé API enregistrée. L’essai partagé par IP reste disponible tant qu’il lui reste des crédits.

La réponse ci-dessous est un exemple illustratif. Cliquez sur Analyser pour envoyer une requête.

Réponse V2 illustrative · pas un résultat en direct
Nom—
GenreInconnu
Confiance—
SourceModèle d’IA
Crédits utilisés1

Les effectifs, scores et soldes de l’exemple illustrent le format de la réponse. Les valeurs réelles peuvent différer. Une estimation n’est pas une identité vérifiée.

Utilisez le nom d’origine sans supposer une seule écriture ni un ordre fixe

Cette démonstration utilise un exemple en devanagari et le contexte pays IN. Il s’agit d’un exemple de saisie, pas d’une définition de l’ensemble des noms utilisés en Inde. L’API reçoit des chaînes Unicode : vous pouvez donc envoyer l’orthographe présente dans votre fiche sans la convertir au préalable en alphabet latin.

La recherche utilise des éléments normalisés. Elle n’effectue pas de conversion générale entre écritures et ne garantit pas que l’orthographe latine et l’orthographe d’origine correspondent au même enregistrement. Conservez la saisie d’origine avec le nom renvoyé. Accepter une écriture ne démontre pas une exactitude mesurée de manière indépendante pour chaque langue ou communauté.

Ne supposez pas que le premier ou le dernier élément a toujours le même rôle. V2 retient le candidat disponible ayant l’effectif enregistré le plus élevé ; il ne garantit pas une position particulière du prénom. Les initiales, les éléments courts et l’absence d’enregistrement peuvent laisser le résultat du jeu de données non résolu ; le repli IA peut évaluer la valeur complète envoyée.

Exemple d’entréeCe qu’il représentePoints à vérifier
प्रिया शर्माNom complet en devanagariPlusieurs éléments peuvent devenir candidats. Vérifiez le nom et la correspondance retenus au lieu de supposer que le premier élément l’emporte.
Priya SharmaExemple en alphabet latinC’est une orthographe distincte ; aucune correspondance identique n’est garantie d’une écriture à l’autre.
A. KumarInitiale suivie d’un élément du nomL’initiale d’une lettre ne devient pas un candidat du jeu de données. Une correspondance sur l’autre élément ne confirme pas le prénom attendu.
country: INContexte d’exemple : IndeUtilisez-le si votre fiche contient un contexte pays pertinent, et non simplement parce que le nom figure dans ce guide.

Choisissez le contexte pays IN à bon escient

La démonstration envoie country: IN (Inde). L’API ne choisit pas ce pays à partir de l’écriture du nom. Dans votre intégration, utilisez un contexte pays connu et pertinent, ou omettez country. Ne transformez pas cet exemple en valeur par défaut pour toutes vos fiches.

Pour chaque candidat, la recherche privilégie l’enregistrement propre au pays s’il existe et, à défaut, consulte l’enregistrement global. Elle retient ensuite le candidat disponible ayant l’effectif enregistré le plus élevé. Vérifiez la portée réelle de la correspondance avec data.match.scope et data.match.country. Un enregistrement de pays à effectifs égaux n’est pas remplacé automatiquement par le résultat global ; si fallback est activé, l’IA peut être utilisée à la place.

data.input.country décrit le contexte envoyé dans la requête. data.country et data.country_source décrivent une association de pays renvoyée et son origine. Ce sont des champs différents ; ils ne prouvent ni la citoyenneté, ni l’origine ethnique, ni la résidence.

Envoyez une requête de nom V2 depuis votre application

Définissez GENDERAPI_API_KEY avec votre clé existante et exécutez l’exemple sur votre serveur. La requête active explicitement le repli IA standard. Elle illustre le format d’une requête, pas une exactitude mesurée ni une couverture démontrée. Pour utiliser uniquement le jeu de données, choisissez options.ai_mode: off.

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.

Guide des erreurs et des nouvelles tentatives →
cURL
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": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
}'

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

JavaScript / Node.js
// 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": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
};

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+ ; fetch intégré. Enregistrez sous example.mjs et exécutez node example.mjs. Documentation de l'environnement d'exécution

Python
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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}")

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

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"प्रिया शर्मा","country":"IN","options":{"ai_mode":"fallback"}}', 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+ avec l'extension cURL. Enregistrez sous example.php et exécutez php example.php. Documentation de l'environnement d'exécution

Java
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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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+ ; client HTTP standard. Enregistrez sous GenderApiExample.java et exécutez java GenderApiExample.java. Documentation de l'environnement d'exécution

C# / .NET
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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}", 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

Go
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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    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+ ; bibliothèque standard. Enregistrez sous main.go et exécutez go run main.go. Documentation de l'environnement d'exécution

Conservez le résultat avec ses éléments de preuve

Une association déduite n’équivaut pas au genre déclaré par la personne. Conservez séparément la valeur d’origine, les éléments de preuve renvoyés et les informations fournies par la personne elle-même. unknown est un résultat valide : ne le transformez pas en une catégorie devinée dans votre application.

ChampComment l’utiliser
data.gender / data.result_statusUtilisez male ou female uniquement lorsque le résultat est identified. Conservez la valeur JSON null lorsqu’il est unknown.
data.name / data.matchVérifiez le nom renvoyé et le candidat retenu. Une correspondance partielle ne prouve pas que la valeur appartient à une personne portant ce prénom.
data.confidence / data.confidence_kindLa confiance est exprimée entre 0 et 1, ou vaut null. observed_frequency provient des effectifs enregistrés ; model_reported est un score fourni par l’IA. Évaluez vos seuils séparément pour chaque type.
data.source / data.sample_countDistinguez dataset, ai et none. Les résultats de l’IA n’ont pas d’effectif enregistré. La taille de l’échantillon n’est pas une mesure d’exactitude.
meta.access.modeVérifiez la valeur api_key pour une intégration liée à un compte. Si la clé est absente ou non reconnue, l’essai partagé par IP peut être utilisé à la place.
meta.usageLisez charged_credits et billing_status. Un résultat unknown obtenu avec succès est facturé. L’absence de réponse ne prouve pas que la requête était gratuite.

Choisissez quand utiliser l’IA

forceToGenderize est facultatif pour les noms, les adresses e-mail et les noms d’utilisateur. Lorsqu’il est activé, omettez ai_mode ou utilisez fallback : la combinaison avec off ou always renvoie une erreur 422. Un solde de départ positif suffit pour lancer une requête, même si le débit final fait passer le solde en dessous de zéro.

L’analyse des pseudonymes peut renvoyer un genre avec name: null. Elle peut aussi renvoyer unknown. Ni le repli IA standard ni l’analyse des pseudonymes ne garantissent une réponse correcte ou non nulle.

Option de la requêteComportementCrédits par requête aboutie
options.ai_mode: offInterroge uniquement le jeu de données.1 crédit, unknown compris
options.ai_mode: fallbackInterroge d’abord le jeu de données, puis l’IA standard si aucun genre n’est trouvé. C’est le mode par défaut des requêtes individuelles.1 crédit au total, repli IA compris
options.ai_mode: alwaysInterroge directement l’IA.2 crédits
forceToGenderize: trueInterroge d’abord le jeu de données ; si aucun genre n’est trouvé, autorise l’IA à interpréter le sens d’un surnom ou d’un pseudonyme personnel, même sans prénom réel.1 crédit si le jeu de données résout la requête ; 2 au total si l’IA est utilisée

Traitez une liste de noms sans perdre son contexte

Envoyez jusqu’à 50 éléments avec une clé API, ou 10 avec l’essai par IP, via POST /api/v2/gender/batch. Attribuez des id uniques et conservez la valeur d’origine de chaque ligne. Chaque élément peut avoir ses propres options de pays et d’IA ; omettez le pays lorsqu’il est inconnu.

Contrairement aux requêtes individuelles, dont le mode par défaut est fallback, les éléments d’un lot utilisent par défaut uniquement le jeu de données. Définissez options.ai_mode: fallback sur chaque élément qui nécessite l’IA. Examinez chaque résultat, même après un HTTP 200, conservez les résultats unknown et vérifiez les erreurs et la facturation avant tout nouvel envoi. Chaque élément standard abouti consomme 1 crédit ; une requête HTTP de lot ne correspond pas à un seul crédit d’estimation.

Comprenez ce que vous envoyez

L’outil n’envoie la valeur saisie à GenderAPI.io que lorsque vous cliquez sur Analyser. Si l’IA intervient, le service d’inférence configuré reçoit type, value et le contexte pays envoyé. Pour une estimation fondée uniquement sur le jeu de données, utilisez options.ai_mode: off sans forceToGenderize dans votre intégration.

La Politique de confidentialité, l’accord de traitement des données et la liste des sous-traitants décrivent les conditions publiées. Le résultat est une association déduite : donnez la priorité aux informations fournies par la personne. Ne l’utilisez pas comme fondement de décisions ayant des conséquences importantes pour quelqu’un.

Questions fréquentes

La démonstration pour les noms indiens accepte-t-elle uniquement des noms en hindi ?

La démonstration utilise un exemple en devanagari, mais l’API accepte des noms sous forme de chaînes Unicode. Cette capacité de saisie ne signifie pas une couverture complète du jeu de données ni une exactitude mesurée pour chaque langue utilisée en Inde.

Une orthographe latine renvoie-t-elle le même résultat que l’écriture d’origine ?

Ce n’est pas garanti. La recherche actuelle n’établit pas d’équivalence générale entre translittérations. Conservez chaque orthographe envoyée avec la source, la correspondance et la confiance renvoyées.

Une évaluation indépendante de l’exactitude est-elle publiée pour ce groupe de noms ?

Cette page ne publie pas une telle évaluation. Accepter une saisie, afficher des effectifs enregistrés ou renvoyer un score de confiance ne constitue pas une mesure indépendante de l’exactitude. Consultez la méthodologie pour connaître les éléments disponibles et les mesures qui restent à publier.

Un résultat sans estimation consomme-t-il des crédits ?

Un résultat unknown abouti est facturé. Le mode standard jeu de données ou fallback coûte 1 crédit au total. Avec forceToGenderize, la requête coûte 1 crédit si le jeu de données la résout, ou 2 au total si l’IA est utilisée, unknown compris. Les erreurs suivent des règles de facturation distinctes ; consultez meta.usage.

Continuez vos tests

Utilisez votre clé GenderAPI

Collez la clé API de votre compte GenderAPI pour poursuivre les tests lorsque les crédits partagés de l’essai par IP sur 24 heures sont épuisés. L’enregistrement de la clé n’envoie aucune requête. Relancez ensuite l’analyse.

Elle est conservée uniquement dans cet onglet et supprimée à sa fermeture.