API DOKÜMANTASYONU

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: E‑posta Adresine Göre Sorgula (v2)
PURPOSE: E‑posta adreslerinden isimleri çıkar ve gelişmiş ayrıştırma algoritmalarıyla cinsiyeti 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: email
  Type: string
  Required: REQUIRED
  Description: Sorgulanacak e-posta adresi

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 e-posta adresine göre sorgula
Request Body (JSON):
{
    "email": "theresa.miller14@gmail.com"
}

Example 2: E-posta adresi ve ülke koduna göre sorgula
Request Body (JSON):
{
    "email": "thomas.clarks@hotmail.com",
    "country": "US"
}

Example 3: E-posta adresi ve tarayıcı yereli ile sorgula
Request Body (JSON):
{
    "email": "Thomas.j32@live.com",
    "locale": "en_US"
}

Example 4: E-posta adresine göre sorgula ve konumlandırmak için bir IP adresi kullan
Request Body (JSON):
{
    "email": "thomasfromnewyork@gmail.com",
    "ip": "54.201.16.177"
}

Example 5: Birden fazla adı tek bir istekte sorgula
Request Body (JSON):
[
    {
        "email": "thomas.clarks@hotmail.com",
        "country": "US"
    },
    {
        "email": "theresa.miller14@gmail.com"
    }
]

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "email": "theresa.miller14@gmail.com"
    },
    "details": {
        "credits_used": 1,
        "duration": "12ms",
        "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.email_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: email
  Type: string
  Description: Cinsiyetlendirme için kullandığımız e-posta adresi

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 '{"email":"theresa.miller14@gmail.com"}'

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

=== END OF INSTRUCTIONS ===