API de genre par prénom | Requête individuelle

Vue d’ensemble

Envoyez un prénom par requête

Envoyez un objet JSON contenant un prénom et authentifiez la requête avec un jeton Bearer. Ajoutez le code pays lorsque les usages régionaux peuvent améliorer l’estimation.

MéthodePOST

Type de contenuapplication/json

AuthentificationJeton Bearer

Coût en crédits1 requête

HDR

En-têtes HTTP obligatoires

Autorisez la requête

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

Conservez la clé API dans les variables d’environnement du serveur. Consultez le guide d’authentification pour protéger vos identifiants.

Corps JSON de la requête

Paramètres

Paramètre	Type	Statut	Description
`name`	string	Obligatoire	Prénom à analyser. Envoyez un prénom propre, sans titre ni préfixe.
`country`	string	Facultatif	Code pays ISO 3166-1 alpha-2, par exemple FR ou US, pour ajouter un contexte régional.
`askToAI`	boolean	Facultatif	Si true, utilise l’assistance IA lorsque le prénom est absent de la base de données.
`forceToGenderize`	boolean	Facultatif	Si true, tente de produire un résultat pour un alias ou une entrée qui ne ressemble pas à un prénom courant.

À propos de l’assistance IA

askToAI ne s’applique que lorsque la base de données ne renvoie aucun résultat. Une estimation forcée sur une entrée inhabituelle peut être moins fiable : utilisez probability comme signal de contrôle important.

Exemples de code

Envoyez une requête individuelle

Tous les exemples envoient la même requête avec une authentification Bearer.

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Alice","country":"FR","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "FR", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "FR", "askToAI": True}
)
print(response.json())

Réponse 200

Résultat de l’estimation

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "FR",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

Champs de la réponse

Champ	Type	Description
`status`	boolean	Indique si la requête a été traitée correctement.
`used_credits`	integer	Crédits consommés par cette requête.
`remaining_credits`	integer	Crédits disponibles après la requête.
`expires`	integer	Date d’expiration du pack sous forme d’horodatage UNIX.
`q`	string	Prénom transmis à l’origine dans la requête.
`name`	string	Prénom analysé par GenderAPI.
`gender`	string \| null	Valeur estimée : male, female ou null.
`country`	string	Code pays pris en compte pour l’estimation.
`total_names`	integer	Nombre d’échantillons sur lesquels repose l’estimation.
`probability`	integer	Niveau de confiance de l’estimation, exprimé en pourcentage.
`duration`	string	Temps de traitement côté serveur.

Envoyez des données propres et correctement encodées

Utilisez un prénom sans titre ni préfixe. Les clients JSON gèrent automatiquement l’encodage, mais validez toujours les entrées externes avant de créer le corps de la requête.

Guide suivant

Analysez plusieurs prénoms

Requête avec plusieurs prénomsTraitez plusieurs prénoms en une seule requête →AuthentificationRevoir la sécurité de la clé API →