توثيق API

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