DOCUMENTACIÓN DE LA API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Consultar por dirección de correo electrónico (v2)
PURPOSE: Extrae nombres de direcciones de correo electrónico y determina el género con algoritmos avanzados de análisis.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <us fichas de autorización> 
link

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: Dirección de correo electrónico para la consulta

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: ISO 3166 ALPHA-2 Código de país link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Navegador Local

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Dirección IPv4 o IPv6 válida

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Máximo 50 caracteres. Puede configurar esta identificación a cualquier valor alfanumérico que desee.
            Como ejemplo, puede establecer el id a su id interno del conjunto de datos en su base de datos. En un asíncrono 
            ambiente esto puede ayudar a conectar mejor la respuesta a una solicitud anterior

--- REQUEST EXAMPLES ---

Example 1: Consulta por correo electrónico solamente
Request Body (JSON):
{
    "email": "theresa.miller14@gmail.com"
}

Example 2: Consulta por correo electrónico y código de país
Request Body (JSON):
{
    "email": "thomas.clarks@hotmail.com",
    "country": "US"
}

Example 3: Consulta por dirección de correo electrónico y localización del navegador
Request Body (JSON):
{
    "email": "Thomas.j32@live.com",
    "locale": "en_US"
}

Example 4: Consultar por correo electrónico y utilizar una dirección IP para la localización
Request Body (JSON):
{
    "email": "thomasfromnewyork@gmail.com",
    "ip": "54.201.16.177"
}

Example 5: Consultar varios nombres en una sola solicitud
Request Body (JSON):
[
    {
        "email": "thomas.clarks@hotmail.com",
        "country": "US"
    },
    {
        "email": "theresa.miller14@gmail.com"
    }
]

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "email": "theresa.miller14@gmail.com"
    },
    "details": {
        "credits_used": 1,
        "duration": "12ms",
        "samples": 8961,
        "country": null,
        "first_name_sanitized": "theresa"
    },
    "result_found": true,
    "last_name": "Miller",
    "first_name": "Theresa",
    "probability": 0.98,
    "gender": "female"
}

--- RESPONSE FIELDS ---

Field: input
  Type: object
  Description: La carga útil enviada

Field: details.credits_used
  Type: int
  Description: La cantidad de créditos utilizados para esta consulta

Field: details.samples
  Type: int
  Description: Número de registros encontrados en nuestra base de datos que coinciden con su solicitud

Field: details.country
  Type: string
  Description: El país que encontramos

Field: details.email_sanitized
  Type: int
  Description: El nombre después de que le aplicamos nuestro normalizador

Field: details.duration
  Type: string
  Description: El tiempo que el servidor necesitaba para procesar la solicitud

Field: result_found
  Type: bool
  Description: Es cierto que si pudiéramos consultar el género del primer nombre

Field: email
  Type: string
  Description: La dirección de correo electrónico que hemos utilizado para la genderización

Field: probability
  Type: float
  Description: Este valor (entre 0 y 1) determina la fiabilidad de nuestra base de datos. Un valor de 1 significa que los resultados de su solicitud de género son 100% exactos.

Field: gender
  Type: string
  Description: Valores posibles: masculino, femenino, desconocido

--- 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 <us fichas de autorización> link' \
  -d '{"email":"theresa.miller14@gmail.com"}'

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

=== END OF INSTRUCTIONS ===