تحديد الجنس من الاسم API | توثيق الطلب الواحد

نظرة عامة على الطلب

أرسل اسماً واحداً في كل طلب

أرسل كائن JSON يحتوي على الاسم الأول، ووثّق الطلب باستخدام Bearer token. أضف رمز الدولة عندما تساعد أنماط التسمية الإقليمية على تحسين التوقع.

الطريقةPOST

نوع المحتوىapplication/json

المصادقةBearer token

تكلفة الرصيدعملية بحث واحدة

HDR

ترويسات HTTP المطلوبة

وثّق الطلب

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

احتفظ بمفتاح API داخل متغيرات البيئة على الخادم. راجع دليل المصادقة لحماية بيانات الاعتماد.

جسم طلب JSON

المعاملات

المعامل	النوع	الحالة	الوصف
`name`	string	مطلوب	الاسم الأول المراد تحليله. استخدم اسماً واضحاً من دون ألقاب أو بادئات.
`country`	string	اختياري	رمز الدولة ISO 3166-1 alpha-2، مثل US أو TR، لإضافة سياق إقليمي.
`askToAI`	boolean	اختياري	عند ضبطه على true، يُستخدم دعم الذكاء الاصطناعي إذا لم يوجد الاسم في قاعدة البيانات.
`forceToGenderize`	boolean	اختياري	عند ضبطه على true، يحاول إرجاع نتيجة للألقاب أو المدخلات التي لا تبدو كأسماء معتادة.

حول دعم الذكاء الاصطناعي

askToAI يعمل فقط عندما لا تعثر قاعدة البيانات على نتيجة. قد تكون التوقعات القسرية للمدخلات غير المعتادة أقل موثوقية، لذلك تعامل مع probability كمؤشر مهم.

أمثلة الكود

نفّذ طلباً واحداً

ترسل الأمثلة التالية الطلب نفسه باستخدام Bearer authentication.

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Alice","country":"US","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "US", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "US", "askToAI": True}
)
print(response.json())

استجابة 200

نتيجة التوقع

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "US",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

حقول الاستجابة

الحقل	النوع	الوصف
`status`	boolean	يوضح ما إذا اكتمل الطلب بنجاح.
`used_credits`	integer	عدد الأرصدة المستهلكة في هذا الطلب.
`remaining_credits`	integer	عدد الأرصدة المتبقية بعد الطلب.
`expires`	integer	وقت انتهاء الباقة بصيغة UNIX timestamp.
`q`	string	الاسم الأصلي المرسل في الطلب.
`name`	string	الاسم الذي حللته GenderAPI.
`gender`	string \| null	القيمة المتوقعة: male أو female أو null.
`country`	string	رمز الدولة المستخدم في التوقع.
`total_names`	integer	عدد العينات الداعمة للتوقع.
`probability`	integer	درجة الثقة في التوقع كنسبة مئوية.
`duration`	string	مدة المعالجة على الخادم.

أرسل مدخلاً واضحاً ومشفّراً بصورة صحيحة

استخدم اسماً أول من دون ألقاب أو بادئات. تتولى مكتبات JSON الترميز تلقائياً، لكن تحقّق دائماً من المدخلات الخارجية قبل إنشاء جسم الطلب.

الدليل التالي

حلّل عدة أسماء

طلب أسماء متعددةعالج عدة أسماء في طلب واحد ←المصادقةراجع أمان مفتاح API ←