Centre d’aide GenderAPI.io V2
Questions fréquentes
Réponses sur les requêtes V2, la confiance, les résultats inconnus, les crédits, la confidentialité et votre compte. Consultez la référence V1 si vous maintenez une intégration de la version précédente.
Résultats et confiance
Comprendre une prédiction et ses limites
Contexte pays, scores de confiance et résultats inconnus dans l’API V2.
Un résultat GenderAPI identifie-t-il le genre d’une personne ?
Non. GenderAPI estime le genre à partir d’indices liés au prénom ou, lorsque cette option est activée, au pseudonyme. Une prédiction n’est pas une donnée personnelle vérifiée. Conservez l’incertitude, respectez l’identité déclarée par chaque personne et ne fondez aucune décision à fort impact sur cette seule estimation.
Comment le pays influence-t-il un résultat ?
Un code pays ISO facultatif, en majuscules, apporte un contexte régional à la recherche. Ne l’envoyez que s’il est pertinent et connu. Un même prénom peut avoir des usages différents selon les régions ; le pays renvoyé indique une association du prénom, et non une preuve de nationalité ou de résidence.
Que signifie le score de confiance de V2 ?
confidence est une valeur comprise entre 0 et 1, ou null lorsqu’elle n’est pas disponible. Lisez-la avec confidence_kind : observed_frequency correspond au nombre d’occurrences de la catégorie dominante divisé par le total du jeu de données ; model_reported est un score fourni par l’IA. Ces scores ne sont ni des probabilités calibrées concernant une personne, ni une mesure de la précision du produit. Définissez vos seuils de vérification à partir de données représentatives.
Que signifie gender: null, et ce résultat est-il facturé ?
Un résultat V2 réussi avec gender: null signifie que les éléments disponibles n’ont pas permis d’identifier un genre. Il s’agit de la valeur null native de JSON, et non de la chaîne "null". Un résultat inconnu réussi est facturé selon le tarif sélectionné. Conservez-le comme inconnu ; une défaillance du fournisseur ou de la requête est une erreur distincte.
Puis-je envoyer des prénoms dans différents systèmes d’écriture ?
Oui. Envoyez les prénoms en Unicode avec leurs caractères d’origine et leurs accents significatifs. La couverture et la confiance varient selon le prénom, la région et les éléments disponibles : testez un échantillon représentatif des écritures et des pays que votre application prend en charge.
API et IA
Choisir un type de requête et une option d’IA
Types de recherche V2, lots, comportement de l’IA et limites d’utilisation.
Puis-je analyser des prénoms, des e-mails et des noms d’utilisateur dans un même lot ?
Oui. POST /api/v2/gender/batch accepte jusqu’à 50 éléments avec une clé API, ou 10 avec l’essai par IP. Chaque élément possède ses propres type, value, country facultatif et réglages d’IA. Par défaut, l’IA est désactivée pour les éléments d’un lot. Examinez chaque résultat : un lot peut renvoyer HTTP 200 alors que certains éléments ont échoué. Les crédits sont facturés par élément réussi, résultats inconnus compris.
Comment fonctionne une recherche par e-mail ?
Utilisez type: email avec une adresse valide. L’API recherche un indice de prénom exploitable dans la partie locale, avant le signe @ ; le domaine n’établit ni l’identité ni le pays d’une personne. Les boîtes partagées et les adresses opaques peuvent renvoyer un résultat inconnu. Une requête individuelle utilise par défaut l’IA en repli si le jeu de données ne permet pas de conclure.
Comment fonctionne une recherche par nom d’utilisateur ?
Utilisez type: username. La recherche ordinaire cherche un prénom reconnaissable dans un identifiant ou un nom affiché. Les pseudonymes abstraits peuvent renvoyer un résultat inconnu. Activez forceToGenderize si vous souhaitez une analyse des pseudonymes par IA après une recherche non résolue dans le jeu de données ; cette option peut produire un genre sans extraire de véritable prénom.
Quand V2 utilise-t-il l’IA ?
Les requêtes individuelles utilisent par défaut options.ai_mode: fallback : le jeu de données est consulté en premier, puis l’IA est utilisée si le genre n’est pas résolu, pour 1 crédit au total. off utilise uniquement le jeu de données pour 1 crédit ; always ignore le jeu de données et utilise l’IA pour 2 crédits. Les éléments d’un lot sont à off par défaut et peuvent activer l’IA individuellement. Aucun de ces modes ne garantit un résultat différent de null.
À quoi sert forceToGenderize ?
Cette option facultative fonctionne avec les entrées de type prénom, e-mail et nom d’utilisateur, y compris pour chaque élément d’un lot. Un résultat résolu par le jeu de données coûte 1 crédit. Sinon, l’IA adaptée aux pseudonymes est utilisée pour 2 crédits au total, même si le résultat réussi est inconnu. Un véritable prénom n’est pas nécessaire. Omettez ai_mode ou utilisez fallback ; associer cette option à off ou always renvoie 422.
Comment les crédits sont-ils décomptés dans V2 ?
Consultez meta.usage.charged_credits pour connaître le montant net facturé pour l’opération et billing_status pour sa confirmation. Les prédictions ordinaires par jeu de données et en mode fallback coûtent 1 crédit par élément réussi ; always et l’IA adaptée aux pseudonymes coûtent 2 crédits. Une vérification de numéro de téléphone terminée coûte 1 crédit, y compris lorsque le résultat est invalide. Un solde de départ positif suffit : la facturation finale peut donc le rendre négatif. Les prédictions en échec sont remboursées ; une facturation non confirmée nécessite un examen par l’assistance.
V2 impose-t-il des limites de requêtes ?
Oui. Les valeurs par défaut actuelles comprennent 120 requêtes par minute et par compte, 600 par minute et par IP, et 2 opérations simultanées par compte. La capacité partagée du service s’applique également. Le corps des requêtes POST est limité à 64 KiB ; les lots acceptent 50 éléments avec une clé ou 10 avec l’essai par IP. Respectez HTTP 429 et Retry-After au lieu de supposer que toutes les requêtes seront acceptées jusqu’à ces plafonds.
Puis-je relancer une requête en échec ou expirée ?
Chaque requête de prédiction est une nouvelle opération, facturée normalement. Un délai d’attente dépassé ou une réponse perdue ne prouve pas qu’aucun crédit n’a été débité. Vérifiez billing_status avant de relancer la requête ; contactez l’assistance avec request_id si la facturation n’est pas confirmée. Pour un lot partiellement en échec, ne relancez que les éléments en échec, une fois la facturation confirmée. En cas de 429, suivez Retry-After.
Où trouver les exemples de code et les outils V2 ?
Les guides V2 comprennent des exemples en cURL, JavaScript, Python, PHP, Java, C# et Go. Swagger et Postman utilisent le même contrat V2. Choisissez le type d’entrée et conservez votre clé API dans la configuration côté serveur.
Puis-je continuer à utiliser V1 ?
Oui. Les intégrations V1 existantes conservent leurs endpoints et leurs formats de réponse d’origine. V1 et V2 partagent la même clé API et le même solde de crédits, mais leurs champs de requête, leurs réponses et leurs erreurs diffèrent. Utilisez la référence V1 distincte pour maintenir un client existant, et le guide de migration lorsque vous êtes prêt à le mettre à jour.
Confidentialité et fichiers
Comprendre le traitement des données
Où trouver les informations en vigueur sur le traitement, la conservation et la suppression.
Les requêtes GenderAPI réussies sont-elles conservées ?
La Politique de confidentialité indique quels enregistrements de requêtes, enregistrements opérationnels et journaux de sécurité peuvent être conservés, pour quelles raisons ils sont traités et comment fonctionne leur suppression. Examinez ces informations pour votre intégration et évitez d’envoyer des données personnelles inutiles.
Les adresses e-mail envoyées dans les requêtes sont-elles conservées ?
Consultez la Politique de confidentialité pour connaître le traitement actuel des adresses e-mail envoyées et des enregistrements techniques associés. Une adresse e-mail peut constituer une donnée personnelle : n’envoyez que ce que la recherche nécessite et évitez d’inclure des adresses complètes dans vos propres journaux de diagnostic.
Combien de temps les fichiers Excel ou CSV importés sont-ils conservés ?
La Politique de confidentialité décrit la conservation, la suppression et la gestion des sauvegardes des fichiers importés. Exportez les résultats dont vous avez besoin et utilisez les commandes de suppression de l’espace de travail lorsque vous n’avez plus besoin du fichier. Contactez l’assistance pour toute question sur les exigences de conservation de votre organisation.
Des prestataires de services peuvent-ils traiter les requêtes ou les fichiers importés ?
La Politique de confidentialité et les informations sur les sous-traitants décrivent le traitement effectué par des prestataires de services et les garanties applicables. Examinez ces ressources, ainsi que tout accord applicable à votre compte, pour évaluer où vos données sont traitées.
Politique de confidentialité →Sous-traitants →Informations sur le RGPD →
Compte et assistance
Connecter votre clé et gérer votre compte
Accès gratuit, authentification, consultation du solde et assistance.
Puis-je essayer GenderAPI gratuitement ?
Oui. Un compte gratuit enregistré comprend 200 crédits par jour. Par ailleurs, l’essai V2 sans clé offre 10 crédits par adresse IP publique sur une période de 24 heures, partagés avec V1 et les autres utilisateurs de cette IP. Les deux appliquent les tarifs habituels ; le nombre de crédits ne correspond pas toujours au nombre de requêtes HTTP.
Comment m’authentifier et protéger ma clé API ?
Utilisez Authorization: Bearer YOUR_API_KEY depuis du code serveur de confiance ; les requêtes POST nécessitent aussi Content-Type: application/json. N’exposez jamais la vraie clé dans du code exécuté par le navigateur, dans des dépôts publics ou dans des journaux. Une clé absente, mal formée ou inconnue peut basculer sur l’essai par IP : vérifiez donc que meta.access.mode vaut api_key. Une clé connue mais désactivée, expirée ou restreinte ne bascule pas sur l’essai.
Comment consulter mes crédits restants ?
Appelez GET /api/v2/usage avec votre clé Bearer. Cette consultation du solde est gratuite et renvoie data.remaining_credits. Sans clé, elle lit le solde partagé de l’essai par IP. V1 et V2 utilisent le même solde de compte ; la valeur remaining_credits d’une prédiction reflète le solde au moment où l’opération s’est terminée.
Où puis-je gérer ou résilier un abonnement ?
Connectez-vous à l’application GenderAPI pour gérer l’abonnement associé à votre clé API. Utilisez les paramètres actuels du compte pour consulter votre offre et les options de résiliation.
Où puis-je mettre à jour mes informations de facturation ?
Gérez les paramètres de facturation et de paiement dans l’application GenderAPI, une fois connecté au compte de la clé API ou de l’abonnement concerné.
Comment signaler un résultat incorrect ou demander de l’aide pour une intégration ?
Envoyez à l’assistance la version de l’API, l’endpoint, request_id et un petit exemple reproductible. Indiquez le code d’erreur lorsqu’il est disponible, mais retirez votre clé API et toute donnée personnelle sensible.
Base de connaissances technique
Guides d’intégration et d’utilisation responsable
Réponses sur les résultats, la confidentialité et le fonctionnement de V2, avec des liens vers les guides et une version Markdown de chaque réponse.
Résultats, confiance et utilisation responsable
Une prédiction V2 non résolue utilise la valeur null native de JSON pour gender, et non la chaîne "null". Un prénom peut être ambigu, ou les éléments disponibles insuffisants ; consultez result_status et reason lorsqu’ils sont présents. Conservez le résultat inconnu au lieu de le forcer dans une catégorie. Une prédiction inconnue réussie est facturée selon le tarif sélectionné. Les erreurs de requête ou du fournisseur sont des échecs distincts, dont les informations de facturation figurent dans meta.usage.
Lire la réponse complète →Comment la précision de GenderAPI est-elle évaluée ?Une évaluation de précision utile indique sa population de test, sa date, sa méthode d’échantillonnage, la part de résultats inconnus et les résultats par région et par système d’écriture. La page de méthodologie actuelle décrit un protocole d’évaluation, et non un pourcentage de précision mesuré. Les champs confidence et confidence_kind de V2 expliquent les éléments sur lesquels repose chaque résultat ; ils ne remplacent pas une évaluation sur des données représentatives.
Lire la réponse complète →Sources de données, confidentialité et conformité
La page sur la provenance des données décrit le cadre utilisé pour documenter les catégories de sources, les critères de sélection, les licences et les limites géographiques ou liées aux systèmes d’écriture. Elle ne publie pas actuellement de catalogue de sources vérifié. Consultez cette page et contactez l’assistance pour les exigences propres à votre intégration ; ne supposez aucune source, taille de jeu de données ni couverture qui n’a pas été documentée.
Lire la réponse complète →À quelle fréquence les données sur les prénoms sont-elles mises à jour ?La page actuelle sur la provenance des données n’indique pas de calendrier de mise à jour unique pour l’ensemble des enregistrements de prénoms ou des règles de traitement. Si la fraîcheur des données compte pour votre cas d’usage, interrogez l’assistance sur le jeu de données ou le flux concerné et évaluez des résultats représentatifs. La date de révision d’une page ne prouve pas que tous les enregistrements sous-jacents ont été actualisés à cette date.
Lire la réponse complète →Où trouver les informations sur le RGPD et l’accord de traitement des données ?La Politique de confidentialité, les informations sur le RGPD, l’Accord de traitement des données et le registre des sous-traitants décrivent les conditions de traitement et les garanties publiées. Consultez les documents en vigueur et tout accord applicable à votre compte. Contactez GenderAPI pour les questions propres à votre organisation concernant les rôles de traitement, les transferts ou les demandes des personnes concernées ; une FAQ générale ne remplace pas l’accord applicable.
Lire la réponse complète →Fonctionnement de l’API, erreurs et facturation
Utilisez Authorization: Bearer YOUR_API_KEY depuis du code serveur de confiance. Les requêtes POST de V2 nécessitent aussi Content-Type: application/json. GET /api/v2/gender accepte en outre une clé dans les paramètres de requête, mais les en-têtes évitent d’exposer les identifiants dans les URL du navigateur. Une clé absente, mal formée ou inconnue peut basculer sur l’essai partagé par IP ; vérifiez que meta.access.mode vaut api_key pour une intégration liée à un compte. Une clé connue mais désactivée, expirée ou restreinte ne bascule pas sur l’essai.
Lire la réponse complète →Comment gérer les limites de requêtes et les nouvelles tentatives ?V2 applique des limites de débit et de simultanéité ; respectez HTTP 429 et Retry-After. Chaque prédiction relancée est une nouvelle opération, facturée normalement. Ne relancez pas automatiquement une requête après un délai d’attente dépassé, une réponse perdue ou une facturation non confirmée. Examinez d’abord code, action et meta.usage.billing_status ; en cas de billing_reconciliation_required, contactez l’assistance avec request_id. N’utilisez un backoff borné que lorsque la facturation est confirmée et que l’action documentée autorise une nouvelle tentative.
Lire la réponse complète →Comment interpréter les erreurs de V2 ?Les erreurs de l’API V2 utilisent des statuts HTTP d’erreur et des Problem Details conformes à la RFC 9457, avec des champs code et action stables. Lisez ces champs plutôt que de comparer le texte de detail, et conservez request_id pour l’assistance. Un résultat inconnu réussi n’est pas une erreur. Une réponse de lot peut contenir des erreurs par élément même avec HTTP 200. Un proxy peut renvoyer une erreur non JSON, et une réponse perdue ou illisible ne prouve pas qu’aucun crédit n’a été débité.
Lire la réponse complète →Comment consulter les crédits restants ?Appelez GET /api/v2/usage avec votre clé API Bearer depuis du code serveur de confiance. Cette requête est gratuite et renvoie data.remaining_credits ; sans clé, elle lit l’essai partagé par IP. V1 et V2 utilisent le même solde de compte. Le champ meta.usage d’une prédiction indique le montant facturé pour cette opération et le solde au moment où elle s’est terminée, qui peut évoluer avec des requêtes simultanées. N’écrivez pas les identifiants dans les journaux et ne considérez pas une lecture du solde comme la preuve qu’une requête dont la réponse a été perdue n’a pas été facturée.
Lire la réponse complète →Comment passer de V1 à V2 sans casser mon intégration ?Utilisez V2 pour les nouvelles intégrations et conservez les clients V1 existants sur leurs chemins documentés jusqu’à ce que vous décidiez de les migrer. Les deux versions partagent les clés API et les crédits, mais leurs champs de requête, leurs structures de réponse et leurs formats d’erreur diffèrent. Suivez le guide de migration, testez les résultats réussis, inconnus et en erreur, puis mettez à jour votre code d’analyse des réponses avant de changer d’endpoint. La référence V1 reste disponible pour les intégrations existantes.
Lire la réponse complète →Comment diagnostiquer les échecs et suivre la disponibilité du service ?Si des requêtes échouent, utilisez le code d’erreur renvoyé pour distinguer une défaillance du service d’une entrée invalide, d’un problème d’accès au compte, de crédits épuisés ou de limites de requêtes. Surveillez le taux de réussite et la latence des requêtes dans votre propre intégration. Contactez l’assistance avec request_id en cas d’échec inexpliqué ou de facturation incertaine. Appuyez toute affirmation de disponibilité sur des mesures ; cette FAQ n’indique aucun pourcentage de disponibilité garanti.
Lire la réponse complète →Encore besoin d’aide ?
Envoyez-nous un exemple reproductible
Indiquez l’endpoint, les paramètres et l’erreur renvoyée, mais ne partagez ni votre clé API de production ni de données personnelles sensibles.