REST API संदर्भ
चार endpoint, एक प्रतिक्रिया रूप। नीचे सब कुछ आपके खाते के विरुद्ध लाइव है।
https://namegender.com/api
मुफ्त साइन अप करें
त्वरित शुरुआत
अपने डैशबोर्ड में एक 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: Bearer ng_live_xxxxxxxxxxxx
X-Api-Key: ng_live_xxxxxxxxxxxx
https://namegender.com/api?name=Ayşe&key=ng_live_xxxxxxxxxxxx
आप डैशबोर्ड से key को विशिष्ट IP पतों तक सीमित कर सकते हैं।
क्लाइंट लाइब्रेरी
एक API, चार इनपुट प्रकार, और बल्क टूल जो वह फाइलें संभालते हैं जहां अन्य सेवाएं विफल होती हैं।
सभी देखें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
}
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"
}
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"
}
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 करने की आवश्यकता है या नहीं।
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)।
रूसी, यूक्रेनी, बल्गेरियाई और सर्बियाई नाम सीधे लिप्यंतरित होते हैं।
हिंदी, मराठी और नेपाली नाम। अंतर्निहित अनुगामी मात्रा को संभाला जाता है (राहुल → 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 आइटम भेजे जा सकते हैं। |
ai_consent_required |
422 | askToAI नाम को एक तृतीय-पक्ष AI प्रदाता को भेजता है, जिसके लिए इस खाते ने सहमति नहीं दी है। प्रदाता जानने के लिए "ai" फ़ील्ड देखें, फिर अपनी डैशबोर्ड सेटिंग्स में AI lookups को सक्षम करें। |
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