GenderAPI.io V2 · Průvodce

Určení pohlaví podle indických jmen

Vyzkoušejte jména používaná v Indii s GenderAPI.io V2. Zachovejte původní zápisy, kontext země IN volte uváženě a správně vykládejte shody celého jména, výsledky AI i neznámé výsledky.

Poslední aktualizace:

Vyzkoušejte API V2

Analyzujte jméno

Datová sada + AI

Odešlete hodnotu a prohlédněte si celou odpověď, včetně neznámých výsledků a spotřebovaných kreditů.

Nástroj jako příklad používá kontext země: Indie (IN). Nejde o výchozí hodnotu pro všechna jména v tomto jazyce ani o důkaz státní příslušnosti.

Běžný požadavek: 1 kredit, včetně záložní AI a neznámých výsledků. S analýzou přezdívek: 1 kredit, pokud výsledek pochází z datové sady, nebo celkem 2 kredity, pokud se použije AI, i když je výsledek neznámý.

Odeslaná hodnota (jméno) se předá do GenderAPI.io, a pokud je potřeba záložní AI, může být předána nakonfigurované službě AI. Přečtěte si, jak se s daty zachází.

Žádný uložený API klíč. Můžete použít sdílený zkušební režim podle IP, dokud v něm zbývají kredity.

Odpověď níže je ilustrativní příklad. Požadavek odešlete tlačítkem Analyzovat.

Příklad odpovědi V2 · nejde o výsledek v reálném čase
Jméno—
PohlavíNeznámé
Spolehlivost—
ZdrojModel AI
Použité kredity1

Četnosti, hodnoty a zůstatek v příkladu ukazují jen formát odpovědi; skutečné hodnoty se mohou lišit. Odhad není ověřená identita.

Použijte původní jméno bez předpokladu jednoho písma nebo jednoho vzoru jmen

Tato ukázka používá příklad v písmu dévanágarí a kontext země IN. Jde o jeden příklad vstupu, nikoli o definici všech jmen používaných v Indii. API přijímá řetězce Unicode, takže můžete odeslat zápis, který je ve vašem záznamu, aniž byste ho nejprve převáděli do latinky.

Vyhledávání v datové sadě používá normalizované části jména. Neprovádí obecný převod mezi písmy a neslibuje, že zápisy v latince a v původním písmu povedou ke stejnému záznamu. Původní vstup uchovávejte spolu s vráceným jménem. To, že je písmo přijato, neznamená, že pro daný jazyk nebo komunitu existuje nezávisle naměřená přesnost.

Nepředpokládejte, že první nebo poslední část jména má pevnou roli. V2 vybere dostupného kandidáta s nejvyšším uloženým celkovým počtem a nezaručuje určitou pozici křestního jména. Iniciály, krátké části jména a chybějící uložené shody mohou způsobit, že datová sada nevrátí výsledek; záložní AI může zkusit celou odeslanou hodnotu.

Příklad vstupuCo představujeCo zkontrolovat
प्रिया शर्माPříklad celého jména v dévanágaríKandidáty se může stát více částí jména. Zkontrolujte vybrané jméno a shodu, místo abyste předpokládali, že vyhraje první část.
Priya SharmaPříklad v latinceJde o samostatný zápis; shodný výsledek napříč písmy se neslibuje.
A. KumarIniciála a část jménaJednopísmenná iniciála se nestane kandidátem v datové sadě. Shoda s druhou částí jména nepotvrzuje zamýšlené křestní jméno.
country: INUkázkový kontext: IndiePoužijte ho, když má váš záznam relevantní kontext země, ne jen proto, že se jméno objevuje v tomto průvodci.

Kontext země IN volte uváženě

Ukázka v reálném čase odesílá country: IN (Indie). API tuto zemi nevybírá podle písma, kterým je jméno zapsané. Ve své integraci použijte známý a relevantní kontext, nebo country vynechte; z této ukázkové hodnoty nedělejte výchozí hodnotu pro všechny záznamy.

Pro každého kandidáta dává vyhledávání v datové sadě přednost existujícímu záznamu pro konkrétní zemi a jinak zvažuje globální záznam. Potom vybere dostupného kandidáta s nejvyšším uloženým celkovým počtem. Skutečný rozsah shody zjistíte z data.match.scope a data.match.country. Záznam pro konkrétní zemi se stejným počtem pro obě pohlaví se automaticky nenahradí globálním výsledkem; fallback může místo toho použít AI.

