الاستخدام الأساسي

يتيح لك GenderAPI تحديد جنس الشخص باستخدام أنواع مختلفة من بيانات الإدخال. يمكنك تحليل الأسماء الأولى مباشرة، أو استخراج الأسماء من عناوين البريد الإلكتروني وأسماء المستخدمين. إليك كيفية البدء:

١. تحديد الجنس من الاسم

أرسل الاسم الأول إلى نقطة النهاية التالية: 

https://api.genderapi.io/api

مثال: 

curl "https://api.genderapi.io/api?name=Alice&key=YOUR_API_KEY"

يمكنك أيضاً إضافة معلمات اختيارية:

  • country: إرسال رمز الدولة المكون من حرفين ( ISO 3166-1 alpha-2 ) لتحسين دقة التنبؤ. على سبيل المثال: country=TR لتركيا.
  • askToAI: إذا تم تعيينه على true، ستقوم الـ API بسؤال نموذج الذكاء الاصطناعي لتحديد الجنس إذا لم يُعثر على الاسم في قاعدة البيانات.
  • forceToGenderize: إذا تم تعيينه على true، ستحاول الـ API تخمين الجنس حتى في الإدخالات التي لا تبدو كأسماء بشرية حقيقية مثل الألقاب أو الأسماء الخيالية مثل sparkling unicorn أو mystic warrior. قد يكون هذا مفيداً لتحليل أسماء المستخدمين، ولكن قد تكون النتائج أقل دقة. ملاحظة: هذا المعامل غير متاح في نقطة نهاية البريد الإلكتروني.

مثال باستخدام المعاملات: 

curl "https://api.genderapi.io/api?name=sparkling%20unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

٢. تحديد الجنس من عنوان البريد الإلكتروني

استخدم هذه النقطة النهائية إذا كان لديك عنوان بريد إلكتروني فقط: 

https://api.genderapi.io/api/email

مثال: 

curl "https://api.genderapi.io/api/email?email=alice.smith@example.com&country=TR&askToAI=true&key=YOUR_API_KEY"

ملاحظة: المعامل forceToGenderize غير متاح لنقطة نهاية البريد الإلكتروني لأن هذه النقطة تقوم أولاً باستخراج الاسم داخلياً.


٣. تحديد الجنس من اسم المستخدم

لأسماء المستخدمين أو الألقاب، استخدم: 

https://api.genderapi.io/api/username

مثال: 

curl "https://api.genderapi.io/api/username?username=sparkling_unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

يكون المعامل forceToGenderize مفيدًا بشكل خاص هنا لأن أسماء المستخدمين غالبًا ما تحتوي على كلمات ليست أسماء أو مصطلحات خيالية. حيث يُجبر الـ API على محاولة التنبؤ بالجنس حتى إذا كان الإدخال ليس اسماً بشرياً تقليدياً.

جميع الطرق تدعم الطلبات الفردية أو الجماعية. لمزيد من التفاصيل، راجع الأقسام المحددة في قائمة التنقل اليسرى.


✅ استجابة الـ API

مثال على استجابة JSON لجميع نقاط النهاية: 

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "michael.smith@example.com",
  "name": "Michael",
  "gender": "male",
  "country": "US",
  "total_names": 325,
  "probability": 98,
  "duration": "4ms"
}

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

الحقل النوع الوصف
status Boolean true إذا كانت الطلبية ناجحة. تحقق من الأخطاء إذا كانت false.
used_credits Integer عدد الاعتمادات المستخدمة لهذا الطلب.
remaining_credits Integer الاعتمادات المتبقية في حسابك بعد هذا الطلب.
expires Integer (timestamp) تاريخ انتهاء صلاحية الباقة بصيغة UNIX timestamp (ثواني).
q String الاستعلام المرسل (اسم، بريد إلكتروني أو اسم مستخدم).
name String الاسم الأول المستخرج أو الذي تم العثور عليه.
gender Enum[String] الجنس المتوقع. القيم الممكنة: male أو female أو null.
country Enum[String] رمز الدولة الأكثر احتمالاً (مثل US أو DE).
total_names Integer عدد العينات المستخدمة خلف التنبؤ.
probability Integer نسبة احتمالية تحديد الجنس (مثلاً من 50 إلى 100).
duration String مدة معالجة الطلب (مثلاً 4ms).
تحذير: إذا كانت قيم الإدخال الخاصة بك تحتوي على مسافات أو أحرف خاصة (مثل sparkling unicorn)، تأكد دائماً من ترميزها باستخدام URL-encode قبل إرسال طلبات GET. وإلا فقد يفشل الطلب أو قد تُفسر المعاملات الأخرى بشكل خاطئ بواسطة لغة البرمجة أو مكتبة HTTP التي تستخدمها. 
curl "https://api.genderapi.io/api?name=sparkling unicorn&key=YOUR_API_KEY"
يجب عليك استخدام: 
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&key=YOUR_API_KEY"
أو تطبيق دوال URL-encoding الصحيحة في لغتك البرمجية.