GenderAPI.io V2: płeć na podstawie imienia lub imienia i nazwiska

Przed wysłaniem zapytania

Wysyłaj zapytania o prognozy GenderAPI.io V2 do POST https://api.genderapi.io/api/v2/gender, z type i value w treści JSON. Użyj istniejącego klucza GenderAPI.io w Authorization: Bearer YOUR_API_KEY oraz Content-Type: application/json. Wynik odczytasz w data, a informacje o dostępie i rozliczeniach w meta. Każde zapytanie jest przetwarzane niezależnie.

Wybierz język programowania w przykładzie kodu. Przed uruchomieniem ustaw GENDERAPI_API_KEY w środowisku procesu. Brakujący lub nierozpoznany klucz może spowodować użycie współdzielonej próby dla adresu IP, dlatego przy integracji konta upewnij się, że meta.access.mode ma wartość api_key.

Płeć na podstawie imienia

Parametr	Typ	Wymagany	Wartość domyślna	Opis
`type`	`string`	Tak	`—`	Kategoria danych wejściowych: name, email lub username.
`value`	`string`	Tak	`—`	Wymagane. 1–254 znaki; wartość niepusta, bez znaków sterujących. Wartość typu email musi mieć poprawną składnię adresu e-mail.
`country`	`string`	Nie	`—`	Opcjonalny kod ISO 3166-1 alpha-2 zapisany wielkimi literami, na przykład TR lub US. Wyszukiwanie dla konkretnego kraju może przejść na globalny zbiór danych.
`forceToGenderize`	`boolean`	Nie	`false`	Najpierw sprawdza zbiór danych, a przy braku wyniku używa AI uwzględniającej pseudonimy. Obsługiwane dla name, email i username.
`options`	`object`	Nie	`—`	Obiekt z opcjami AI dla danego wejścia.
`options.ai_mode`	`string`	Nie	`fallback`	Dozwolone wartości: off, fallback, always. Przy forceToGenderize: true pomiń pole lub użyj fallback.
`id`	`string`	Nie	`—`	Opcjonalny identyfikator o długości 1–64 znaków w treści JSON zapytania POST. Zwracany obok każdego wyniku partii; musi być unikalny w obrębie partii. Akceptowany, ale niezwracany w pojedynczych prognozach. Nieobsługiwany w zapytaniach GET.

W przypadku imienia lub imienia i nazwiska wyślij type: name i całą wartość w value do POST https://api.genderapi.io/api/v2/gender. GenderAPI.io V2 używa tych samych pól zapytania dla obu formatów. Pomyślna odpowiedź może mimo to zawierać data.gender: null. Pojedyncze zapytania najpierw sprawdzają zbiór danych, a jeśli nie da się ustalić płci, domyślnie przechodzą na AI.

Wybierz język programowania. Skonfiguruj klucz API, następnie uruchom przykład na swoim serwerze.

Każde zapytanie o prognozę, łącznie z ponownymi próbami, jest nową płatną operacją. Te przykłady nie ponawiają zapytań automatycznie. Przed wysłaniem kolejnego zapytania sprawdź status rozliczenia.

Zanim uruchomisz: dostęp i obsługa błędów

Uruchamiaj te przykłady na swoim serwerze. Ustaw w środowisku procesu zmienną GENDERAPI_API_KEY na swój istniejący klucz API. Upewnij się, że meta.access.mode ma wartość api_key: nierozpoznany klucz może spowodować przejście na próbę dla adresu IP.

W przypadku odpowiedzi JSON z kodem HTTP 4xx i 5xx przykłady zachowują treść błędu i zwracają niezerowy kod wyjścia. Przed ponowną próbą sprawdź code, action i meta.usage.billing_status.

Przewodnik po błędach i ponawianiu zapytań →

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": "Krzysztof",
  "country": "PL"
}'

cURL 7.76+ w powłoce POSIX. Uruchom w terminalu. Dokumentacja środowiska uruchomieniowego

