Comprendre la réponse JSON
Les prédictions individuelles de GenderAPI.io V2 renvoient un objet data pour le résultat et un objet meta pour les informations de requête, d'accès et de facturation. Lisez data.gender et data.confidence avec data.confidence_kind et data.source. L'exemple de jeu de données ci-dessous est une réponse réelle obtenue le 1er octobre 2026 avec une clé API ; seul le solde du compte a été remplacé. Il ne représente pas une précision mesurée du produit, et une requête réelle peut renvoyer un résultat différent. Les requêtes avec clé API indiquent 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 avec la limite d'essai et l'heure de réinitialisation.
{
"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 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. |
Champs d'entrée renvoyés
| Champ | Type | Peut valoir null | Exemple | Description |
|---|---|---|---|---|
data.input.type | string | Non | "name" | Catégorie d'entrée : name, email ou username. |
data.input.value | string | Non | "Antoine" | Valeur envoyée pour la prédiction. |
data.input.country | string | Oui | "FR" | Contexte de pays envoyé ; null s'il a été omis. |
data.input.forceToGenderize | boolean | Non | true | Présent uniquement lorsque le mode surnom est activé ; omis sinon. |
Champs de correspondance du jeu de données
| Champ | Type | Peut valoir null | Exemple | Description |
|---|---|---|---|---|
data.match.name | string | Oui | "antoine" | Candidat sélectionné dans le jeu de données ; null si aucune ligne n'a été sélectionnée. |
data.match.method | string | Oui | "normalized" | normalized, token, substring ou model_inference ; null si indisponible. |
data.match.scope | string | Oui | "country" | country ou global pour le jeu de données ; null pour l'IA ou en l'absence de preuve. |
data.match.country | string | Oui | "FR" | Pays de la ligne sélectionnée ; null pour les lignes globales ou l'IA. |
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. |
Un résultat inconnu renvoyé avec succès
HTTP 200 signifie que l'opération s'est terminée ; cela ne garantit pas un genre. Conservez JSON null au lieu de le convertir en male, female, en chaîne vide ou en confiance nulle. Vérifiez data.result_status et data.reason indépendamment des erreurs HTTP.
Cet exemple réel limité au jeu de données, obtenu le 1er octobre 2026, renvoie source: none et reason: not_found et coûte tout de même 1 crédit. Une ligne du jeu de données à égalité peut renvoyer reason: ambiguous tout en conservant sample_count. Un résultat inconnu de l'IA utilise source: ai et reason: insufficient_evidence.
{
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
},
"meta": {
"request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Interpréter la confiance et les indices de correspondance
Une confiance de 0.9 s'exprime sur une échelle de 0 à 1. Pour observed_frequency, il s'agit de l'effectif dominant divisé par le total de la ligne sélectionnée ; ce n'est pas une précision de bout en bout mesurée pour le produit. Un score model_reported est fourni par l'IA et n'est pas calibré par rapport aux fréquences du jeu de données.
Choisissez vos seuils applicatifs à partir de vos propres données d'évaluation et de confidence_kind. Ne classez pas directement les scores du jeu de données et de l'IA comme s'ils mesuraient la même chose. Pour l'IA, match.name, match.scope et match.country valent null car aucune ligne du jeu de données n'a été sélectionnée ; match.method vaut model_inference.
Pour un nom complet, un résultat du jeu de données peut provenir d'un composant plutôt que de la chaîne entière. data.input conserve la valeur envoyée ; data.name décrit le nom renvoyé et data.match décrit le candidat et la portée de la recherche.
Décider de la suite à donner dans votre application
Traitez d'abord les erreurs de requête et d'élément, puis examinez result_status. Pour une prédiction individuelle, lisez data ; pour un lot, appliquez la même décision à data de chaque élément réussi. Conservez les résultats unknown dans votre application au lieu d'imposer une étiquette male ou female.
| Résultat | Signification | Traitement conseillé |
|---|---|---|
| identified; gender: male ou female | L'inférence a produit un genre, à partir du jeu de données ou de l'IA. | Appliquez une règle évaluée pour ce confidence_kind ; conservez source et les indices de correspondance. |
| unknown; reason: not_found | Aucun enregistrement du jeu de données ne correspond aux candidats extraits. | Laissez gender à null. Une nouvelle requête volontaire avec d'autres options d'IA est une nouvelle opération facturable. |
| unknown; reason: no_name_candidate | L'analyse n'a produit aucun candidat de nom exploitable pour le jeu de données. | Conservez null ; vérifiez le type et la valeur d'entrée avant de demander une inférence supplémentaire. |
| unknown; reason: ambiguous | La ligne retenue du jeu de données compte autant d'occurrences masculines que féminines ; sample_count peut rester présent. | Ne départagez pas l'égalité vous-même et ne convertissez pas la confiance null en zéro. |
| unknown; reason: insufficient_evidence | L'IA a terminé sans indices suffisants pour renvoyer un genre. | Traitez-le comme un unknown terminé, et non comme une défaillance du fournisseur ni comme un motif de nouvelle tentative automatique. |
| Problem Details ou error d'un élément | L'exécution a échoué, par exemple avec ai_upstream_error ou prediction_timeout. | Conservez le code d'erreur et l'identifiant de requête, vérifiez la facturation et suivez les consignes de nouvelle tentative. |
Définir vos seuils à partir de votre propre évaluation
Aucun seuil de confiance universel ne rend une prédiction correcte. Évaluez observed_frequency et model_reported séparément, sur des exemples représentatifs de votre cas d'usage dont les étiquettes de référence ont été établies de manière indépendante. Une fréquence observée dans le jeu de données et un score déclaré par l'IA sont des signaux différents, même lorsque tous deux valent 0.9. Mesurez la part des entrées auxquelles votre règle répond et la part des réponses correctes ; conservez une voie unknown ou de révision pour les autres.
Par exemple, si result_status vaut identified mais que confidence_kind vaut model_reported, appliquez la règle évaluée pour l'IA plutôt que le seuil du jeu de données. Avec forceToGenderize, name: null accompagné d'un gender non null est valide : un alias peut être interprété sans extraire de véritable prénom. Vérifiez gender et result_status, et pas seulement name, pour savoir si l'inférence a répondu. Le résultat reste une estimation, et non une vérification de l'identité d'une personne.