# استجابات API v2 JSON والثقة

> فهم بيانات GenderAPI v2 وحقول التعريف: الجنس، والأسباب غير المعروفة، والثقة، وأدلة مجموعة البيانات، ونتائج الذكاء الاصطناعي، ووضع الوصول، والبيانات الوصفية للفوترة.

Canonical HTML: https://www.genderapi.io/ar/docs/v2/responses

Last reviewed: 2026-09-25

## فهم استجابة JSON

تحتوي الاستجابات الفردية الناجحة على data وmeta. إن استجابة مجموعة البيانات أدناه هي مثال توضيحي، وليست قياسًا لدقة المنتج أو وعدًا بنفس النتيجة المباشرة. ويظهر الوصول إلى IP التجريبي. الطلبات التي تمت مصادقتها باستخدام مفتاح الحساب ترجع access.mode: api_key؛ الحقول التي تنطبق على النسخة التجريبية فقط لها القيمة null.

| الميدان [[م162]] المعنى | معنى |
| --- | --- |
| data.input | نوع الإدخال والقيمة والبلد. يتم تضمين forceToGenderize عند true. |
| data.name | الاسم المطابق أو المستخرج؛ null عند عدم توفر أي شيء. |
| data.gender | male أو female أو JSON null. هذا توقع وليس دليلاً على هوية الشخص. |
| data.result_status / reason | عندما يكون result_status هو identified، فإن reason هو null. عندما تكون الحالة unknown، يكون السبب هو not_found أو no_name_candidate أو ambiguous أو insufficient_evidence. |
| data.confidence | 0–1 النتيجة أو null. الجنس الفارغ لديه ثقة null. |
| data.confidence_kind | observed_frequency: عدد الجنس السائد مقسومًا على العدد الإجمالي في مجموعة البيانات المحددة. model_reported: درجة الذكاء الاصطناعي، وليست احتمالية معايرة. القيمة هي null عندما لا تكون متاحة. |
| data.sample_count | حجم عينة مجموعة البيانات أو null. الذكاء الاصطناعي لا يخترع عدد العينات. |
| data.source | dataset أو ai أو none. |
| data.country / country_source | ارتباط الدولة من مجموعة البيانات أو ai_association أو null. لا يحدد الجنسية أو الإقامة أو العرق. |
| data.match | الاسم المطابق في مجموعة البيانات، وطريقة المطابقة (normalized أو token أو substring أو model_inference)، والنطاق (country أو global)، والبلد المطابق. تكون المعلومات غير المتاحة null. |
| meta.request_id / duration_ms | معرف العملية ومدة المعالجة بالمللي ثانية. |
| meta.access | كيفية منح حق الوصول وسبب التراجع عن المحاكمة إن وجد. |
| meta.usage | صافي الرسوم ورصيد وقت الإكمال وحالة الفوترة ومعلومات إعادة تعيين النسخة التجريبية. |

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [أكمل مخططات الاستجابة وأمثلة الدفعات](https://api.genderapi.io/api/v2/openapi.json)

## نتيجة ناجحة غير معروفة

HTTP 200 يعني أن العملية قد اكتملت؛ لا يضمن الجنس. احتفظ بـ JSON null بدلاً من تحويلها إلى male أو female أو سلسلة فارغة أو ثقة معدومة. تحقق من data.result_status وdata.reason بشكل منفصل عن أخطاء HTTP.

يُرجع هذا المثال لمجموعة البيانات فقط source: none وreason: not_found ولا يزال يتكلف رصيدًا واحدًا. إذا كانت أعداد مجموعة البيانات للجنسين متساوية، فيمكن أن تحتوي النتيجة على reason: ambiguous مع الحفاظ على sample_count. تستخدم نتيجة الذكاء الاصطناعي غير المعروفة source: ai وreason: insufficient_evidence.

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "zzzxxyy",
      "country": null
    },
    "name": null,
    "gender": null,
    "country": null,
    "confidence": null,
    "confidence_kind": null,
    "sample_count": null,
    "source": "none",
    "result_status": "unknown",
    "reason": "not_found",
    "country_source": null,
    "match": {
      "name": null,
      "method": null,
      "scope": null,
      "country": null
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 8,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

## تفسير الثقة ومطابقة الأدلة

الثقة البالغة 0.9 تقع على مقياس من 0 إلى 1. بالنسبة إلى observed_frequency، فهذا يعني العدد السائد مقسومًا على إجمالي مجموعة البيانات المحددة؛ لا يتم قياس دقة المنتج من البداية إلى النهاية. يتم توفير درجة model_reported بواسطة الذكاء الاصطناعي ولا تتم معايرتها مقابل ترددات مجموعة البيانات.

اختر أي حد للتطبيق باستخدام بيانات التقييم الخاصة بك وconfidence_kind. لا تقم بترتيب مجموعة البيانات ونتائج الذكاء الاصطناعي بشكل مباشر كما لو أنها تقيس نفس الشيء. AI match.name وmatch.scope وmatch.country هي null لأنه لم يتم تحديد صف مجموعة بيانات؛ match.method هو model_inference.

بالنسبة للأسماء الكاملة، قد تأتي نتيجة مجموعة البيانات من مكون بدلاً من السلسلة الكاملة. يحتفظ data.input بالقيمة المقدمة؛ يصف data.name الاسم الذي تم إرجاعه، ويصف data.match المرشح ونطاق البحث.

## أدلة ذات صلة

- [الاستجابة المجمعة والأخطاء لكل عنصر](https://www.genderapi.io/ar/docs/v2/batch#batch-response)
- [حالة الفواتير والأرصدة المتبقية](https://www.genderapi.io/ar/docs/v2/credits-and-usage)
- [توافق الاستجابة وإعادة المحاولة](https://www.genderapi.io/ar/docs/v2/errors-and-retries#retries)