GenderAPI.io V2 ile isimden cinsiyet tahmini

İsteği göndermeden önce

POST https://api.genderapi.io/api/v2/gender adresine JSON gönderin. Authorization: Bearer YOUR_API_KEY başlığında mevcut anahtarınızı ve Content-Type: application/json kullanın. Her istek bağımsız işlenir.

Kod örneğinde dilinizi seçin. Çalıştırmadan önce GENDERAPI_API_KEY ortam değişkenini ayarlayın. Eksik veya tanınmayan anahtarlar ortak IP denemesini kullanabilir; hesap entegrasyonunda meta.access.mode değerinin api_key olduğunu doğrulayın.

İsimden cinsiyet tahmini

Parametre	Tür	Zorunlu	Varsayılan	Açıklama
`type`	`string`	Evet	`—`	Girdi türü: name, email veya username.
`value`	`string`	Evet	`—`	Zorunlu. 1–254 karakter; boş olamaz ve kontrol karakteri içeremez. E-posta değeri geçerli e-posta sözdizimine uymalıdır.
`country`	`string`	Hayır	`—`	İsteğe bağlı, büyük harfli ISO 3166-1 alpha-2 kodu; örneğin TR veya US. Ülkeye özel sorgu, genel veri kümesine dönebilir.
`forceToGenderize`	`boolean`	Hayır	`false`	Önce veri kümesine bakılır; sonuç bulunamazsa takma adları yorumlayan yapay zekâ kullanılır. name, email ve username için desteklenir.
`options`	`object`	Hayır	`—`	Her girdiye ait yapay zekâ seçeneklerini içeren nesne.
`options.ai_mode`	`string`	Hayır	`fallback`	Geçerli değerler: off, fallback, always. forceToGenderize: true olduğunda bu alanı göndermeyin veya fallback kullanın.
`id`	`string`	Hayır	`—`	POST JSON içinde isteğe bağlı, 1–64 karakterlik kimlik. Her toplu sonuçta geri döner ve aynı toplu istekte benzersiz olmalıdır. Tekli sorguda kabul edilir ancak yanıtta yer almaz. GET sorgularında desteklenmez.

Ad veya tam ad için type: name kullanın. Başarılı yanıtta gender: null olabilir. Tekli istekler önce veri kümesini kontrol eder; cinsiyet belirlenemezse varsayılan olarak yapay zekâya sorar.

Programlama dilinizi seçin. API anahtarınızı ayarlayın, ardından örneği sunucunuzda çalıştırın.

Yeniden denemeler dahil her tahmin isteği yeni ve ücretlendirilebilir bir işlemdir. Örnekler otomatik yeniden deneme yapmaz. Yeni istekten önce ücretlendirme durumunu kontrol edin.

Çalıştırmadan önce: erişim ve hata yönetimi

Örnekleri sunucunuzda çalıştırın. İşlem ortamındaki GENDERAPI_API_KEY değişkenini mevcut anahtarınıza ayarlayın. Tanınmayan anahtar IP denemesine yönlenebildiğinden meta.access.mode değerinin api_key olduğunu doğrulayın.

HTTP 4xx ve 5xx JSON yanıtlarında hata gövdesi korunur ve program sıfırdan farklı çıkış koduyla sonlanır. Yeniden denemeden önce code, action ve meta.usage.billing_status alanlarını kontrol edin.

Hata ve yeniden deneme rehberi →

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": "Elif",
  "country": "TR"
}'

POSIX kabuğunda cURL 7.76+. Terminalinizde çalıştırın. Çalıştırma ortamı dokümantasyonu

// 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": "Elif",
  "country": "TR"
};

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+; yerleşik fetch. example.mjs olarak kaydedin ve node example.mjs çalıştırın. Çalıştırma ortamı dokümantasyonu

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\":\"Elif\",\"country\":\"TR\"}")

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+; standart kütüphane. example.py olarak kaydedin ve python3 example.py çalıştırın. Çalıştırma ortamı dokümantasyonu

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Elif","country":"TR"}', 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.

