API DOKÜMANTASYONU

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: İlk İsimle Sorgula (v2)
PURPOSE: İlk adlardan cinsiyeti belirle, isteğe bağlı ülke yerelleştirmesiyle doğruluğu artır.

--- 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: first_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 ad ile sorgu yapma
Request Body (JSON):
{
    "first_name": "Sandra"
}

Example 2: Ad ve ülke kodu ile sorgu yapma
Request Body (JSON):
{
    "first_name": "Sandra",
    "country": "US"
}

Example 3: Ad ve tarayıcı yereli ile sorgu yapma
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: Ad ve bölge belirlemek için IP adresi kullanarak sorgu yapma
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

Example 5: Birden fazla adı tek bir istekte sorgula
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: 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.first_name_sanitized
  Type: string
  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: first_name
  Type: string
  Description: Cinsiyetlendirme için kullandığımız ilk 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 '{"first_name":"Sandra"}'

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

=== END OF INSTRUCTIONS ===