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. Vous pouvez régler cet identifiant sur la valeur alphanumérique de votre choix.
            Par exemple, vous pouvez définir l'identifiant comme étant votre identifiant interne de l'ensemble de données de votre base de données. Dans un environnement asynchrone
            cela peut vous aider à mieux relier la réponse à une demande 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: Requête de plusieurs noms dans 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: Quantité de crédits utilisés pour cette demande

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

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 demande

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 indique la fiabilité de notre base de données. Une valeur de 1 signifie que les résultats concernant ta demande d’identification de sexe sont précis à 100 %.

Field: gender
  Type: string
  Description: Valeurs possibles : homme, femme, sexe inconnu

--- 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 ===