जारी रखें → अवलोकन

REST API संदर्भ

चार endpoint, एक प्रतिक्रिया रूप। नीचे सब कुछ आपके खाते के विरुद्ध लाइव है।

त्वरित शुरुआत

अपने डैशबोर्ड में एक key बनाएं, फिर अपना पहला अनुरोध भेजें। SDK की आवश्यकता नहीं है।

curl "https://namegender.com/api?name=Ay%C5%9Fe&country=TR" \
  -H "Authorization: Bearer YOUR_API_KEY"
<?php

$query = http_build_query(['name' => 'Ayşe', 'country' => 'TR']);

$ch = curl_init('https://namegender.com/api?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_API_KEY'],
]);

$result = json_decode(curl_exec($ch), true);

echo $result['gender'];       // female
echo $result['probability'];  // 100
const params = new URLSearchParams({ name: 'Ayşe', country: 'TR' });

const response = await fetch(`https://namegender.com/api?${params}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});

const result = await response.json();

console.log(result.gender);       // "female"
console.log(result.probability);  // 100
import requests

response = requests.get(
    "https://namegender.com/api",
    params={"name": "Ayşe", "country": "TR"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

result = response.json()
print(result["gender"])       # female
print(result["probability"])  # 100
require "net/http"
require "json"

uri = URI("https://namegender.com/api")
uri.query = URI.encode_www_form(name: "Ayşe", country: "TR")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)["gender"]   # female
req, _ := http.NewRequest("GET", "https://namegender.com/api?name=Ay%C5%9Fe&country=TR", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result struct {
    Gender      string `json:"gender"`
    Probability int    `json:"probability"`
}
json.NewDecoder(resp.Body).Decode(&result)

fmt.Println(result.Gender)   // female

प्रत्येक endpoint एक ही रूप लौटाता है, इसलिए आप अपने पार्सिंग कोड को बदले बिना input स्विच कर सकते हैं।

प्रमाणीकरण

अपनी API key को तीन तरीकों में से किसी भी तरीके से भेजें। Authorization header की सिफारिश की जाती है: query string सर्वर लॉग और ब्राउज़र history में समाप्त हो जाते हैं।

Authorization header (अनुशंसित)
Authorization: Bearer ng_live_xxxxxxxxxxxx
कस्टम header
X-Api-Key: ng_live_xxxxxxxxxxxx
Query पैरामीटर
https://namegender.com/api?name=Ayşe&key=ng_live_xxxxxxxxxxxx
अपनी key को कभी भी क्लाइंट-साइड कोड में expose न करें। ब्राउज़र या मोबाइल ऐप से कॉल आपके अपने backend के माध्यम से जाना चाहिए।

आप डैशबोर्ड से key को विशिष्ट IP पतों तक सीमित कर सकते हैं।

क्लाइंट लाइब्रेरी

एक API, चार इनपुट प्रकार, और बल्क टूल जो वह फाइलें संभालते हैं जहां अन्य सेवाएं विफल होती हैं।

सभी देखें
GET · POST https://namegender.com/api

नाम से लिंग

पहले नाम या पूरे नाम को स्वीकार करता है। खिताब, middle name और surname को lookup से पहले हटा दिया जाता है, इसलिए "Dr. Ayşe Yılmaz" और "Ayşe" एक ही उत्तर देते हैं।

पैरामीटर प्रकार विवरण
name
आवश्यक
string वर्गीकृत करने के लिए नाम। पहला नाम या पूरा नाम।
country
वैकल्पिक
string ISO 3166-1 alpha-2 country code। उन नामों के लिए सटीकता में सुधार करता है जिनका लिंग क्षेत्र के अनुसार अलग-अलग होता है, जैसे Andrea (इटली में male, जर्मनी में female)।
askToAI
वैकल्पिक
boolean जब नाम database में न हो तो language model पर fallback करें। एक अतिरिक्त credit खर्च होता है।
forceToGenderize
वैकल्पिक
boolean सबसे संभावित लिंग लौटाएं भले ही confidence threshold से नीचे हो। डिफ़ॉल्ट रूप से बंद है, क्योंकि एक coin-flip उत्तर को निश्चित के रूप में प्रस्तुत करना कोई उत्तर न देने से बदतर है।
curl "https://namegender.com/api?name=Jordan" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 49999,
  "expires": null,
  "q": "Jordan",
  "name": "Jordan",
  "gender": "male",
  "country": null,
  "total_names": 62240,
  "probability": 84,
  "confidence": "high",
  "duration": "1ms",
  "source": "db",
  "matched_as": null
}
GET · POST https://namegender.com/api/email

ईमेल से लिंग

पते के local part से व्यक्ति को निकालता है, फिर वर्गीकृत करता है। "ayse.yilmaz84@example.com" Ayşe को resolve करता है।

पैरामीटर प्रकार विवरण
email
आवश्यक
string ईमेल पता। केवल @ से पहले का भाग उपयोग किया जाता है।
country
वैकल्पिक
string ISO 3166-1 alpha-2 country code। उन नामों के लिए सटीकता में सुधार करता है जिनका लिंग क्षेत्र के अनुसार अलग-अलग होता है, जैसे Andrea (इटली में male, जर्मनी में female)।
askToAI
वैकल्पिक
boolean जब नाम database में न हो तो language model पर fallback करें। एक अतिरिक्त credit खर्च होता है।

forceToGenderize यहां उपलब्ध नहीं है: नाम को आंतरिक रूप से निकाला जाता है, इसलिए एक अनिश्चित निष्कर्षण पर परिणाम को force करना दो अनुमानों को जोड़ता है।

curl "https://namegender.com/api/email?email=ayse.yilmaz84%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "status": true,
  "q": "ayse.yilmaz84@example.com",
  "name": "Ayse",
  "gender": "female",
  "probability": 95,
  "confidence": "unverified",
  "total_names": 655,
  "duration": "1ms",
  "source": "db"
}
GET · POST https://namegender.com/api/username

यूजरनेम से लिंग

camelCase, snake_case, trailing digit और leading @ signs को संभालता है। "AyseYilmaz84" Ayşe को resolve करता है।

पैरामीटर प्रकार विवरण
username
आवश्यक
string यूजरनेम या handle। एक leading @ को ignore किया जाता है।
country
वैकल्पिक
string ISO 3166-1 alpha-2 country code। उन नामों के लिए सटीकता में सुधार करता है जिनका लिंग क्षेत्र के अनुसार अलग-अलग होता है, जैसे Andrea (इटली में male, जर्मनी में female)।
askToAI
वैकल्पिक
boolean जब नाम database में न हो तो language model पर fallback करें। एक अतिरिक्त credit खर्च होता है।
forceToGenderize
वैकल्पिक
boolean सबसे संभावित लिंग लौटाएं भले ही confidence threshold से नीचे हो। डिफ़ॉल्ट रूप से बंद है, क्योंकि एक coin-flip उत्तर को निश्चित के रूप में प्रस्तुत करना कोई उत्तर न देने से बदतर है।
curl "https://namegender.com/api/username?username=AyseYilmaz84" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "status": true,
  "q": "AyseYilmaz84",
  "name": "Ayse",
  "gender": "female",
  "probability": 95,
  "confidence": "unverified",
  "source": "db"
}
POST https://namegender.com/api/bulk

बल्क अनुरोध

एक अनुरोध में 100 नाम तक भेजें। looping के बजाय इसका उपयोग करें: 100 नामों के लिए एक बल्क कॉल एक single round trip और एक single deduplicated lookup है।

पैरामीटर प्रकार विवरण
names
आवश्यक
string[] नामों की array। अधिकतम 100 items।
type
वैकल्पिक
string items क्या हैं: name, email या username। डिफ़ॉल्ट name है।
country
वैकल्पिक
string अनुरोध में प्रत्येक item पर लागू होता है।
curl -X POST "https://namegender.com/api/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names": ["Ayşe", "Mehmet", "Priya", "Wei"]}'
<?php

$ch = curl_init('https://namegender.com/api/bulk');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'names' => ['Ayşe', 'Mehmet', 'Priya', 'Wei'],
    ]),
]);

$data = json_decode(curl_exec($ch), true);

foreach ($data['results'] as $row) {
    printf("%-8s %-7s %d%%\n", $row['q'], $row['gender'] ?? '?', $row['probability']);
}
const response = await fetch('https://namegender.com/api/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ names: ['Ayşe', 'Mehmet', 'Priya', 'Wei'] }),
});

const { results, summary } = await response.json();

console.log(summary.match_rate);   // 100
results.forEach(r => console.log(r.q, r.gender, r.probability));
import requests

response = requests.post(
    "https://namegender.com/api/bulk",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"names": ["Ayşe", "Mehmet", "Priya", "Wei"]},
)

data = response.json()
print(data["summary"]["match_rate"])   # 100

for row in data["results"]:
    print(row["q"], row["gender"], row["probability"])
{
  "status": true,
  "used_credits": 4,
  "remaining_credits": 49995,
  "duration": "2ms",
  "summary": {
    "total": 4,
    "identified": 4,
    "unknown": 0,
    "match_rate": 100
  },
  "results": [
    { "q": "Ayşe",   "gender": "female", "probability": 95, "total_names": 0, "confidence": "unverified", "source": "db" },
    { "q": "Mehmet", "gender": "male",   "probability": 95, "total_names": 0, "confidence": "unverified", "source": "db" },
    { "q": "Priya",  "gender": "female", "probability": 95, "total_names": 0, "confidence": "unverified", "source": "db" },
    { "q": "Wei",    "gender": "male",   "probability": 85, "total_names": 0, "confidence": "unverified", "source": "db" }
  ]
}

परिणाम उसी क्रम में वापस आते हैं जिस क्रम में आपने उन्हें भेजा था। Credit प्रति नाम लिए जाते हैं, और यदि आपका balance कम है तो पूरा अनुरोध किसी भी काम से पहले अस्वीकार कर दिया जाता है, इसलिए आप कभी half-processed batch नहीं पाते हैं।

summary block आपको एक नज़र में match rate बताता है, इसलिए आप तय कर सकते हैं कि बाकी को process करने से पहले input को clean करने की आवश्यकता है या नहीं।

GET https://namegender.com/api/me

खाता और कोटा

एक credit खर्च किए बिना अपना शेष balance जांचें।

curl "https://namegender.com/api/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "status": true,
  "email": "you@example.com",
  "remaining_credits": 50099,
  "purchased_credits": 50000,
  "free_today": 99,
  "free_daily_limit": 100,
  "lifetime_requests": 12480,
  "expires": null
}

गैर-लैटिन लिपियाँ

नाम को अपनी लिपि में भेजें और हम इसे संदर्भ डेटा से जोड़ते हैं। कोई अतिरिक्त पैरामीटर नहीं: हम लिपि का पता लगाते हैं और इसके लिए सही रणनीति चुनते हैं।

समर्थित
अरबी लिपि

अरबी लेखन छोटी मात्राओं को छोड़ता है, इसलिए محمد को "mhmd" में लिप्यंतरित किया जाता है जबकि हमारे डेटा में "muhammed" है। हम व्यंजन पैटर्न पर मेल खाते हैं और स्त्रीलिंग ة चिन्ह को बनाए रखते हैं ताकि خالد (Khalid) और خالدة (Khalida) अलग रहें। फारसी और उर्दू नाम भी कवर करता है जो अरबी लिपि में लिखे हों।

चीनी अक्षर

Pinyin में रूपांतरित। चीनी में पहला नाम उपनाम है, इसलिए 李明 का उपनाम 李 (Li) है और दिया गया नाम 明 (Ming) है — हम खोज से पहले उपनाम हटाते हैं। एक एकल अक्षर एक पूर्ण दिया गया नाम है और एक के रूप में संभाला जाता है।

कोरियाई

चीनी जैसा ही उपनाम-पहले हैंडलिंग, सामान्य कोरियाई उपनामों का उपयोग करते हुए।

जापानी कना

हिरागाना और कातकाना सही तरीके से पढ़े जाते हैं (ひろし → Hiroshi)।

Cyrillic

रूसी, यूक्रेनी, बल्गेरियाई और सर्बियाई नाम सीधे लिप्यंतरित होते हैं।

देवनागरी

हिंदी, मराठी और नेपाली नाम। अंतर्निहित अनुगामी मात्रा को संभाला जाता है (राहुल → Rahul, "Rahula" नहीं)।

समर्थित नहीं
जापानी कांजी

जापानी कंजी और चीनी अक्षर एक ही Unicode range में आते हैं, इसलिए हम केवल अक्षरों से उन्हें अलग नहीं कर सकते। Han input को चीनी के रूप में पढ़ा जाता है: एक कंजी नाम जो हमारे पास शब्दशः नहीं है, उसे Mandarin उच्चारण मिलता है, जो जापानी नाम के लिए आमतौर पर गलत होता है (健太 को "jian tai" के रूप में पढ़ा जाता है जबकि नाम Kenta है)। जो नाम हमारे पास हैं वे बिल्कुल मेल खाते हैं और सही हैं। निश्चित होने के लिए जापानी नाम kana या Latin में भेजें।

थाई

थाई अरबी की तरह मात्राओं को छोड़ता है और इसके लिए अपनी मिलान परत की आवश्यकता है। अभी तक बनाई नहीं गई है, इसलिए ये null लौटाते हैं।

# Arap yazısı — ünsüz iskeleti üzerinden eşleşir
curl "https://namegender.com/api?name=%D9%85%D8%AD%D9%85%D8%AF" -H "Authorization: Bearer KEY"
# -> { "gender": "male", "probability": 100, "source": "script", "matched_as": "mahamad" }

# Çince — soyadı ayıklanır, verilen ad sorgulanır
curl "https://namegender.com/api?name=%E6%9D%8E%E6%98%8E" -H "Authorization: Bearer KEY"
# -> { "gender": "male", "probability": 92, "source": "db" }

जब हम किसी script को बिल्कुल भी bridge नहीं कर सकते, तो response में gender: null और source: none होता है। source field को देखें: script का अर्थ है हमने transliterate किया, db का अर्थ है हमने आपके द्वारा भेजे गए अक्षरों को सीधे match किया। दोनों में अलग-अलग confidence है, और हम आपको दिखाते हैं कि आपको कौन सा मिला।

Response फ़ील्ड

सभी endpoints पर समान।

फ़ील्ड प्रकार विवरण
status boolean false जब अनुरोध विफल हो। पहले इसे देखें।
used_credits integer इस अनुरोध में खर्च किए गए credits।
remaining_credits integer इस अनुरोध के बाद बचे हुए credits।
expires null हमेशा null। खरीदे गए credits expire नहीं होते।
q string आपका input, बिना बदले वापस किया गया।
name string वह नाम जिसे हमने वास्तव में खोजा, titles और surnames हटाने के बाद।
gender string male, female, या null जब हम आत्मविश्वास से कहने के लिए पर्याप्त निश्चित न हों।
country string वह देश जहाँ से आँकड़े आए, या null global aggregate के लिए।
total_names integer कितने असली लोगों पर यह उत्तर आधारित है। 0 का मतलब स्रोत गिनती के बजाय अनुपात देता है, न कि उत्तर कमजोर है।
probability integer बताए गए लिंग में आत्मविश्वास, 50 से 100। 0 जब gender null हो।
duration string Server-side processing समय।

दो फ़ील्ड जो अन्य सेवाएं नहीं देती हैं

source बताता है कि उत्तर कहाँ से आया: reference database, fuzzy match, या AI fallback। matched_as उस entry का नाम देता है जिस पर fuzzy match पड़ा। साथ में ये आपको यह तय करने देते हैं कि एक परिणाम पर कितना भरोसा करें।

फ़ील्ड प्रकार विवरण
source string db, fuzzy, llm, या none।
confidence string उच्च, मध्यम, निम्न, अपरिवर्तित, या अज्ञात — नमूना सबूत के आधार पर।
matched_as string Fuzzy match के लिए, वह database entry जो match हुई। अन्यथा null।

Error codes

Errors एक JSON body return करते हैं status: false के साथ और एक machine-readable error string। message पर नहीं, error पर match करें: messages translated होते हैं और बदल सकते हैं।

कोड HTTP अर्थ
missing_key 401 API key गायब है। इसे "key" पैरामीटर या Authorization: Bearer header के रूप में पास करें।
invalid_key 401 यह API key वैध नहीं है।
revoked_key 401 इस API key को रद्द कर दिया गया है।
blocked 403 यह खाता निलंबित कर दिया गया है। सहायता से संपर्क करें।
email_not_verified 403 इस खाते के ईमेल पते की अभी पुष्टि नहीं हुई है। हमने जो पुष्टिकरण लिंक भेजा है उसे खोलें, या डैशबोर्ड से नया लिंक माँगें।
ip_not_allowed 403 इस IP पते से इस key के लिए अनुरोध की अनुमति नहीं है।
forbidden 403 आपको यह कार्य करने की अनुमति नहीं है।
no_credits 402 आपके पास क्रेडिट समाप्त हो गए हैं। और खरीदें या अपनी दैनिक निःशुल्क कोटा रीसेट होने का इंतज़ार करें।
missing_input 400 "name" पैरामीटर आवश्यक है।
invalid_input 422 "name" पैरामीटर वैध नहीं है।
too_many_items 422 एक अनुरोध में अधिकतम 100 आइटम भेजे जा सकते हैं।
unknown_endpoint 404 इस पथ पर कोई endpoint नहीं है। API दस्तावेज़ के विरुद्ध URL की जाँच करें।
method_not_allowed 405 यह endpoint DELETE अनुरोधों को स्वीकार नहीं करता है।
payload_too_large 413 वह अनुरोध निकाय बहुत बड़ा है।
rate_limited 429 बहुत सारे अनुरोध। धीमा करें और जल्द ही फिर से कोशिश करें।
not_ready 503 नाम डेटाबेस फिर से बनाया जा रहा है। एक पल में फिर से कोशिश करें।
server_error 500 हमारी ओर से कुछ गलत हुआ। हमें सूचित कर दिया गया है।
{
  "status": false,
  "error": "no_credits",
  "message": "You are out of credits. Buy more or wait for your daily free quota to reset.",
  "request_id": "req_9c1f5b2a7e0d4a13",
  "docs": "https://namegender.com/docs#error-no_credits"
}

Rate limits

सामान्य उपयोग से limit नहीं लगती। यह cap एक leaked key के दुरुपयोग को रोकने के लिए है, और यह API key के अनुसार count होता है न कि IP के अनुसार, इसलिए एक सर्वर पर कई ग्राहक एक दूसरे का allowance नहीं खा सकते।

वर्तमान limit: प्रति मिनट 1,200 requests प्रति key। अधिक चाहिए? बताएं और हम इसे आपके खाते पर बढ़ा देंगे।

हर response में standard X-RateLimit-Limit और X-RateLimit-Remaining headers होते हैं।

किसी अन्य provider से माइग्रेट करना

हमारे response fields और parameter names सामान्य convention से मेल खाते हैं, इसलिए switching आमतौर पर एक line बदलने का मतलब है: base URL।

- https://api.other-provider.io/api?name=Ayşe&key=KEY
+ https://namegender.com/api?name=Ayşe&key=KEY

askToAI और forceToGenderize अपनी original spelling रखते हैं इसी कारण से। यदि कोई field जिस पर आप निर्भर हैं missing है, तो बताएं और हम इसे जोड़ देंगे।

अपना इनपुट एनकोड करें

नामों में स्पेस और गैर-ASCII वर्ण होते हैं। क्वेरी स्ट्रिंग में डालने से पहले मान को URL-एनकोड करें, या एक JSON बॉडी के साथ POST का उपयोग करें।

Ayşe Yılmaz  ->  Ay%C5%9Fe%20Y%C4%B1lmaz
محمد          ->  %D9%85%D8%AD%D9%85%D8%AF
中村           ->  %E4%B8%AD%E6%9D%91