GenderAPI.io V2 : recherche par prénom et nom complet

Avant d'envoyer la requête

Envoyez les requêtes de prédiction GenderAPI.io V2 à POST https://api.genderapi.io/api/v2/gender, avec type et value dans le corps JSON. Utilisez votre clé GenderAPI.io existante dans Authorization: Bearer YOUR_API_KEY et Content-Type: application/json. Lisez le résultat dans data et les informations d'accès et de facturation dans meta. Chaque requête est traitée indépendamment.

Choisissez votre langage dans l'exemple de code. Définissez GENDERAPI_API_KEY dans l'environnement du processus avant de l'exécuter. Une clé absente ou non reconnue peut utiliser l'essai partagé par IP ; vérifiez donc que meta.access.mode vaut api_key lorsque vous intégrez un compte.

Genre à partir d'un nom

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`type`	`string`	Oui	`—`	Catégorie d'entrée : name, email ou username.
`value`	`string`	Oui	`—`	Obligatoire. 1 à 254 caractères ; non vide et sans caractères de contrôle. Une valeur de type email doit respecter la syntaxe d'une adresse e-mail valide.
`country`	`string`	Non	`—`	Code ISO 3166-1 alpha-2 facultatif, en majuscules, par exemple TR ou US. La recherche propre à un pays peut se rabattre sur le jeu de données global.
`forceToGenderize`	`boolean`	Non	`false`	Consulte d'abord le jeu de données, puis l'IA adaptée aux surnoms si aucun résultat n'est trouvé. Compatible avec name, email et username.
`options`	`object`	Non	`—`	Objet contenant les options d'IA propres à chaque entrée.
`options.ai_mode`	`string`	Non	`fallback`	Valeurs autorisées : off, fallback, always. Avec forceToGenderize: true, omettez ce champ ou utilisez fallback.
`id`	`string`	Non	`—`	Identifiant facultatif de 1 à 64 caractères dans le corps JSON POST. Renvoyé avec chaque résultat de lot et unique au sein d'un lot. Accepté mais non renvoyé pour les prédictions individuelles. Non pris en charge dans les requêtes GET.

Pour un prénom ou un nom complet, envoyez type: name et l'entrée complète dans value à POST https://api.genderapi.io/api/v2/gender. GenderAPI.io V2 utilise les mêmes champs de requête pour les deux formats. Une réponse réussie peut tout de même contenir data.gender: null. Les requêtes individuelles consultent d'abord le jeu de données et, par défaut, font appel à l'IA lorsqu'il ne permet pas de déterminer un genre.

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 --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": "Antoine",
  "country": "FR"
}'

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 = {
  "type": "name",
  "value": "Antoine",
  "country": "FR"
};

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

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\":\"Antoine\",\"country\":\"FR\"}")

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
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Antoine","country":"FR"}', 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

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\":\"Antoine\",\"country\":\"FR\"}";
        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

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\":\"Antoine\",\"country\":\"FR\"}", 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 := "{\"type\":\"name\",\"value\":\"Antoine\",\"country\":\"FR\"}"
    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

Exemple de réponse

