API-DOCUMENTATIE

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Opvragen op Volledige Naam (v2)
PURPOSE: Splits automatisch volledige namen en bepaal het geslacht in één efficiënte API-call.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <je autorisatietoken> 
link

--- REQUEST PARAMETERS ---

Parameter: full_name
  Type: string
  Required: REQUIRED
  Description: Naam om op te zoeken

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

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Browsertaal

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Geldig IPv4- of IPv6-adres

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Max. 50 tekens. Je kunt deze id op elke alfanumerieke waarde zetten die je wilt. Je kunt de id bijvoorbeeld op je eigen interne id van de dataset in je database zetten. In een asynchrone omgeving kan dit je helpen om de respons beter aan een eerder verzoek te koppelen

--- REQUEST EXAMPLES ---

Example 1: Zoeken op alleen een volledige naam
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 2: Zoeken op volledige naam en landcode
Request Body (JSON):
{
    "full_name": "Theresa Miller",
    "country": "US"
}

Example 3: Zoeken op volledige naam en browsertaal
Request Body (JSON):
{
    "full_name": "Thomas Johnson",
    "locale": "en_US"
}

Example 4: Zoeken op volledige naam en een IP-adres gebruiken voor lokalisatie
Request Body (JSON):
{
    "full_name": "Markus Stefan NonExistingLastName",
    "ip": "54.201.16.177"
}

Example 5: Meerdere namen opzoeken in één verzoek
Request Body (JSON):
[
    {
        "full_name": "Theresa Miller"
    },
    {
        "full_name": "Thomas Johnson",
        "country": "US"
    }
]

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "full_name": "Theresa Miller"
    },
    "details": {
    "credits_used": 1,
        "duration": "33ms",
        "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: De ingediende payload

Field: details.credits_used
  Type: int
  Description: Het aantal verzoeken dat voor deze query is gebruikt

Field: details.samples
  Type: int
  Description: Aantal records in onze database dat overeenkomt met je verzoek

Field: details.country
  Type: string
  Description: Het land dat we hebben gevonden

Field: details.full_name_sanitized
  Type: int
  Description: De naam nadat we onze normalisator erop hebben toegepast

Field: details.duration
  Type: string
  Description: Tijd die de server nodig had om het verzoek te verwerken

Field: result_found
  Type: bool
  Description: true als we een geslacht hebben kunnen vinden voor de opgegeven naam

Field: full_name
  Type: string
  Description: De volledige naam die we hebben gebruikt om het geslacht te bepalen

Field: probability
  Type: float
  Description: Deze waarde (tussen 0 en 1) bepaalt de betrouwbaarheid van onze database. Een waarde van 1 betekent dat de resultaten van je geslachtsverzoek 100% nauwkeurig zijn.

Field: gender
  Type: string
  Description: Mogelijke waarden: 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 <je autorisatietoken> link' \
  -d '{"full_name":"Theresa Miller"}'

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

=== END OF INSTRUCTIONS ===