data.input.country popisuje kontext požadavku. data.country a data.country_source popisují vrácené přiřazení. Jde o různá pole a neurčují státní občanství, etnickou příslušnost ani bydliště.

Odešlete indické jméno přes V2

Požadavek spusťte na svém serveru s GENDERAPI_API_KEY nastaveným na váš stávající klíč. Příklad výslovně zapíná běžnou záložní AI. Ukazuje podobu požadavku, nikoli naměřený odhad ani naměřené pokrytí. Pokud chcete použít pouze datovou sadu, nastavte options.ai_mode: off.

Vyberte programovací jazyk. Nastavte API klíč, potom spusťte příklad na svém serveru.

Každý požadavek na odhad je nová zpoplatněná operace, včetně opakování. Tyto příklady požadavky automaticky neopakují. Před odesláním dalšího požadavku zkontrolujte stav účtování.

Před spuštěním: přístup a zpracování chyb

Tyto příklady spouštějte na svém serveru. V prostředí procesu nastavte GENDERAPI_API_KEY na svůj stávající API klíč. Ověřte, že meta.access.mode je api_key: nerozpoznaný klíč může přejít na zkušební režim podle IP.

U odpovědí JSON s HTTP 4xx a 5xx příklady zachovají tělo chyby a skončí s nenulovým návratovým kódem. Před opakováním požadavku zkontrolujte code, action a meta.usage.billing_status.

Průvodce chybami a opakováním požadavků →
cURL
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": "IN",
  "options": {
    "ai_mode": "fallback"
  }
}'

cURL 7.76+ v shellu POSIX. Spusťte v terminálu. Dokumentace běhového prostředí

JavaScript / Node.js
// 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": "IN",
  "options": {
    "ai_mode": "fallback"
  }
};

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+; vestavěné fetch. Uložte jako example.mjs a spusťte node example.mjs. Dokumentace běhového prostředí

Python
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\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}")

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+; standardní knihovna. Uložte jako example.py a spusťte python3 example.py. Dokumentace běhového prostředí

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"प्रिया शर्मा","country":"IN","options":{"ai_mode":"fallback"}}', 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+ s rozšířením cURL. Uložte jako example.php a spusťte php example.php. Dokumentace běhového prostředí

Java
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\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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+; standardní HTTP klient. Uložte jako GenderApiExample.java a spusťte java GenderApiExample.java. Dokumentace běhového prostředí

C# / .NET
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\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}", 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.
}

Konzolová aplikace .NET 8+. Použijte jako Program.cs v konzolovém projektu a potom spusťte dotnet run. Dokumentace běhového prostředí

Go
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\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    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+; standardní knihovna. Uložte jako main.go a spusťte go run main.go. Dokumentace běhového prostředí

Uchovávejte výsledek spolu s jeho podklady

Odvozené přiřazení není pohlaví, které osoba sama uvedla. Původní vstup, vrácené podklady a údaje, které poskytla sama osoba, uchovávejte odděleně. Neznámý výsledek je platný výsledek a ve vaší aplikaci by se z něj neměla stát odhadnutá kategorie.

PoleJak ho použít
data.gender / data.result_statusmale nebo female používejte jen u výsledku identified. U neznámého výsledku zachovejte původní hodnotu JSON null.
data.name / data.matchZkontrolujte vrácené jméno a vybraného kandidáta. Shoda s částí řetězce nedokazuje, že vstup patří osobě s tímto křestním jménem.
data.confidence / data.confidence_kindSpolehlivost je hodnota od 0 do 1, nebo null. observed_frequency vychází z uložených četností; model_reported je skóre AI. Prahové hodnoty vyhodnocujte pro každý druh zvlášť.
data.source / data.sample_countRozlišujte dataset, ai a none. Výsledky AI nemají uloženou velikost vzorku. Velikost vzorku není naměřená přesnost.
meta.access.modeV integraci s účtem ověřte, že je uvedeno api_key. Chybějící nebo nerozpoznané klíče mohou místo toho použít sdílený zkušební režim podle IP.
meta.usageČtěte charged_credits a billing_status. Úspěšný neznámý výsledek se účtuje. Ztracená odpověď nedokazuje, že požadavek byl zdarma.

Rozhodněte, kdy použít AI

forceToGenderize je volitelné pro jména, e-mailové adresy i uživatelská jména. Pokud je zapnuté, ai_mode vynechte nebo použijte fallback; off a always jsou s ním v konfliktu a vrátí 422. K zahájení požadavku stačí kladný počáteční zůstatek, i když konečné vyúčtování dostane zůstatek do záporu.