cURL uzantılı PHP 8+. example.php olarak kaydedin ve php example.php çalıştırın. Çalıştırma ortamı dokümantasyonu

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\":\"Elif\",\"country\":\"TR\"}";
        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+; standart HTTP istemcisi. GenderApiExample.java olarak kaydedin ve java GenderApiExample.java çalıştırın. Çalıştırma ortamı dokümantasyonu

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\":\"Elif\",\"country\":\"TR\"}", 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.
}

.NET 8+ konsol uygulaması. Konsol projesinde Program.cs olarak kullanın, ardından dotnet run çalıştırın. Çalıştırma ortamı dokümantasyonu

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\":\"Elif\",\"country\":\"TR\"}"
    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+; standart kütüphane. main.go olarak kaydedin ve go run main.go çalıştırın. Çalıştırma ortamı dokümantasyonu

Örnek yanıt

Bu, 1 Ekim 2026'da API anahtarıyla alınmış gerçek bir yanıttır; yalnızca hesap bakiyesi değiştirilmiştir. Doğruluk ölçüsü değildir ve canlı bir istek farklı bir sonuç döndürebilir. API anahtarlı isteklerde meta.access.mode: api_key döner ve yalnızca denemeye ait kota alanları null olur; IP denemesi isteklerinde ip_trial döner. Tahmini data, işlemin ücretlendirme sonucunu meta.usage içinde okuyun.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Elif",
      "country": "TR"
    },
    "name": "elif",
    "gender": "female",
    "country": "TR",
    "confidence": 0.9896548693676163,
    "confidence_kind": "observed_frequency",
    "sample_count": 79651,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "elif",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "d570b038-4085-4ae3-ba10-50b54721e518",
    "duration_ms": 26,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Yanıt alanları ve güven skoru

Tahmin yanıtı alanları

Alan	Tür	Null olabilir mi?	Örnek	Açıklama
`data.input`	`object`	Hayır	`{"type":"name","value":"Elif","country":"TR"}`	Girdi türü, değeri ve ülkesi. forceToGenderize, true olduğunda eklenir.
`data.name`	`string`	Evet	`"elif"`	Eşleşen veya çıkarılan ad; bulunamıyorsa null.
`data.gender`	`string`	Evet	`"male"`	male, female veya JSON null. Doğrulanmış kişisel kimlik değil, tahmindir.
`data.result_status`	`string`	Hayır	`"identified"`	Cinsiyet döndürüldüğünde identified, diğer durumlarda unknown.
`data.reason`	`string`	Evet	`null`	Sonuç identified ise null. Bilinmeyen sonuç nedenleri: not_found, no_name_candidate, ambiguous veya insufficient_evidence.
`data.confidence`	`number`	Evet	`0.95`	0–1 arası puan veya null. Cinsiyet null ise güven skoru da null’dır.
`data.confidence_kind`	`string`	Evet	`"observed_frequency"`	observed_frequency: baskın veri kümesi sayısı / toplam. model_reported: yapay zekâ skoru; kalibre edilmiş olasılık değildir. Bilgi yoksa null.
`data.sample_count`	`integer`	Evet	`1200`	Veri kümesindeki örnek sayısı veya null. Yapay zekâ örnek sayısı üretmez.
`data.source`	`string`	Hayır	`"dataset"`	dataset, ai veya none.
`data.country`	`string`	Evet	`"TR"`	Veri kümesi veya ai_association kaynaklı ülke ilişkisi; bilgi yoksa null. Vatandaşlık, ikamet veya etnik köken kanıtı değildir.
`data.country_source`	`string`	Evet	`"dataset"`	Ülke ilişkilendirmesinin kaynağı: dataset, ai_association veya null.
`data.match`	`object`	Hayır	`{"name":"elif","method":"normalized","scope":"country","country":"TR"}`	Eşleşen isim, yöntem (normalized, token, substring veya model_inference), ülke/genel kapsam ve eşleşen ülke. Olmayan kanıt null’dır.

Erişim, ücretlendirme ve istek bilgileri