Il s'agit d'une réponse réelle obtenue le 1er octobre 2026 avec une clé API ; seul le solde du compte a été remplacé. Elle ne constitue pas une mesure de la précision, et une requête réelle peut renvoyer un résultat différent. Les requêtes avec clé API indiquent meta.access.mode: api_key et renvoient null dans les champs de quota propres à l'essai ; les requêtes en essai par IP indiquent ip_trial. Lisez data pour l'inférence et meta.usage pour le résultat de facturation de l'opération.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Antoine",
      "country": "FR"
    },
    "name": "antoine",
    "gender": "male",
    "country": "FR",
    "confidence": 0.9968091895341417,
    "confidence_kind": "observed_frequency",
    "sample_count": 1567,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "antoine",
      "method": "normalized",
      "scope": "country",
      "country": "FR"
    }
  },
  "meta": {
    "request_id": "e1b6e741-9544-4b89-a4a0-c590bc682513",
    "duration_ms": 28,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Champs de réponse et confiance

Champs de la réponse de prédiction

Champ	Type	Peut valoir null	Exemple	Description
`data.input`	`object`	Non	`{"type":"name","value":"Antoine","country":"FR"}`	Type d'entrée, valeur et pays. forceToGenderize est inclus lorsqu'il vaut true.
`data.name`	`string`	Oui	`"antoine"`	Prénom correspondant ou extrait ; null si aucun n'est disponible.
`data.gender`	`string`	Oui	`"male"`	male, female ou JSON null. Il s'agit d'une inférence, et non d'une identité personnelle vérifiée.
`data.result_status`	`string`	Non	`"identified"`	identified si un genre est renvoyé ; unknown sinon.
`data.reason`	`string`	Oui	`null`	null pour les résultats identified. Raisons d'un résultat inconnu : not_found, no_name_candidate, ambiguous ou insufficient_evidence.
`data.confidence`	`number`	Oui	`0.95`	Score de 0 à 1 ou null. Un genre null a une confiance null.
`data.confidence_kind`	`string`	Oui	`"observed_frequency"`	observed_frequency : effectif du genre dominant divisé par le total de la ligne du jeu de données sélectionnée. model_reported : score de l'IA, qui n'est pas une probabilité calibrée. null lorsqu'il n'est pas disponible.
`data.sample_count`	`integer`	Oui	`1200`	Taille de l'échantillon du jeu de données ou null. L'IA n'invente pas d'effectif d'échantillon.
`data.source`	`string`	Non	`"dataset"`	dataset, ai ou none.
`data.country`	`string`	Oui	`"FR"`	Association à un pays issue de dataset ou ai_association, ou null. N'établit ni la nationalité, ni la résidence, ni l'origine ethnique.
`data.country_source`	`string`	Oui	`"dataset"`	Origine de l'association au pays : dataset, ai_association ou null.
`data.match`	`object`	Non	`{"name":"antoine","method":"normalized","scope":"country","country":"FR"}`	Nom correspondant dans le jeu de données, méthode (normalized, token, substring ou model_inference), portée country ou global et pays de la correspondance. Les informations indisponibles valent null.

Accès, facturation et métadonnées de la requête

Champ	Type	Peut valoir null	Exemple	Description
`meta.request_id`	`string`	Non	`"550e8400-e29b-41d4-a716-446655440000"`	Identifiant unique de cette tentative HTTP ; également envoyé dans X-Request-ID.
`meta.duration_ms`	`integer`	Non	`42`	Durée de traitement de la requête en millisecondes.
`meta.access.mode`	`string`	Non	`"api_key"`	api_key, ip_trial ou unauthenticated. Vérifiez api_key lorsque vous utilisez un compte payant.
`meta.access.reason`	`string`	Oui	`null`	Motif du passage à l'essai : api_key_missing, api_key_invalid ou api_key_not_found ; null sinon.
`meta.usage.charged_credits`	`integer`	Oui	`1`	Crédits nets débités. Zéro avant débit ou après remboursement intégral confirmé ; null si la facturation n'est pas confirmée.
`meta.usage.remaining_credits`	`integer`	Oui	`99`	Solde à la fin de l'opération. Peut être négatif ; null si indisponible ou si la facturation n'est pas confirmée.
`meta.usage.billing_status`	`string`	Non	`"confirmed"`	not_charged, confirmed ou unconfirmed. Vérifiez ce champ avant de relancer une prédiction échouée.
`meta.usage.resets_at`	`string`	Oui	`"2026-09-27T12:00:00.000Z"`	Réinitialisation de l'essai par IP en UTC (ISO 8601) ; null pour les comptes avec clé API ou si inconnue.
`meta.usage.limit`	`integer`	Oui	`10`	Crédits de l'essai par IP ; null pour les comptes avec clé API.
`meta.usage.period_seconds`	`integer`	Oui	`86400`	Durée de l'essai par IP en secondes ; null pour les comptes avec clé API.

Contexte de pays et noms inconnus

Indiquez un pays uniquement si vous disposez d'un contexte pertinent. L'API peut sélectionner une ligne du jeu de données propre à ce pays ou se rabattre sur une ligne globale. data.match.scope indique laquelle a été retenue ; le pays renvoyé n'indique pas où vit la personne.

Par défaut, une requête individuelle utilise le repli sur l'IA pour 1 crédit au total. Pour n'utiliser que le jeu de données, envoyez options: {"ai_mode": "off"}. Les entrées non résolues peuvent renvoyer gender: null et restent facturables lorsque l'opération réussit. Un nom complet peut correspondre à l'un de ses composants ; data.match indique le candidat retenu et la méthode de correspondance.

Pour une valeur de nom qui ressemble à un surnom, forceToGenderize: true autorise l'inférence sans véritable prénom : un résultat résolu par le jeu de données coûte 1 crédit ; sinon, l'IA adaptée aux surnoms coûte 2 crédits au total. Un solde de départ positif suffit et le solde final peut devenir négatif.

Rechercher un nom complet sans supposer que le premier mot est retenu

Envoyez le nom avec ses caractères Unicode d'origine. La recherche dans le jeu de données applique une normalisation NFKC, une conversion en minuscules et une extraction des composants ; vous n'avez pas besoin de convertir le nom en ASCII. Parmi les candidats disponibles, l'API retient l'enregistrement dont le total stocké est le plus élevé. Ce candidat peut être un composant ultérieur du nom : ne supposez pas que le premier mot ou le prénom a été retenu.

Cette requête limitée au jeu de données permet d'examiner plus facilement la correspondance retenue. Lisez data.input.value pour le nom complet envoyé, data.match.name pour le candidat recherché et data.match.method pour la méthode de correspondance. L'exemple ne garantit ni un genre ni un composant particulier. Les candidats du jeu de données doivent comporter plus de deux caractères ; les entrées courtes peuvent rester non résolues. Activez le repli ordinaire sur l'IA si cette inférence supplémentaire convient à votre application.