GenderAPI.io V2: البحث بالاسم الأول والاسم الكامل

قبل إرسال الطلب

أرسل طلبات التقدير إلى GenderAPI.io V2 عبر POST https://api.genderapi.io/api/v2/gender، مع type وvalue في جسم JSON. استخدم مفتاح GenderAPI.io الحالي في Authorization: Bearer YOUR_API_KEY مع Content-Type: application/json. اقرأ النتيجة في data، ومعلومات الوصول والخصم في meta. يُعالَج كل طلب بشكل مستقل.

اختر لغة البرمجة في مثال الكود. اضبط GENDERAPI_API_KEY في بيئة العملية قبل تشغيله. قد تستخدم المفاتيح المفقودة أو غير المعروفة التجربة المشتركة حسب عنوان IP، لذا تأكد عند ربط حساب من أن قيمة meta.access.mode هي api_key.

الجنس من الاسم

المعامل	النوع	مطلوب	القيمة الافتراضية	الوصف
`type`	`string`	نعم	`—`	فئة الإدخال: name أو email أو username.
`value`	`string`	نعم	`—`	مطلوب. 1–254 حرفًا؛ غير فارغ ودون أحرف تحكم. يجب أن تكون قيم email بصيغة بريد إلكتروني صالحة.
`country`	`string`	لا	`—`	رمز ISO 3166-1 alpha-2 اختياري بأحرف كبيرة، مثل TR أو US. قد يرجع البحث الخاص بدولة إلى مجموعة البيانات العامة.
`forceToGenderize`	`boolean`	لا	`false`	ابحث في مجموعة البيانات أولًا، ثم استخدم الذكاء الاصطناعي الذي يفسّر الأسماء المستعارة إذا لم توجد نتيجة. مدعوم لـ name وemail وusername.
`options`	`object`	لا	`—`	كائن يضم خيارات الذكاء الاصطناعي لكل مُدخل.
`options.ai_mode`	`string`	لا	`fallback`	القيم المسموح بها: off وfallback وalways. مع forceToGenderize: true، احذف هذا الحقل أو استخدم fallback.
`id`	`string`	لا	`—`	معرّف اختياري من 1–64 حرفًا في JSON لطلبات POST. يُعاد بجوار نتيجة العنصر في الطلب المجمّع، ويجب أن يكون فريدًا داخل الطلب المجمّع. يُقبل في التقديرات الفردية لكنه لا يُعاد في الاستجابة. غير مدعوم في استعلامات GET.

لاسم أول أو اسم كامل، أرسل type: name والمُدخل كاملًا في value إلى POST https://api.genderapi.io/api/v2/gender. يستخدم GenderAPI.io V2 حقول الطلب نفسها للصيغتين. قد تحتوي الاستجابة الناجحة أيضًا على data.gender: null. تبحث الطلبات الفردية في مجموعة البيانات أولًا، وتستخدم افتراضيًا الذكاء الاصطناعي عندما يتعذّر تحديد الجنس منها.

اختر لغة البرمجة. إعداد مفتاح API، ثم شغّل المثال على خادمك.

كل طلب تقدير عملية جديدة مدفوعة، حتى عند إعادة المحاولة. لا تعيد هذه الأمثلة المحاولة تلقائيًا. تحقّق من حالة الخصم قبل إرسال طلب آخر.

قبل التشغيل: الوصول ومعالجة الأخطاء

شغّل هذه الأمثلة على خادمك. اضبط GENDERAPI_API_KEY في بيئة العملية على مفتاح API الحالي. تأكد من أن قيمة meta.access.mode هي api_key: فالمفتاح غير المعروف قد يؤدي إلى استخدام التجربة حسب عنوان IP.

في استجابات JSON ذات رموز HTTP 4xx و5xx، يُحتفظ بجسم الخطأ وينتهي المثال برمز خروج غير صفري. تحقّق من code وaction وmeta.usage.billing_status قبل إعادة المحاولة.

دليل الأخطاء وإعادة المحاولة ←

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "محمد",
  "country": "SA"
}'