Alan	Tür	Null olabilir mi?	Örnek	Açıklama
`meta.request_id`	`string`	Hayır	`"550e8400-e29b-41d4-a716-446655440000"`	Bu HTTP isteğinin benzersiz kimliği; X-Request-ID başlığında da gönderilir.
`meta.duration_ms`	`integer`	Hayır	`42`	İsteğin milisaniye cinsinden işlenme süresi.
`meta.access.mode`	`string`	Hayır	`"api_key"`	api_key, ip_trial veya unauthenticated. Hesap anahtarıyla erişimde api_key olduğunu doğrulayın.
`meta.access.reason`	`string`	Evet	`null`	Denemeye geçiş nedeni: api_key_missing, api_key_invalid veya api_key_not_found; diğer durumlarda null.
`meta.usage.charged_credits`	`integer`	Evet	`1`	Net düşülen kredi. Ücretlendirme öncesinde veya tam iade doğrulandığında sıfırdır; ücretlendirme belirsizse null.
`meta.usage.remaining_credits`	`integer`	Evet	`99`	İşlem tamamlandığındaki bakiye. Negatif olabilir; bilgi alınamıyorsa veya ücretlendirme belirsizse null.
`meta.usage.billing_status`	`string`	Hayır	`"confirmed"`	not_charged, confirmed veya unconfirmed. Başarısız bir tahmini yeniden denemeden önce kontrol edin.
`meta.usage.resets_at`	`string`	Evet	`"2026-09-27T12:00:00.000Z"`	IP denemesinin UTC sıfırlanma zamanı (ISO 8601); API anahtarlı hesaplarda veya bilinmiyorsa null.
`meta.usage.limit`	`integer`	Evet	`10`	IP denemesinin kredi hakkı; API anahtarlı hesaplarda null.
`meta.usage.period_seconds`	`integer`	Evet	`86400`	IP denemesinin saniye cinsinden süresi; API anahtarlı hesaplarda null.

Ülke bağlamı ve bulunamayan isimler

country alanını yalnızca ilgili ülke bilgisi varsa gönderin. API ülkeye özel veya genel veri kümesi kaydını seçebilir; seçimi data.match.scope gösterir. Dönen ülke, kişinin yaşadığı yeri kanıtlamaz.

Tekli istekte varsayılan AI fallback toplam 1 kredidir. Yalnızca veri kümesi için options: {"ai_mode": "off"} gönderin. İşlem başarıyla tamamlandığında gender: null sonucu da ücretlidir. Tam adın bir bileşeni eşleşebilir; seçilen aday ve yöntem data.match içinde bulunur.

Takma ad niteliğindeki isimlerde forceToGenderize: true, gerçek ad bulunmadan tahmine izin verir. Çözülen veri kümesi sonucu 1 kredi; aksi halde takma ad odaklı yapay zekâ toplam 2 kredidir. Pozitif başlangıç bakiyesi yeterlidir; sonuçta bakiye eksiye düşebilir.

Tam ad sorgusunda hangi adın eşleştiğini kontrol edin

Adı özgün Unicode karakterleriyle gönderin; Türkçe karakterleri ASCII karşılıklarına dönüştürmeniz gerekmez. Veri kümesi eşleştirmesi NFKC normalleştirmesi, küçük harfe dönüştürme ve ad bileşenlerini ayırma adımlarını uygular. Mevcut adaylar arasından kayıt toplamı en yüksek olan seçilir. Bu aday, tam adın sonraki bir bileşeni de olabilir; ilk sözcüğün veya kişinin ön adının seçildiğini varsaymayın.

Aşağıdaki örnek yalnızca veri kümesini sorgular. Gönderdiğiniz tam adı data.input.value, seçilen adayı data.match.name, eşleştirme yöntemini data.match.method alanından okuyun. Örnek, belirli bir cinsiyet veya ad bileşeninin döneceğini garanti etmez. Veri kümesi adayları iki karakterden uzun olmalıdır; kısa girdilerde tahmin bulunamayabilir. Uygulamanız için uygunsa standart yapay zekâ yedeklemesini açabilirsiniz.