GenderAPI.io V2: استجابات JSON ودرجة الثقة

فهم استجابة JSON

تعيد التقديرات الفردية في GenderAPI.io V2 كائن data للنتيجة وكائن meta لمعلومات الطلب والوصول والخصم. اقرأ data.gender وdata.confidence مع data.confidence_kind وdata.source. مثال مجموعة البيانات التالي استجابة حقيقية جرى الحصول عليها في 1 أكتوبر 2026 باستخدام مفتاح API، ولم يُستبدل فيها سوى رصيد الحساب. وهو لا يمثّل دقة مقيسة للمنتج، وقد يعيد طلب حي نتيجة مختلفة. تُظهر الطلبات التي تستخدم مفتاح API القيمة access.mode: api_key وقيمة null في حقول الحصة الخاصة بالتجربة؛ أما طلبات التجربة حسب عنوان IP فتُظهر ip_trial مع حد التجربة ووقت إعادة التعيين.

{
  "data": {
    "input": {
      "type": "name",
      "value": "محمد",
      "country": "SA"
    },
    "name": "محمد",
    "gender": "male",
    "country": "SA",
    "confidence": 0.9850187265917603,
    "confidence_kind": "observed_frequency",
    "sample_count": 1869,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "محمد",
      "method": "normalized",
      "scope": "country",
      "country": "SA"
    }
  },
  "meta": {
    "request_id": "64092cee-096a-4ae9-abc9-53addc430187",
    "duration_ms": 9,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

• مخططات الاستجابة الكاملة وأمثلة الطلبات المجمّعة

حقول استجابة التقدير

حقول الإدخال المُعادة

حقول المطابقة في مجموعة البيانات

البيانات الوصفية للوصول والخصم والطلب

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

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

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

{
  "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": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
    "duration_ms": 10,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

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

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

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

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

تحديد ما يجب أن يفعله تطبيقك

تعامل أولًا مع أخطاء الطلب وأخطاء العناصر المنفردة، ثم تحقّق من result_status. في التقدير الفردي اقرأ data؛ وفي الطلب المجمّع طبّق القرار نفسه على data في كل عنصر ناجح. احتفظ بالنتائج غير المعروفة في تطبيقك بدلًا من فرض التصنيف male أو female.

• التمييز بين الأخطاء التشغيلية والنتائج غير المعروفة
• تطبيق القرارات على طلب مجمّع

اختيار العتبات بناءً على تقييمك الخاص

لا توجد عتبة عامة لدرجة الثقة تجعل التقدير صحيحًا. قيّم observed_frequency وmodel_reported كلًّا على حدة، باستخدام أمثلة ممثِّلة مصنَّفة بشكل مستقل من حالة الاستخدام الخاصة بك. التكرار في مجموعة البيانات والقيمة التي يقدّمها الذكاء الاصطناعي إشارتان مختلفتان، حتى عندما تكون قيمة كل منهما 0.9. قِس عدد المرات التي تعطي فيها قاعدتك إجابة، وعدد المرات التي تكون فيها هذه الإجابات صحيحة؛ وفي بقية الحالات احتفظ بنتيجة غير معروفة أو خطّط لمراجعة يدوية.

على سبيل المثال، إذا كانت قيمة result_status هي identified وقيمة confidence_kind هي model_reported، فطبّق القاعدة التي قيّمتها للذكاء الاصطناعي، لا عتبة مجموعة البيانات. إذا استُخدم forceToGenderize، فإن name: null مع جنس غير null نتيجة صالحة: إذ يمكن تفسير اسم مستعار دون استخراج اسم أول حقيقي. تحقّق من gender وresult_status، لا من name وحده، لتعرف هل أعطى التقدير إجابة. تظل النتيجة تقديرًا، وليست تأكيدًا لهوية شخص.

• مقاييس التقييم وحدود درجة الثقة
• ملف مجموعة البيانات وحدود الأدلة
• تفسير الأسماء المستعارة وname بقيمة null

أدلة ذات صلة

• استجابة الطلب المجمّع وأخطاء العناصر المنفردة
• حالة الخصم والأرصدة المتبقية
• توافق الاستجابات وإعادة المحاولة