توثيق API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: الاستعلام بالاسم الأول (الإصدار الثاني)
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: first_name
  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 حرفًا. يمكنك تعيين هذا المعرّف لأي قيمة أبجدية رقمية تريدها.\r\n            كمثال، يمكنك تعيين المعرّف لمعرّفك الداخلي لمجموعة البيانات في قاعدة بياناتك. في بيئة غير متزامنة \r\n            يمكن أن يساعدك هذا في ربط الاستجابة بطلب سابق بشكل أفضل

--- REQUEST EXAMPLES ---

Example 1: الاستعلام بالاسم الأول فقط
Request Body (JSON):
{
    "first_name": "Sandra"
}

Example 2: الاستعلام بالاسم الأول ورمز البلد
Request Body (JSON):
{
    "first_name": "Sandra",
    "country": "US"
}

Example 3: الاستعلام بالاسم الأول وموقع المتصفح
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: الاستعلام بالاسم الأول واستخدام عنوان IP لتحديد الموقع
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

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

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

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

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

Field: details.first_name_sanitized
  Type: string
  Description: الاسم بعد تطبيقنا المُطبع عليه

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

Field: result_found
  Type: bool
  Description: صحيح إذا تمكنا من الاستعلام عن جنس للاسم المحدد

Field: first_name
  Type: string
  Description: الاسم الأول الذي استخدمناه لتحديد الجنس

Field: probability
  Type: float
  Description: تحدد هذه القيمة (بين 0 و1) موثوقية قاعدة بياناتنا. تشير القيمة 1 إلى أن النتائج في طلب الجنس الخاص بك دقيقة بنسبة 100٪.

Field: gender
  Type: string
  Description: القيم الممكنة: ذكر، أنثى، غير معروف

--- 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 '{"first_name":"Sandra"}'

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

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: استعلام بالاسم الكامل (الإصدار الثاني)
PURPOSE: قسّم الأسماء الكاملة تلقائيًا وحدد الجنس في مكالمة 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: رمز الدولة الأبجدي 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 حرفًا. يمكنك تعيين هذا المعرّف لأي قيمة أبجدية رقمية تريدها.\r\n            كمثال، يمكنك تعيين المعرّف لمعرّفك الداخلي لمجموعة البيانات في قاعدة بياناتك. في بيئة غير متزامنة \r\n            يمكن أن يساعدك هذا في ربط الاستجابة بطلب سابق بشكل أفضل

--- 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: القيم الممكنة: ذكر، أنثى، غير معروف

--- 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 ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: الاستعلام عن طريق عنوان البريد الإلكتروني (الإصدار 2)
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 حرفًا. يمكنك تعيين هذا المعرّف لأي قيمة أبجدية رقمية تريدها.\r\n            كمثال، يمكنك تعيين المعرّف لمعرّفك الداخلي لمجموعة البيانات في قاعدة بياناتك. في بيئة غير متزامنة \r\n            يمكن أن يساعدك هذا في ربط الاستجابة بطلب سابق بشكل أفضل

--- 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: صحيح إذا تمكنا من الاستعلام عن جنس للاسم المحدد

Field: email
  Type: string
  Description: عنوان البريد الإلكتروني الذي استخدمناه لتحديد الجنس

Field: probability
  Type: float
  Description: تحدد هذه القيمة (بين 0 و1) موثوقية قاعدة بياناتنا. تشير القيمة 1 إلى أن النتائج في طلب الجنس الخاص بك دقيقة بنسبة 100٪.

Field: gender
  Type: string
  Description: القيم الممكنة: ذكر، أنثى، غير معروف

--- 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 ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: الحصول على بلد المنشأ (الإصدار 2)
PURPOSE: اكتشف بلد المنشأ والخلفية العرقية المحتملة بناءً على الأسماء.

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

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

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: الاسم الأول المراد الاستعلام عنه

Parameter: full_name
  Type: string
  Required: OPTIONAL
  Description: الاسم الكامل للاستعلام عنه. يمكن تقديمه بدلاً من حقل الاسم الأول

Parameter: email
  Type: string
  Required: OPTIONAL
  Description: عنوان البريد الإلكتروني للاستعلام. يمكن توفيره بدلاً من حقل first_name

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

--- REQUEST EXAMPLES ---

Example 1: الاستعلام بالاسم الأول
Request Body (JSON):
{
    "first_name": "Johann"
}

