DOCUMENTATION DE L’API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Recherche par prénom (v2)
PURPOSE: Détermine le genre à partir des prénoms avec une localisation par pays en option pour une précision accrue.

--- API DETAILS ---
Method: POST
URL: https://gender-api.com/v2/gender

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <ton jeton d'autorisation> 
link

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Nom faisant l’objet de la demande

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: Code pays ISO 3166 ALPHA-2 link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Navigateur local

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Adresse IPv4 ou IPv6 valide

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Max 50 chars. Tu peux définir cet identifiant sur la valeur alphanumérique de ton choix.
Par exemple, tu peux y mettre l’identifiant interne du jeu de données dans ta base de données. Dans un environnement asynchrone, cela t’aide à mieux relier la réponse à une requête précédente

--- REQUEST EXAMPLES ---

Example 1: Requête par prénom uniquement
Request Body (JSON):
{
    "first_name": "Sandra"
}

Example 2: Requête par prénom et code pays
Request Body (JSON):
{
    "first_name": "Sandra",
    "country": "US"
}

Example 3: Requête par le prénom et la langue du navigateur
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: Requête par le prénom et utilisation d'une adresse IP pour la localisation
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

Example 5: Interroger plusieurs noms en une seule requête
Request Body (JSON):
[
    {
        "first_name": "Sandra",
        "country": "US"
    },
    {
        "first_name": "Jason",
        "country": "US"
    }
]

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "first_name": "Sandra"
    },
    "details": {
        "credits_used": 1,
        "samples": 464,
        "country": null,
        "first_name_sanitized": "sandra",
        "duration": "436ms"
    },
    "result_found": true,
    "first_name": "Sandra",
    "probability": 0.85,
    "gender": "female"
}

--- RESPONSE FIELDS ---

Field: input
  Type: object
  Description: La charge utile soumise

Field: details.credits_used
  Type: int
  Description: Nombre de requêtes utilisées pour cette recherche

Field: details.samples
  Type: int
  Description: Nombre d’enregistrements trouvés dans notre base de données qui correspondent à ta requête

Field: details.country
  Type: string
  Description: Le pays que nous avons trouvé

Field: details.first_name_sanitized
  Type: string
  Description: Le nom après utilisation de notre normalisateur

Field: details.duration
  Type: string
  Description: Temps nécessaire au serveur pour traiter la requête

Field: result_found
  Type: bool
  Description: Vrai si on pouvait interroger un genre pour le prénom

Field: first_name
  Type: string
  Description: Le premier nom que nous avons utilisé pour la sexospécificité

Field: probability
  Type: float
  Description: Cette valeur (entre 0 et 1) indique la fiabilité de notre base de données. Une valeur de 1 signifie que les résultats de ta requête de genre sont fiables à 100 %.

Field: gender
  Type: string
  Description: Valeurs possibles : male, female, unknown

--- IMPLEMENTATION NOTES ---

1. Make sure to replace placeholder values:
   - Replace '' with your actual API key
   - Replace domain placeholders with the actual API domain

2. Handle errors appropriately:
   - Check HTTP status codes
   - Parse error responses
   - Implement retry logic for transient failures

3. Best Practices:
   - Store API keys securely (use environment variables)
   - Implement rate limiting on your side
   - Cache responses when appropriate
   - Use HTTPS for all requests
   - Set appropriate timeout values

4. RECOMMENDED: Implement the Statistics Endpoint
   - The statistics endpoint allows users to monitor their credit usage
   - Users can see how many credits they have used and how many are left
   - This helps prevent unexpected service interruptions
   - API v1: GET /get-stats?key=YOUR_API_KEY
   - API v2: GET /v2/statistic (with Authorization Bearer token)
   - Display remaining credits in your application's UI
   - Consider adding alerts when credits are running low

--- IMPLEMENTATION TEMPLATE ---

// Example implementation in cURL:
curl -X POST \
  'https://gender-api.com/v2/gender' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ton jeton d'autorisation> link' \
  -d '{"first_name":"Sandra"}'

--- CREDIT USAGE ---
Required Requests: 1

=== END OF INSTRUCTIONS ===