cURL 7.76+ في واجهة أوامر POSIX. شغّله في الطرفية. وثائق بيئة التشغيل

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "name",
  "value": "محمد",
  "country": "SA"
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+ مع fetch المدمج. احفظه باسم example.mjs وشغّل node example.mjs. وثائق بيئة التشغيل

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"name\",\"value\":\"محمد\",\"country\":\"SA\"}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+ مع المكتبة القياسية. احفظه باسم example.py وشغّل python3 example.py. وثائق بيئة التشغيل

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"محمد","country":"SA"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+ مع امتداد cURL. احفظه باسم example.php وشغّل php example.php. وثائق بيئة التشغيل

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"name\",\"value\":\"محمد\",\"country\":\"SA\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+ مع عميل HTTP القياسي. احفظه باسم GenderApiExample.java وشغّل java GenderApiExample.java. وثائق بيئة التشغيل

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"محمد\",\"country\":\"SA\"}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

تطبيق وحدة تحكم (console) على .NET 8+. استخدمه كملف Program.cs في مشروع console، ثم شغّل dotnet run. وثائق بيئة التشغيل

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"name\",\"value\":\"محمد\",\"country\":\"SA\"}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+ مع المكتبة القياسية. احفظه باسم main.go وشغّل go run main.go. وثائق بيئة التشغيل

مثال على الاستجابة

هذه استجابة حقيقية جرى الحصول عليها في 1 أكتوبر 2026 باستخدام مفتاح API، ولم يُستبدل فيها سوى رصيد الحساب. وهي ليست مقياسًا للدقة، وقد يعيد طلب حي نتيجة مختلفة. تُظهر الطلبات التي تستخدم مفتاح API القيمة meta.access.mode: api_key وقيمة null في حقول الحصة الخاصة بالتجربة؛ أما طلبات التجربة حسب عنوان IP فتُظهر ip_trial. اقرأ data للتقدير، وmeta.usage لنتيجة خصم العملية.

{
  "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
    }
  }
}

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

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

الحقل	النوع	يمكن أن يكون null	مثال	الوصف
`data.input`	`object`	لا	`{"type":"name","value":"محمد","country":"SA"}`	نوع الإدخال والقيمة والدولة. يُضمَّن forceToGenderize عندما تكون قيمته true.
`data.name`	`string`	نعم	`"محمد"`	الاسم الأول المطابق أو المستخرج؛ وnull إذا لم يتوفر.
`data.gender`	`string`	نعم	`"male"`	male أو female أو JSON null. تقدير، وليس هوية شخصية موثَّقة.
`data.result_status`	`string`	لا	`"identified"`	identified عند إعادة جنس؛ وإلا unknown.
`data.reason`	`string`	نعم	`null`	null للنتائج identified. أسباب unknown: not_found أو no_name_candidate أو ambiguous أو insufficient_evidence.
`data.confidence`	`number`	نعم	`0.95`	قيمة من 0 إلى 1 أو null. إذا كان gender هو null، فدرجة الثقة null أيضًا.
`data.confidence_kind`	`string`	نعم	`"observed_frequency"`	observed_frequency: العدد الغالب في مجموعة البيانات مقسومًا على الإجمالي. model_reported: قيمة يقدّمها الذكاء الاصطناعي، وليست احتمالًا معايرًا. null إذا لم تتوفر.
`data.sample_count`	`integer`	نعم	`1200`	حجم العينة في مجموعة البيانات أو null. لا يختلق الذكاء الاصطناعي عددًا للعينات.
`data.source`	`string`	لا	`"dataset"`	dataset أو ai أو none.
`data.country`	`string`	نعم	`"SA"`	ارتباط بدولة مصدره dataset أو ai_association، أو null. لا يحدد الجنسية أو مكان الإقامة أو الأصل العرقي.
`data.country_source`	`string`	نعم	`"dataset"`	مصدر الارتباط بالدولة: dataset أو ai_association أو null.
`data.match`	`object`	لا	`{"name":"محمد","method":"normalized","scope":"country","country":"SA"}`	الاسم المطابق في مجموعة البيانات، والطريقة (normalized أو token أو substring أو model_inference)، والنطاق country أو global، والدولة المطابقة. الأدلة غير المتوفرة قيمتها null.

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

