GenderAPI.io V2: pohlaví podle jména

Před odesláním požadavku

Posílejte JSON na POST https://api.genderapi.io/api/v2/gender. Použijte svůj stávající API klíč v Authorization: Bearer YOUR_API_KEY a Content-Type: application/json. Každý požadavek se zpracovává samostatně.

V příkladu kódu vyberte programovací jazyk. Před spuštěním nastavte GENDERAPI_API_KEY v prostředí procesu. Chybějící nebo nerozpoznané klíče mohou použít sdílený zkušební režim podle IP, proto při integraci účtu ověřte, že meta.access.mode je api_key.

Pohlaví podle jména

Parametr	Typ	Povinné	Výchozí hodnota	Popis
`type`	`string`	Ano	`—`	Kategorie vstupu: name, email nebo username.
`value`	`string`	Ano	`—`	Povinné. 1–254 znaků; nesmí být prázdné ani obsahovat řídicí znaky. E-mailové hodnoty musí mít platnou syntaxi e-mailové adresy.
`country`	`string`	Ne	`—`	Volitelný kód ISO 3166-1 alpha-2 velkými písmeny, například TR nebo US. Vyhledávání pro konkrétní zemi může přejít na globální datovou sadu.
`forceToGenderize`	`boolean`	Ne	`false`	Nejprve se prohledá datová sada, a pokud nepřinese výsledek, použije se AI s analýzou přezdívek. Podporováno pro name, email a username.
`options`	`object`	Ne	`—`	Objekt s možnostmi AI pro daný vstup.
`options.ai_mode`	`string`	Ne	`fallback`	Povolené hodnoty: off, fallback, always. Při forceToGenderize: true toto pole vynechte nebo použijte fallback.
`id`	`string`	Ne	`—`	Volitelný identifikátor o délce 1–64 znaků v těle JSON u POST. Vrací se u každého výsledku dávky; v rámci dávky musí být jedinečný. U jednotlivých odhadů se přijme, ale v odpovědi se nevrací. V dotazech GET není podporován.

Pro křestní nebo celé jméno použijte type: name. I úspěšná odpověď může obsahovat gender: null. Jednotlivé požadavky nejprve prohledají datovou sadu, a pokud pohlaví nelze určit, ve výchozím nastavení se obrátí na AI.

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 --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": "Tomáš",
  "country": "CZ"
}'

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

// 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": "Tomáš",
  "country": "CZ"
};

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í

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\":\"Tomáš\",\"country\":\"CZ\"}")

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
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Tomáš","country":"CZ"}', 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í

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\":\"Tomáš\",\"country\":\"CZ\"}";
        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í

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\":\"Tomáš\",\"country\":\"CZ\"}", 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í

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\":\"Tomáš\",\"country\":\"CZ\"}"
    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í

Příklad odpovědi

