ΤΕΚΜΗΡΙΩΣΗ API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Αναζήτηση με πλήρες όνομα (v2)
PURPOSE: Διαίρεσε αυτόματα ολόκληρα ονόματα και προσδιόρισε το gender σε μία αποδοτική κλήση API.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <το διακριτικό εξουσιοδότησής σας> 
link

--- REQUEST PARAMETERS ---

Parameter: full_name
  Type: string
  Required: REQUIRED
  Description: Όνομα για αναζήτηση

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: Κωδικός Χώρας ISO 3166 ALPHA-2 link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Τοπική διαμόρφωση προγράμματος περιήγησης

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Έγκυρη διεύθυνση IPv4 ή IPv6

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Μέγιστος αριθμός χαρακτήρων: 50. Μπορείς να ορίσεις αυτό το id σε οποιαδήποτε αλφαριθμητική τιμή θέλεις. 
            Ως παράδειγμα, μπορείς να ορίσεις το id στο εσωτερικό id του dataset στη βάση δεδομένων σου. Σε ένα ασύγχρονο 
            περιβάλλον αυτό μπορεί να σε βοηθήσει να συνδέσεις καλύτερα την απάντηση με μια προηγούμενη αίτηση

--- REQUEST EXAMPLES ---

Example 1: Αναζήτηση μόνο με πλήρες όνομα
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 2: Αναζήτηση με πλήρες όνομα και κωδικό χώρας
Request Body (JSON):
{
    "full_name": "Theresa Miller",
    "country": "US"
}

Example 3: Αναζήτηση με πλήρες όνομα και γλώσσα περιηγητή
Request Body (JSON):
{
    "full_name": "Thomas Johnson",
    "locale": "en_US"
}

Example 4: Αναζήτηση με πλήρες όνομα και χρήση διεύθυνσης IP για εντοπισμό
Request Body (JSON):
{
    "full_name": "Markus Stefan NonExistingLastName",
    "ip": "54.201.16.177"
}

Example 5: Αναζήτηση πολλαπλών ονομάτων σε ένα αίτημα
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: Το υποβληθέν φορτίο

Field: details.credits_used
  Type: int
  Description: Η ποσότητα αιτημάτων που χρησιμοποιήθηκαν για αυτό το ερώτημα

Field: details.samples
  Type: int
  Description: Αριθμός εγγραφών που βρέθηκαν στη βάση δεδομένων μας και ταιριάζουν με το αίτημά σου

Field: details.country
  Type: string
  Description: Η χώρα που βρήκαμε

Field: details.full_name_sanitized
  Type: int
  Description: Το όνομα μετά την εφαρμογή του κανονικοποιητή μας

Field: details.duration
  Type: string
  Description: Χρόνος που χρειάστηκε ο διακομιστής για να επεξεργαστεί το αίτημα

Field: result_found
  Type: bool
  Description: Αληθές αν μπορέσαμε να προσδιορίσουμε το φύλο για το συγκεκριμένο όνομα

Field: full_name
  Type: string
  Description: Το πλήρες όνομα που χρησιμοποιήσαμε για τον προσδιορισμό του φύλου

Field: probability
  Type: float
  Description: Αυτή η τιμή (μεταξύ 0 και 1) καθορίζει την αξιοπιστία της βάσης δεδομένων μας. Μια τιμή 1 σημαίνει ότι τα αποτελέσματα στο αίτημά σου για το φύλο είναι 100% ακριβή.

Field: gender
  Type: string
  Description: Πιθανές τιμές: 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 <το διακριτικό εξουσιοδότησής σας> link' \
  -d '{"full_name":"Theresa Miller"}'

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

=== END OF INSTRUCTIONS ===