الحقل	النوع	يمكن أن يكون null	مثال	الوصف
`meta.request_id`	`string`	لا	`"550e8400-e29b-41d4-a716-446655440000"`	معرّف فريد لمحاولة HTTP هذه؛ ويُرسل أيضًا في X-Request-ID.
`meta.duration_ms`	`integer`	لا	`42`	مدة معالجة الطلب بالمللي ثانية.
`meta.access.mode`	`string`	لا	`"api_key"`	api_key أو ip_trial أو unauthenticated. عند استخدام حساب مدفوع، تحقّق من ظهور api_key.
`meta.access.reason`	`string`	نعم	`null`	سبب الانتقال إلى التجربة حسب عنوان IP: api_key_missing أو api_key_invalid أو api_key_not_found؛ وإلا null.
`meta.usage.charged_credits`	`integer`	نعم	`1`	صافي الأرصدة المخصومة. صفر قبل الخصم أو بعد استرداد كامل مؤكد؛ وnull إذا لم يُؤكَّد الخصم.
`meta.usage.remaining_credits`	`integer`	نعم	`99`	الرصيد عند اكتمال العملية. قد يكون سالبًا؛ وnull إذا لم يتوفر أو لم يُؤكَّد الخصم.
`meta.usage.billing_status`	`string`	لا	`"confirmed"`	not_charged أو confirmed أو unconfirmed. تحقّق منه قبل إعادة محاولة تقدير فاشل.
`meta.usage.resets_at`	`string`	نعم	`"2026-09-27T12:00:00.000Z"`	موعد تجديد التجربة حسب عنوان IP بتوقيت UTC (ISO 8601)؛ وnull لحسابات مفاتيح API أو إذا كان غير معروف.
`meta.usage.limit`	`integer`	نعم	`10`	حصة التجربة حسب عنوان IP؛ وnull لحسابات مفاتيح API.
`meta.usage.period_seconds`	`integer`	نعم	`86400`	مدة فترة التجربة حسب عنوان IP بالثواني؛ وnull لحسابات مفاتيح API.

سياق الدولة والأسماء غير المعروفة

أرسل country فقط عندما يتوفر لديك سياق ذو صلة. قد تختار API صفًا خاصًا بالدولة من مجموعة البيانات أو ترجع إلى صف عام. يبيّن data.match.scope أيهما اختير؛ ولا تحدد الدولة المُعادة مكان إقامة الشخص.

تستخدم الطلبات الفردية افتراضيًا الرجوع إلى الذكاء الاصطناعي بتكلفة إجمالية قدرها رصيد واحد. لاستخدام مجموعة البيانات فقط، أرسل options: {"ai_mode": "off"}. قد تعيد المُدخلات التي لم تُحسم gender: null، وتُخصم أرصدتها مع ذلك إذا نجحت العملية. قد يطابق الاسم الكامل أحد أجزائه؛ ويسجّل data.match المرشح المختار وطريقة المطابقة.

لقيم name التي تشبه الأسماء المستعارة، يسمح forceToGenderize: true بالتقدير دون اسم أول حقيقي: تكلفة النتيجة الموجودة في مجموعة البيانات رصيد واحد، وإلا فتكلفة الذكاء الاصطناعي الذي يفسّر الأسماء المستعارة رصيدان إجمالًا. يكفي أن يكون الرصيد الابتدائي موجبًا، وقد يصبح الرصيد الناتج سالبًا.

البحث عن اسم كامل دون افتراض أن الكلمة الأولى هي المعتمدة

أرسل الاسم الأصلي بترميز Unicode. تستخدم المطابقة مع مجموعة البيانات تطبيع NFKC والأحرف الصغيرة واستخراج أجزاء الاسم؛ ولا حاجة إلى تحويل الاسم إلى ASCII. من بين المرشحين المتاحين، تختار API سجل مجموعة البيانات صاحب أعلى عدد إجمالي مخزَّن. قد يكون المرشح جزءًا لاحقًا من الاسم، لذا لا تفترض أن الكلمة الأولى أو الاسم الأول هو ما اختير.

يستخدم هذا الطلب مجموعة البيانات فقط، مما يسهّل التحقق من الأدلة المختارة. اقرأ data.input.value للاسم الكامل المُرسل، وdata.match.name للمرشح الذي بُحث عنه، وdata.match.method لطريقة المطابقة. لا يعد المثال بجنس محدد ولا بجزء معيّن من الاسم يُختار. يجب أن يزيد طول مرشحي مجموعة البيانات على حرفين، وقد تبقى المُدخلات القصيرة دون نتيجة. استخدم الرجوع العادي إلى الذكاء الاصطناعي عندما يكون التقدير الإضافي مناسبًا لتطبيقك.