// 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": "Krzysztof",
  "country": "PL"
};

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+; wbudowany fetch. Zapisz jako example.mjs i uruchom node example.mjs. Dokumentacja środowiska uruchomieniowego

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\":\"Krzysztof\",\"country\":\"PL\"}")

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+; biblioteka standardowa. Zapisz jako example.py i uruchom python3 example.py. Dokumentacja środowiska uruchomieniowego

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Krzysztof","country":"PL"}', 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+ z rozszerzeniem cURL. Zapisz jako example.php i uruchom php example.php. Dokumentacja środowiska uruchomieniowego

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\":\"Krzysztof\",\"country\":\"PL\"}";
        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+; standardowy klient HTTP. Zapisz jako GenderApiExample.java i uruchom java GenderApiExample.java. Dokumentacja środowiska uruchomieniowego

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\":\"Krzysztof\",\"country\":\"PL\"}", 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.
}

Aplikacja konsolowa .NET 8+. Użyj jako Program.cs w projekcie konsolowym, a następnie uruchom dotnet run. Dokumentacja środowiska uruchomieniowego

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\":\"Krzysztof\",\"country\":\"PL\"}"
    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+; biblioteka standardowa. Zapisz jako main.go i uruchom go run main.go. Dokumentacja środowiska uruchomieniowego

Przykładowa odpowiedź