Režim přezdívek může vrátit pohlaví spolu s name: null. Může také vrátit neznámý výsledek. Běžná záložní AI ani analýza přezdívek nezaručuje správnou odpověď ani hodnotu jinou než null.

Možnost požadavkuChováníKredity za úspěšné vyhledání
options.ai_mode: offPoužije pouze datovou sadu.1, včetně neznámého výsledku
options.ai_mode: fallbackNejprve prohledá datovou sadu, a pokud nevrátí pohlaví, použije běžnou AI. Jde o výchozí nastavení jednotlivých požadavků.Celkem 1, včetně záložní AI
options.ai_mode: alwaysPoužije přímo AI.2
forceToGenderize: trueNejprve prohledá datovou sadu a potom umožní AI vyložit osobní přezdívku nebo alias, i bez skutečného křestního jména.1 za výsledek z datové sady; celkem 2, pokud se použije AI

Zpracujte seznam jmen, aniž byste ztratili kontext

Použijte POST /api/v2/gender/batch pro nejvýše 50 položek s registrovaným API klíčem nebo 10 položek ve zkušebním režimu podle IP. Každé položce přidělte jedinečné id a u každého řádku zachovejte původní hodnotu. Každá položka může mít vlastní zemi a vlastní pravidla AI; pokud zemi neznáte, country vynechte.

Na rozdíl od jednotlivých požadavků, u kterých je výchozí fallback, používají položky dávky ve výchozím nastavení pouze datovou sadu. U každé položky, která potřebuje AI, nastavte options.ai_mode: fallback. Kontrolujte každý výsledek i po HTTP 200, zachovejte neznámé výsledky a před dalším odesláním zkontrolujte chyby jednotlivých položek a účtování. Každá úspěšná běžná položka stojí 1 kredit; jeden požadavek HTTP s dávkou neznamená jeden kredit za jeden odhad.

Vězte, co odesíláte

Ukázka v reálném čase odešle zadanou hodnotu do GenderAPI.io jen tehdy, když ji sami odešlete. Pokud se použije AI, předá se odeslaný type, value a kontext země službě nakonfigurované pro odhady. Pro odhad pouze z datové sady nastavte ve své integraci options.ai_mode: off bez forceToGenderize.

Zásady ochrany osobních údajů, smlouva o zpracování osobních údajů a seznam dalších zpracovatelů popisují zveřejněné podmínky zpracování. Výsledek je odvozené přiřazení; přednost mají údaje, které poskytla sama osoba. Nepoužívejte ho jako podklad pro rozhodnutí se závažnými důsledky pro jednotlivce.

Časté dotazy

Podporuje ukázka indických jmen jen hindská jména?

Ukázka používá jeden příklad v dévanágarí, API však přijímá jména jako řetězce Unicode. Přijetí takového vstupu netvrdí úplné pokrytí v datové sadě ani naměřenou přesnost pro každý jazyk používaný v Indii.

Vrátí zápis v latince stejný výsledek jako původní písmo?

To není zaručeno. Vyhledávání v datové sadě obecně nepovažuje transliterace za rovnocenné. Každý odeslaný zápis uchovávejte spolu s vrácenými údaji source a match a se spolehlivostí.

Je přesnost měřena pro každé indické jméno?

Tato stránka žádné takové měření nezveřejňuje. Přijetí vstupu, uložené četnosti ani hodnota spolehlivosti nejsou nezávislým měřením přesnosti. Na stránce o metodice najdete dostupné podklady i měření, která zatím zveřejněna nejsou.

Stojí neznámý výsledek kredity?

Úspěšný neznámý výsledek se účtuje. Běžný režim s datovou sadou nebo fallback stojí celkem 1 kredit. S forceToGenderize stojí výsledek z datové sady 1 kredit a použití AI celkem 2 kredity, i když AI vrátí neznámý výsledek. Chyby mají vlastní pravidla účtování; zkontrolujte meta.usage.

Pokračovat v testování

Použít klíč GenderAPI

Po vyčerpání sdílených kreditů 24hodinového zkušebního režimu podle IP vložte API klíč ze svého účtu GenderAPI a pokračujte v testování. Uložení klíče neodešle žádný požadavek – až budete připraveni, odešlete jej znovu.

Ukládá se pouze pro tuto kartu prohlížeče a po jejím zavření se odstraní.