توثيق API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: الاستعلام بعنوان البريد الإلكتروني (v2)
PURPOSE: استخراج الأسماء من عناوين البريد الإلكتروني وتحديد الجنس باستخدام خوارزميات تحليل متقدمة.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <رمز التخويل الخاص بك> 
link

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: عنوان البريد الإلكتروني المراد الاستعلام عنه

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: رمز الدولة الأبجدي Alpha-2 ISO 3166 link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: لغة المتصفح

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: عنوان IP صالح (IPv4 أو IPv6)

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: بحد أقصى 50 حرفًا. يمكنك تعيين هذا المعرّف لأي قيمة أبجدية رقمية تريدها.
 كمثال، يمكنك تعيين المعرّف لمعرّفك الداخلي لمجموعة البيانات في قاعدة بياناتك. في بيئة غير متزامنة 
 يمكن أن يساعدك هذا في ربط الاستجابة بطلب سابق بشكل أفضل

--- REQUEST EXAMPLES ---

Example 1: الاستعلام عن طريق عنوان البريد الإلكتروني فقط
Request Body (JSON):
{
    "email": "theresa.miller14@gmail.com"
}

Example 2: الاستعلام عن طريق عنوان البريد الإلكتروني ورمز البلد
Request Body (JSON):
{
    "email": "thomas.clarks@hotmail.com",
    "country": "US"
}

Example 3: الاستعلام بعنوان البريد الإلكتروني ولغة المتصفح
Request Body (JSON):
{
    "email": "Thomas.j32@live.com",
    "locale": "en_US"
}

Example 4: الاستعلام بعنوان البريد الإلكتروني واستخدام عنوان IP للتوطين
Request Body (JSON):
{
    "email": "thomasfromnewyork@gmail.com",
    "ip": "54.201.16.177"
}

Example 5: الاستعلام عن أسماء متعددة في طلب واحد
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: الحمولة المرسلة

Field: details.credits_used
  Type: int
  Description: عدد الطلبات المستخدمة لهذا الاستعلام

Field: details.samples
  Type: int
  Description: عدد السجلات الموجودة في قاعدة بياناتنا والمطابقة لطلبك

Field: details.country
  Type: string
  Description: البلد الذي وجدناه

Field: details.email_sanitized
  Type: int
  Description: الاسم بعد تطبيق أداة التطبيع الخاصة بنا عليه

Field: details.duration
  Type: string
  Description: الوقت الذي احتاجه الخادم لمعالجة الطلب

Field: result_found
  Type: bool
  Description: تكون true إذا تمكّنا من تحديد جنس الاسم المُعطى

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

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

=== END OF INSTRUCTIONS ===