API DOKÜMANTASYONU

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Tam İsimle Sorgula (v2)
PURPOSE: Tam adları otomatik olarak parçala ve cinsiyeti tek, verimli bir API çağrısıyla belirle.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <yetkilendirme token’ın> 
link

--- REQUEST PARAMETERS ---

Parameter: full_name
  Type: string
  Required: REQUIRED
  Description: Sorgulamak için isim

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: ISO 3166 ALPHA-2 Ülke Kodu link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Tarayıcı Dil Ayarı

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Geçerli IPv4 veya IPv6 adresi

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Maksimum 50 karakter. Bu kimliği herhangi bir alfanumerik değere ayarlayabilirsin.

 Örnek olarak, kimliği veritabanındaki veri kümesinin iç kimliği olarak ayarlayabilirsin. Asenkron bir ortamda, bu sana önceki bir isteği yanıta daha iyi bağlamana yardımcı olabilir

--- REQUEST EXAMPLES ---

Example 1: Sadece tam adla sorgula
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 2: Tam ad ve ülke kodu ile sorgula
Request Body (JSON):
{
    "full_name": "Theresa Miller",
    "country": "US"
}

Example 3: Tam ad ve tarayıcı dil koduyla sorgula
Request Body (JSON):
{
    "full_name": "Thomas Johnson",
    "locale": "en_US"
}

Example 4: Tam ada göre sorgula ve konumlandırma için IP adresi kullan
Request Body (JSON):
{
    "full_name": "Markus Stefan NonExistingLastName",
    "ip": "54.201.16.177"
}

Example 5: Birden fazla adı tek bir istekte sorgula
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: Gönderilen veri yükü

Field: details.credits_used
  Type: int
  Description: Bu sorgu için kullanılan istek sayısı

Field: details.samples
  Type: int
  Description: İstediğinle eşleşen veritabanımızdaki kayıt sayısı

Field: details.country
  Type: string
  Description: Bulduğumuz ülke

Field: details.full_name_sanitized
  Type: int
  Description: Normalizasyon işlemimizi uyguladıktan sonra isim

Field: details.duration
  Type: string
  Description: Sunucunun isteği işlemesi için gereken zaman

Field: result_found
  Type: bool
  Description: Belirtilen isim için bir cinsiyet sorgulayabildiysek doğru

Field: full_name
  Type: string
  Description: Cinsiyetlendirme için kullandığımız tam isim

Field: probability
  Type: float
  Description: Bu değer (0 ile 1 arasında) veritabanımızın güvenilirliğini belirler. 1 değeri, cinsiyet isteğine dönen sonuçların %100 doğru olduğu anlamına gelir.

Field: gender
  Type: string
  Description: Olası değerler: 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 <yetkilendirme token’ın> link' \
  -d '{"full_name":"Theresa Miller"}'

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

=== END OF INSTRUCTIONS ===