To prawdziwa odpowiedź pobrana 1 października 2026 r. z użyciem klucza API; zastąpiono jedynie saldo konta. Nie jest miarą dokładności, a zapytanie na żywo może zwrócić inny wynik. Zapytania z kluczem API zwracają meta.access.mode: api_key oraz null w polach limitu dotyczących wyłącznie próby; zapytania w ramach próby dla adresu IP zwracają ip_trial. Wynik wnioskowania odczytasz w data, a wynik rozliczenia operacji w meta.usage.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Krzysztof",
      "country": "PL"
    },
    "name": "krzysztof",
    "gender": "male",
    "country": "PL",
    "confidence": 0.9928131416837782,
    "confidence_kind": "observed_frequency",
    "sample_count": 974,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "krzysztof",
      "method": "normalized",
      "scope": "country",
      "country": "PL"
    }
  },
  "meta": {
    "request_id": "a03ce9f1-da34-4c69-9dac-363e861f9ade",
    "duration_ms": 11,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Pola odpowiedzi i pewność

Pola odpowiedzi z prognozą

Pole	Typ	Dopuszcza null	Przykład	Opis
`data.input`	`object`	Nie	`{"type":"name","value":"Krzysztof","country":"PL"}`	Typ danych wejściowych, wartość i kraj. forceToGenderize jest dołączane, gdy ma wartość true.
`data.name`	`string`	Tak	`"krzysztof"`	Dopasowane lub wyodrębnione imię; null, gdy nie jest dostępne.
`data.gender`	`string`	Tak	`"male"`	male, female lub JSON null. To wynik wnioskowania, a nie zweryfikowana tożsamość osoby.
`data.result_status`	`string`	Nie	`"identified"`	identified, gdy zwrócono płeć; w przeciwnym razie unknown.
`data.reason`	`string`	Tak	`null`	null dla wyników identified. Powody wyniku nieznanego: not_found, no_name_candidate, ambiguous lub insufficient_evidence.
`data.confidence`	`number`	Tak	`0.95`	Wynik w skali 0–1 lub null. Gdy płeć ma wartość null, pewność również jest null.
`data.confidence_kind`	`string`	Tak	`"observed_frequency"`	observed_frequency: liczba wystąpień dominującej płci podzielona przez sumę w wybranym wierszu zbioru danych. model_reported: wynik AI, a nie skalibrowane prawdopodobieństwo. null, gdy wartość jest niedostępna.
`data.sample_count`	`integer`	Tak	`1200`	Wielkość próby w zbiorze danych lub null. AI nie wymyśla liczby próbek.
`data.source`	`string`	Nie	`"dataset"`	dataset, ai lub none.
`data.country`	`string`	Tak	`"PL"`	Powiązanie z krajem pochodzące z dataset lub ai_association albo null. Nie określa obywatelstwa, miejsca zamieszkania ani pochodzenia etnicznego.
`data.country_source`	`string`	Tak	`"dataset"`	Źródło powiązania z krajem: dataset, ai_association lub null.
`data.match`	`object`	Nie	`{"name":"krzysztof","method":"normalized","scope":"country","country":"PL"}`	Dopasowane imię ze zbioru danych, metoda (normalized, token, substring lub model_inference), zakres country lub global oraz dopasowany kraj. Niedostępne informacje o dopasowaniu mają wartość null.

Metadane dostępu, rozliczenia i zapytania

Pole	Typ	Dopuszcza null	Przykład	Opis
`meta.request_id`	`string`	Nie	`"550e8400-e29b-41d4-a716-446655440000"`	Unikalny identyfikator tej próby HTTP; wysyłany także w X-Request-ID.
`meta.duration_ms`	`integer`	Nie	`42`	Czas przetwarzania zapytania w milisekundach.
`meta.access.mode`	`string`	Nie	`"api_key"`	api_key, ip_trial lub unauthenticated. Korzystając z płatnego konta, sprawdź api_key.
`meta.access.reason`	`string`	Tak	`null`	Powód przejścia na próbę: api_key_missing, api_key_invalid lub api_key_not_found; w pozostałych przypadkach null.
`meta.usage.charged_credits`	`integer`	Tak	`1`	Liczba pobranych kredytów netto. Zero przed pobraniem lub po potwierdzonym pełnym zwrocie; null, gdy rozliczenie jest niepotwierdzone.
`meta.usage.remaining_credits`	`integer`	Tak	`99`	Saldo po zakończeniu operacji. Może być ujemne; null, gdy saldo jest niedostępne lub rozliczenie jest niepotwierdzone.
`meta.usage.billing_status`	`string`	Nie	`"confirmed"`	not_charged, confirmed lub unconfirmed. Sprawdź to pole przed ponowieniem nieudanej prognozy.
`meta.usage.resets_at`	`string`	Tak	`"2026-09-27T12:00:00.000Z"`	Czas odnowienia próby dla adresu IP w UTC (ISO 8601); null dla kont z kluczem API lub gdy nie jest znany.
`meta.usage.limit`	`integer`	Tak	`10`	Limit kredytów próby dla adresu IP; null dla kont z kluczem API.
`meta.usage.period_seconds`	`integer`	Tak	`86400`	Okres próby dla adresu IP w sekundach; null dla kont z kluczem API.

Kontekst kraju i nieznane imiona

Podawaj kraj (country) tylko wtedy, gdy masz istotny kontekst. API może wybrać wiersz zbioru danych dla konkretnego kraju lub przejść na wiersz globalny. data.match.scope pokazuje, który został wybrany; zwrócony kraj nie oznacza, że dana osoba w nim mieszka.

Domyślnie pojedyncze zapytanie przechodzi na AI, co kosztuje łącznie 1 kredyt. Aby korzystać tylko ze zbioru danych, wyślij options: {"ai_mode": "off"}. Nierozstrzygnięte dane wejściowe mogą zwrócić gender: null i nadal podlegają opłacie, jeśli operacja zakończy się powodzeniem. Imię i nazwisko może zostać dopasowane do jednego ze składników; data.match zawiera wybranego kandydata i metodę dopasowania.

W przypadku wartości name przypominających pseudonim forceToGenderize: true pozwala na wnioskowanie bez prawdziwego imienia: wynik rozstrzygnięty w zbiorze danych kosztuje 1 kredyt, a w przeciwnym razie AI uwzględniająca pseudonimy kosztuje łącznie 2 kredyty. Wystarczy dodatnie saldo początkowe, a saldo końcowe może być ujemne.

Wyszukiwanie po imieniu i nazwisku bez zakładania, że liczy się pierwsze słowo

Wyślij imię i nazwisko w oryginalnej postaci Unicode. Dopasowanie w zbiorze danych stosuje normalizację NFKC, zamianę na małe litery i wyodrębnianie składników, więc nie musisz zamieniać imienia na ASCII. Spośród dostępnych kandydatów API wybiera rekord o największej zapisanej łącznej liczbie wystąpień. Może to być dalszy składnik imienia i nazwiska, dlatego nie zakładaj, że wybrane zostało pierwsze słowo ani imię.

To zapytanie korzystające tylko ze zbioru danych ułatwia sprawdzenie, na jakiej podstawie wybrano wynik. Odczytaj data.input.value, aby zobaczyć przesłane imię i nazwisko, data.match.name, aby poznać wyszukiwanego kandydata, oraz data.match.method, aby poznać metodę dopasowania. Przykład nie gwarantuje określonej płci ani wybranego składnika. Kandydaci ze zbioru danych muszą mieć więcej niż dwa znaki, więc krótkie dane wejściowe mogą pozostać nierozstrzygnięte. Włącz standardowe przejście na AI, jeśli taka dodatkowa inferencja jest odpowiednia dla Twojej aplikacji.