Réponses et confiance API v2 JSON

Comprendre la réponse JSON

Les réponses uniques réussies contiennent data et meta. La réponse à l'ensemble de données ci-dessous est un exemple illustratif, et non une mesure de la précision du produit ou une promesse du même résultat en direct. Il montre l'accès à l'essai IP. Les demandes authentifiées avec une clé de compte renvoient access.mode: api_key ; les champs qui s'appliquent uniquement à l'essai ont la valeur null.

Champ	Signification
data.input	Type d'entrée, valeur et pays. forceToGenderize est inclus lorsque true.
data.name	Prénom correspondant ou extrait ; null lorsqu’aucun n’est disponible.
data.gender	male, female ou JSON null. Il s’agit d’une prédiction et non d’une preuve de l’identité d’une personne.
data.result_status / reason	Lorsque result_status est identified, reason est null. Lorsque le statut est unknown, la raison est not_found, no_name_candidate, ambiguous ou insufficient_evidence.
data.confidence	score de 0 à 1 ou null. Le genre nul a la confiance null.
data.confidence_kind	observed_frequency : nombre de sexes dominants divisé par le nombre total dans l'ensemble de données sélectionné. model_reported : un score IA, pas une probabilité calibrée. La valeur est null lorsqu'elle n'est pas disponible.
data.sample_count	Taille de l'échantillon de l'ensemble de données ou null. L’IA n’invente pas de décompte d’échantillons. Ensemble de données
data.source	dataset, ai ou none.
data.country / country_source	Association de pays à partir de l'ensemble de données ou ai_association, ou null. N’établit pas la nationalité, la résidence ou l’origine ethnique.
data.match	Nom correspondant dans le jeu de données, méthode (normalized, token, substring ou model_inference), portée (country ou global) et pays associé. Les informations indisponibles valent null.
meta.request_id / duration_ms	Identifiant de l'opération et durée du traitement en millisecondes.
meta.access	Comment l'accès a été accordé et la raison de l'essai de repli, le cas échéant.
meta.usage	Frais nets, solde du temps d'achèvement, état de facturation et informations de réinitialisation de l'essai.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

Schémas de réponse complets et exemples de lots

Un résultat inconnu réussi

HTTP 200 signifie l'opération terminée ; cela ne garantit pas un genre. Conservez JSON null plutôt que de le convertir en male, female, une chaîne vide ou une confiance nulle. Vérifiez les erreurs data.result_status et data.reason séparément des erreurs HTTP.

Cet exemple d'ensemble de données uniquement renvoie source: none et reason: not_found et coûte toujours 1 crédit. Si le nombre de jeux de données pour les deux sexes est égal, le résultat peut contenir reason: ambiguous tout en préservant sample_count. Un résultat IA inconnu 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": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 8,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

Interpréter la confiance et les preuves correspondantes

Un niveau de confiance de 0,9 est sur une échelle de 0 à 1. Pour observed_frequency, cela signifie le nombre dominant divisé par le total de l'ensemble de données sélectionné ; il ne s’agit pas d’une précision mesurée du produit de bout en bout. Un score model_reported est fourni par l'IA et n'est pas calibré par rapport aux fréquences des ensembles de données.

Choisissez n'importe quel seuil d'application en utilisant vos propres données d'évaluation et confidence_kind. Ne classez pas directement les ensembles de données et les scores de l’IA comme s’ils mesuraient la même chose. IA match.name, match.scope et match.country sont null car aucune ligne d'ensemble de données n'a été sélectionnée ; match.method est model_inference.

Pour les noms complets, le résultat d'un ensemble de données peut provenir d'un composant plutôt que de la chaîne complète. data.input conserve la valeur soumise ; data.name décrit le nom renvoyé et data.match décrit le candidat et la portée de la recherche.

Comprendre la réponse JSON

Un résultat inconnu réussi

Interpréter la confiance et les preuves correspondantes

Guides associés