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ée | Ce qu’il représente | Points à vérifier |
|---|---|---|
प्रिया शर्मा | Nom complet en devanagari | Plusieurs é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 Sharma | Exemple en alphabet latin | C’est une orthographe distincte ; aucune correspondance identique n’est garantie d’une écriture à l’autre. |
A. Kumar | Initiale suivie d’un élément du nom | L’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: IN | Contexte d’exemple : Inde | Utilisez-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 7.76+ dans un shell POSIX. À exécuter dans votre terminal. Documentation de l'environnement d'exécution
Node.js 22+ ; fetch intégré. Enregistrez sous example.mjs et exécutez node example.mjs. Documentation de l'environnement d'exécution
Python 3.10+ ; bibliothèque standard. Enregistrez sous example.py et exécutez python3 example.py. Documentation de l'environnement d'exécution
PHP 8+ avec l'extension cURL. Enregistrez sous example.php et exécutez php example.php. Documentation de l'environnement d'exécution
Java 17+ ; client HTTP standard. Enregistrez sous GenderApiExample.java et exécutez java GenderApiExample.java. Documentation de l'environnement d'exécution
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 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.
| Champ | Comment l’utiliser |
|---|---|
data.gender / data.result_status | Utilisez male ou female uniquement lorsque le résultat est identified. Conservez la valeur JSON null lorsqu’il est unknown. |
data.name / data.match | Vé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_kind | La 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_count | Distinguez 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.mode | Vé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.usage | Lisez 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ête | Comportement | Crédits par requête aboutie |
|---|---|---|
| options.ai_mode: off | Interroge uniquement le jeu de données. | 1 crédit, unknown compris |
| options.ai_mode: fallback | Interroge 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: always | Interroge directement l’IA. | 2 crédits |
| forceToGenderize: true | Interroge 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.