API DOCUMENTATION

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Query by First Name (v2)
PURPOSE: Determine gender from first names with optional country localization for enhanced accuracy.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <your authorization token> 
link

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Name to query

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

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Browser Locale

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Valid IPv4 or IPv6 address

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Max 50 chars. You can set this id to any alphanumeric value you want.
            As an example, you can set the id to your internal id of the dataset in your database. In an asynchronus 
            environment this can help you to better connect the response to a previous request

--- REQUEST EXAMPLES ---

Example 1: Query by first name only
Request Body (JSON):
{
    "first_name": "Sandra"
}

Example 2: Query by first name and country code
Request Body (JSON):
{
    "first_name": "Sandra",
    "country": "US"
}

Example 3: Query by first name and browser locale
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: Query by first name and use an IP address for localization
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

Example 5: Query multiple names in a single request
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: The submitted payload

Field: details.credits_used
  Type: int
  Description: The amount of requests used for this query

Field: details.samples
  Type: int
  Description: Number of records found in our database which match your request

Field: details.country
  Type: string
  Description: The country we found

Field: details.first_name_sanitized
  Type: string
  Description: The name after we applied our normalizer to it

Field: details.duration
  Type: string
  Description: Time the server needed to process the request

Field: result_found
  Type: bool
  Description: True if we were able to query a gender for the given name

Field: first_name
  Type: string
  Description: The first name we used for genderization

Field: probability
  Type: float
  Description: This value (between 0 and 1) determines the reliability of our database. A value of 1 means that the results on your gender request are 100% accurate.

Field: gender
  Type: string
  Description: Possible values: 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 <your authorization token> link' \
  -d '{"first_name":"Sandra"}'

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

=== END OF INSTRUCTIONS ===