Jde o skutečnou odpověď získanou 1. října 2026 s API klíčem; nahrazen byl pouze zůstatek účtu. Nejde o míru přesnosti a požadavek v reálném čase může vrátit jiný výsledek. Požadavky s API klíčem vracejí meta.access.mode: api_key a pole kvót platná jen pro zkušební režim mají hodnotu null; požadavky ve zkušebním režimu podle IP vracejí ip_trial. Odhad najdete v data, výsledek účtování operace v meta.usage.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Tomáš",
      "country": "CZ"
    },
    "name": "tomáš",
    "gender": "male",
    "country": "CZ",
    "confidence": 0.9969591659426585,
    "confidence_kind": "observed_frequency",
    "sample_count": 2302,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "tomáš",
      "method": "normalized",
      "scope": "country",
      "country": "CZ"
    }
  },
  "meta": {
    "request_id": "050f6ca4-8761-4a3f-ba00-b7fdd718ec4b",
    "duration_ms": 12,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Pole odpovědi a spolehlivost

Pole odpovědi s odhadem

Pole	Typ	Může být null	Příklad	Popis
`data.input`	`object`	Ne	`{"type":"name","value":"Tomáš","country":"CZ"}`	Typ vstupu, hodnota a země. forceToGenderize se uvádí, pokud má hodnotu true.
`data.name`	`string`	Ano	`"tomáš"`	Nalezené nebo získané křestní jméno; null, pokud není k dispozici.
`data.gender`	`string`	Ano	`"male"`	male, female nebo JSON null. Jde o odhad, nikoli o ověřenou osobní identitu.
`data.result_status`	`string`	Ne	`"identified"`	identified, pokud je vráceno pohlaví; jinak unknown.
`data.reason`	`string`	Ano	`null`	null u výsledků identified. Důvody neznámého výsledku: not_found, no_name_candidate, ambiguous nebo insufficient_evidence.
`data.confidence`	`number`	Ano	`0.95`	Skóre 0–1 nebo null. Pohlaví null má spolehlivost null.
`data.confidence_kind`	`string`	Ano	`"observed_frequency"`	observed_frequency: počet dominantního pohlaví v datové sadě / celkový počet. model_reported: skóre AI, nikoli kalibrovaná pravděpodobnost. null, pokud není k dispozici.
`data.sample_count`	`integer`	Ano	`1200`	Velikost vzorku v datové sadě nebo null. AI si počet vzorků nevymýšlí.
`data.source`	`string`	Ne	`"dataset"`	dataset, ai nebo none.
`data.country`	`string`	Ano	`"CZ"`	Přiřazení země z dataset nebo ai_association, případně null. Neurčuje státní příslušnost, bydliště ani etnickou příslušnost.
`data.country_source`	`string`	Ano	`"dataset"`	Původ přiřazení země: dataset, ai_association nebo null.
`data.match`	`object`	Ne	`{"name":"tomáš","method":"normalized","scope":"country","country":"CZ"}`	Nalezené jméno v datové sadě, metoda (normalized, token, substring nebo model_inference), rozsah country/global a nalezená země. Nedostupné podklady mají hodnotu null.

Metadata přístupu, účtování a požadavku

Pole	Typ	Může být null	Příklad	Popis
`meta.request_id`	`string`	Ne	`"550e8400-e29b-41d4-a716-446655440000"`	Jedinečný identifikátor tohoto pokusu HTTP; posílá se také v X-Request-ID.
`meta.duration_ms`	`integer`	Ne	`42`	Doba zpracování požadavku v milisekundách.
`meta.access.mode`	`string`	Ne	`"api_key"`	api_key, ip_trial nebo unauthenticated. U placeného účtu ověřte api_key.
`meta.access.reason`	`string`	Ano	`null`	Důvod přechodu na zkušební režim: api_key_missing, api_key_invalid nebo api_key_not_found; jinak null.
`meta.usage.charged_credits`	`integer`	Ano	`1`	Čistý počet odečtených kreditů. Nula před odečtením nebo po úplném potvrzeném vrácení; null, pokud účtování není potvrzeno.
`meta.usage.remaining_credits`	`integer`	Ano	`99`	Zůstatek po dokončení operace. Může být záporný; null, pokud není k dispozici nebo účtování není potvrzeno.
`meta.usage.billing_status`	`string`	Ne	`"confirmed"`	not_charged, confirmed nebo unconfirmed. Zkontrolujte před opakováním neúspěšného odhadu.
`meta.usage.resets_at`	`string`	Ano	`"2026-09-27T12:00:00.000Z"`	Čas obnovení zkušebního režimu podle IP v UTC (ISO 8601); null u účtů s API klíčem nebo pokud není znám.
`meta.usage.limit`	`integer`	Ano	`10`	Limit kreditů zkušebního režimu podle IP; null u účtů s API klíčem.
`meta.usage.period_seconds`	`integer`	Ano	`86400`	Délka období zkušebního režimu podle IP v sekundách; null u účtů s API klíčem.

Kontext země a neznámá jména

Zemi uvádějte jen tehdy, když máte relevantní kontext. API může vybrat řádek datové sady pro konkrétní zemi, nebo přejít na globální řádek. Který z nich byl vybrán, ukazuje data.match.scope; vrácená země neurčuje, kde osoba žije.

Jednotlivé požadavky mají ve výchozím nastavení záložní AI za celkem 1 kredit. Chcete-li použít pouze datovou sadu, pošlete options: {"ai_mode": "off"}. Nevyřešené vstupy mohou vrátit gender: null a při úspěšné operaci se přesto účtují. Celé jméno se může shodovat jen s jednou svou částí; data.match zaznamenává vybraného kandidáta a metodu shody.

U hodnot jména, které připomínají přezdívku, umožňuje forceToGenderize: true odhad i bez skutečného křestního jména: výsledek z datové sady stojí 1 kredit, jinak AI s analýzou přezdívek stojí celkem 2 kredity. Stačí kladný počáteční zůstatek; výsledný zůstatek může být záporný.

Vyhledejte celé jméno bez předpokladu, že rozhoduje první slovo

Pošlete původní jméno v Unicode. Shoda v datové sadě používá normalizaci NFKC, převod na malá písmena a rozdělení na části jména; jméno nemusíte převádět do ASCII. Z dostupných kandidátů API vybere záznam v datové sadě s nejvyšším uloženým celkovým počtem. Tímto kandidátem může být i pozdější část jména, proto nepředpokládejte, že bylo vybráno první slovo nebo křestní jméno.

Tento požadavek používá pouze datovou sadu, takže je snazší zkontrolovat, z jakých podkladů výsledek vychází. V data.input.value najdete odeslané celé jméno, v data.match.name kandidáta, který byl vyhledán, a v data.match.method metodu shody. Příklad neslibuje konkrétní pohlaví ani výběr konkrétní části jména. Kandidáti v datové sadě musí mít více než dva znaky; krátké vstupy mohou zůstat bez výsledku. Běžnou záložní AI použijte tehdy, když se tento doplňkový odhad pro vaši aplikaci hodí.