Example 2: ابحث بالاسم الكامل
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 3: الاستعلام عن طريق عنوان البريد الإلكتروني
Request Body (JSON):
{
    "full_name": "sophia5342@gmail.com"
}

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "first_name": "Johann",
        "id": 12
    },
    "details": {
        "credits_used": 2,
        "duration": "414ms",
        "samples": 890,
        "country": null,
        "first_name_sanitized": "johann"
    },
    "result_found": true,
    "country_of_origin": [
        {
            "country_name": "Germany",
            "country": "DE",
            "probability": 0.52,
            "continental_region": "Europe",
            "statistical_region": "Western Europe"
        },
        {
            "country_name": "Austria",
            "country": "AT",
            "probability": 0.48,
            "continental_region": "Europe",
            "statistical_region": "Western Europe"
        }
    ],
    "first_name": "Johann",
    "probability": 0.9,
    "gender": "male",
    "language_of_origin": "Germanic",
    "meaning": "Johann is the German variation of the name John, which means 'God is gracious'. It was frequently used in the Middle Ages across Europe, particularly as a name for religious figures.",
    "ethnicity": {
        "id": "GERMANIC",
        "name": "Germanic (German, Austrian, Swiss)",
        "distribution": [
            {
                "id": "GERMANIC",
                "name": "Germanic (German, Austrian, Swiss)",
                "percentage": 90
            },
            {
                "id": "DUTCH",
                "name": "Dutch",
                "percentage": 5
            },
            {
                "id": "FRENCH",
                "name": "French",
                "percentage": 5
            }
        ]
    }
 }

--- 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.first_name_sanitized
  Type: string
  Description: الاسم بعد تطبيقنا المُطبع عليه

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

Field: result_found
  Type: bool
  Description: صحيح إذا تمكنا من الاستعلام عن جنس للاسم المحدد

Field: country_of_origin_map_url
  Type: string
  Description: عنوان URL لخريطة تفاعلية حول هذا الاسم

Field: first_name
  Type: string
  Description: الاسم الأول الذي استخدمناه لتحديد الجنس

Field: probability
  Type: float
  Description: تحدد هذه القيمة (بين 0 و 1) موثوقية قاعدة بياناتنا. تعني القيمة 1 أن نتائج طلب الجنس الخاص بك دقيقة بنسبة 100٪

Field: gender
  Type: string
  Description: القيم الممكنة: ذكر، أنثى، غير معروف

Field: country_of_origin
  Type: object
  Description: أفضل 25 دولة منشأ. انظر "قائمة كاملة بالدول الممكنة" للحصول على قائمة بالدول المدعومة. يحتوي كل سجل على الحقول country_name و country و probability و continental_region و statistical_region

Field: language_of_origin
  Type: string
  Description: لغة أصل هذا الاسم

Field: meaning
  Type: string
  Description: وصف قصير لمعنى هذا الاسم

Field: ethnicity
  Type: object
  Description: يوفر حقل العرق تفاصيل حول المجموعة العرقية الرئيسية المرتبطة بالاسم، وكيف يتم توزيع الاسم عبر المجموعات العرقية المختلفة

Field: ethnicity.id
  Type: string
  Description: حقل التعريف يحتوي على مُعرّف للمجموعة العرقية الرئيسية المحددة. راجع "Complete List Of Possible Ethnic Groups" للحصول على القائمة الكاملة للمجموعات العرقية المحتملة

Field: ethnicity.name
  Type: string
  Description: يحتوي حقل الاسم على اسم المجموعة العرقية الرئيسية المحددة. انظر "قائمة كاملة بالمجموعات العرقية الممكنة" للحصول على القائمة الكاملة للمجموعات العرقية الممكنة

Field: ethnicity.distribution
  Type: array
  Description: حقل التوزيع يحتوي على معلومات حول نسبة الاسم داخل مجموعات عرقية مختلفة. كل إدخال في المصفوفة يحتوي على الحقول id (نص)، name (نص) ونسبة (عدد عشري). انظر "Complete List Of Possible Ethnic Groups" للحصول على القائمة الكاملة للقيم المحتملة

--- 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/country-of-origin' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <رمز التخويل الخاص بك> link' \
  -d '{"first_name":"Johann"}'

--- CREDIT USAGE ---
Required Requests: 2

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: الحصول على الإحصائيات (الإصدار الثاني)
PURPOSE: استرجع إحصائيات الاستخدام المفصلة وأرصدة الطلبات المتبقية لحسابك.

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

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

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "is_limit_reached": false,
    "remaining_credits": 24999,
    "details": {
        "credits_used": 0,
        "duration": "83ms"
    },
    "usage_last_month": {
        "date": "2018-03",
        "credits_used": 25
    }
}

--- RESPONSE FIELDS ---

Field: is_limit_reached
  Type: bool
  Description: إرجاع صحيح إذا لم يتبق طلبات أخرى

Field: remaining_credits
  Type: int
  Description: عدد الطلبات المتبقية

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

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

Field: usage_last_month.date
  Type: string
  Description: تاريخ الشهر الماضي

Field: usage_last_month.credits_used
  Type: int
  Description: الطلبات التي استخدمتها خلال الشهر الماضي

--- 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 GET \
  'https://gender-api.com/v2/statistic' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <رمز التخويل الخاص بك> link' \

=== END OF INSTRUCTIONS ===