API-DOKUMENTATION

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Abfrage nach Vornamen (v2)
PURPOSE: Bestimme das Gender aus Vornamen mit optionaler Länder-Lokalisierung für höhere Genauigkeit.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <dein Authentifizierungstoken> 
link

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Name der abgefragt werden soll

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: ISO 3166 ALPHA-2 Länderkürzel link

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

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Gültige IPv4 oder IPv6 Adresse

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Max. 50 Zeichen. Du kannst diesem Feld einen beliebigen Alphanumerischen Wert mitgeben.
            Beispielsweise kann als ID die interne ID des Datensatzes aus deiner Datenbank gesetzt werden. In einer asynchronen Umgebung kann dadurch z.B. unsere Serverantwort besser der vorhergehenden Anfrage zugeordnet werden

--- REQUEST EXAMPLES ---

Example 1: Abfrage nur mit einem Vornamen
Request Body (JSON):
{
    "first_name": "Sandra"
}

Example 2: Abfrage nach Vornamen und Ländercode
Request Body (JSON):
{
    "first_name": "Sandra",
    "country": "US"
}

Example 3: Abfrage nach Vorname und Browser Locale
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: Abfrage anhand des Vornamens und benutze eine IP Adresse zur Lokalisierung
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

Example 5: Abfrage mehrere Namen in einem einzigen Query
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: Der übergebene Input

Field: details.credits_used
  Type: int
  Description: Die Anzahl an Anfragen, die für diesen Query nötig waren

Field: details.samples
  Type: int
  Description: Anzahl an Einträgen die auf deine Anfrage in unserer Datenbank gefunden wurden

Field: details.country
  Type: string
  Description: Das gefundene Land

Field: details.first_name_sanitized
  Type: string
  Description: Der Name, nachdem wir ihn normalisiert haben

Field: details.duration
  Type: string
  Description: Zeit, wie lange der Server gebraucht hat, um die Antwort zu ermitteln

Field: result_found
  Type: bool
  Description: True, wenn wir ein Geschlecht zum angegebenen Namen bestimmen konnten

Field: first_name
  Type: string
  Description: Der gefundene Vorname, den wir zur Bestimmung des Geschlechts genutzt haben

Field: probability
  Type: float
  Description: Dieser Wert (zwischen 0 und 1) bestimmt, wie sicher wir uns sind, das richtige Geschlecht gefunden zu haben. Ein Wert von 1 sagt aus, dass wir uns zu 100% sicher sind.

Field: gender
  Type: string
  Description: Mögliche Antworten: male, female, uknown

--- 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 <dein Authentifizierungstoken> link' \
  -d '{"first_name":"Sandra"}'

--- CREDIT USAGE ---
Required Requests: 1 Credit für jede erfolgreiche Anfrage

=== END OF INSTRUCTIONS ===