# Określanie płci na podstawie arabskich imion

> Wypróbuj imiona zapisane pismem arabskim z GenderAPI.io V2. Przed integracją poznaj wpływ znaków diakrytycznych, dopasowanie imienia i nazwiska, kontekst kraju, przejście na AI i wyniki unknown.

Canonical HTML: https://www.genderapi.io/pl/determine-gender-from-arabic-names

Last reviewed: 2026-09-28

## Zachowaj arabską pisownię i sprawdź dopasowane imię

Wyślij imię w oryginalnej pisowni Unicode. Pole tego narzędzia wyświetla tekst arabski od prawej do lewej, a polski przewodnik i JSON pozostają zapisane od lewej do prawej. Nie trzeba wcześniej transliterować imienia na alfabet łaciński. To, że API przyjmuje taki zapis, nie gwarantuje, że w zbiorze danych istnieje odpowiedni rekord.

Wyszukiwanie w zbiorze danych stosuje normalizację Unicode NFKC i dzieli tekst na składniki. Nie zawiera ogólnej reguły usuwania arabskich znaków diakrytycznych ani równoważności różnych zapisów. Oznaczenia samogłosek i inne różnice w pisowni mogą więc wpłynąć na to, który zapisany rekord zostanie znaleziony. Zachowaj oryginalną wartość, zamiast traktować wszystkie warianty jako identyczne.

Imię i nazwisko może dać kilku kandydatów. Wybierany jest dostępny rekord o największej zapisanej łącznej liczbie wystąpień, więc pierwsze słowo nie musi być zwróconym imieniem. Zanim użyjesz wyniku do wzbogacenia rekordu, sprawdź data.name i data.match.name.

| Przykładowe dane wejściowe | Co przedstawia | Co sprawdzić |
| --- | --- | --- |
| `ليلى الخطيب` | Przykład imienia i nazwiska | Uwzględnionych może zostać kilka składników. Sprawdź wybrane dopasowanie; ten przykład nie zapowiada żadnego wyniku na żywo. |
| `ليلى / لَيْلَى` | Zapis bez oznaczeń samogłosek i z nimi | Wyślij rzeczywistą pisownię. Nie ma gwarancji, że oba ciągi zostaną dopasowane do tego samego zapisanego rekordu. |
| `Layla / Leila` | Zapisy w alfabecie łacińskim | To odrębne wartości wejściowe. V2 nie gwarantuje automatycznej równoważności transliteracji. |
| `country: SA` | Przykładowy kontekst: Arabia Saudyjska | Ten kontekst nie jest wartością domyślną dla wszystkich społeczności arabskojęzycznych. Jeśli kraj jest nieznany, pomiń country. |

## Świadomie wybierz kontekst kraju SA

Demo wysyła country: SA (Arabia Saudyjska). API nie wybiera tego kraju na podstawie pisma, w którym zapisano imię. W swojej integracji używaj znanego i odpowiedniego kontekstu kraju albo pomiń country. Nie zamieniaj tego przykładu w wartość domyślną dla wszystkich rekordów.

Dla każdego kandydata wyszukiwanie wybiera rekord dla danego kraju, jeśli istnieje, a w przeciwnym razie sprawdza rekord globalny. Następnie wybiera dostępnego kandydata o największej zapisanej łącznej liczbie wystąpień. Rzeczywisty zakres dopasowania sprawdzisz w data.match.scope i data.match.country. Rekord kraju z równymi liczbami wystąpień nie jest automatycznie zastępowany wynikiem globalnym; jeśli włączony jest fallback, zamiast tego może zostać użyta AI.

data.input.country opisuje kontekst wysłany w zapytaniu. data.country i data.country_source opisują zwrócone powiązanie z krajem i jego pochodzenie. To różne pola; nie dowodzą one obywatelstwa, pochodzenia etnicznego ani miejsca zamieszkania.

- [Kontekst kraju i dopasowania](https://www.genderapi.io/pl/docs/v2/gender-from-name#country-evidence-workflow)

## Wyślij zapytanie V2 o imię ze swojej aplikacji

Ustaw zmienną GENDERAPI_API_KEY na swój istniejący klucz i uruchom przykład na swoim serwerze. Zapytanie jawnie włącza standardowe przejście na AI. Pokazuje format zapytania, a nie zmierzoną dokładność ani potwierdzone pokrycie. Aby korzystać tylko ze zbioru danych, użyj options.ai_mode: off.

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.

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.

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.

**cURL**

cURL 7.76+ w powłoce POSIX. Uruchom w terminalu.

```bash
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": "SA",
  "options": {
    "ai_mode": "fallback"
  }
}'
```

**JavaScript / Node.js**

Node.js 22+; wbudowany fetch. Zapisz jako example.mjs i uruchom node example.mjs.

```javascript
// 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": "SA",
  "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.
}
```

**Python**

Python 3.10+; biblioteka standardowa. Zapisz jako example.py i uruchom python3 example.py.

```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\":\"SA\",\"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.
```

**PHP**

PHP 8+ z rozszerzeniem cURL. Zapisz jako example.php i uruchom php example.php.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"ليلى الخطيب","country":"SA","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.
```

**Java**

Java 17+; standardowy klient HTTP. Zapisz jako GenderApiExample.java i uruchom java GenderApiExample.java.

```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\":\"SA\",\"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.
    }
}
```

**C# / .NET**

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

```csharp
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\":\"SA\",\"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.
}
```

**Go**

Go 1.22+; biblioteka standardowa. Zapisz jako main.go i uruchom go run main.go.

```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\":\"SA\",\"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)
    }
}
```

- [Parametry zapytań o imiona](https://www.genderapi.io/pl/docs/v2/gender-from-name)
- [Skonfiguruj klucz API](https://www.genderapi.io/pl/docs/v2/authentication)

## Przechowuj wynik razem z informacjami, na których się opiera

Wywnioskowane powiązanie nie jest płcią zadeklarowaną przez daną osobę. Przechowuj osobno oryginalne dane wejściowe, zwrócone informacje o dopasowaniu i dane przekazane przez samą osobę. Wynik unknown jest prawidłowym wynikiem; nie zamieniaj go w swojej aplikacji na zgadywaną kategorię.

| Pole | Jak z niego korzystać |
| --- | --- |
| `data.gender / data.result_status` | Używaj male lub female tylko wtedy, gdy wynik ma status identified. Gdy wynik jest unknown, zachowaj natywną wartość null z JSON. |
| `data.name / data.match` | Sprawdź zwrócone imię i wybranego kandydata. Dopasowanie fragmentu nie dowodzi, że dane wejściowe należą do osoby o tym imieniu. |
| `data.confidence / data.confidence_kind` | Pewność jest wyrażona w skali 0–1 albo ma wartość null. observed_frequency wynika z zapisanych liczb wystąpień; model_reported to wynik podany przez AI. Progi oceniaj osobno dla każdego rodzaju. |
| `data.source / data.sample_count` | Rozróżniaj dataset, ai i none. Wyniki AI nie mają zapisanej liczby próbek. Liczba próbek nie jest zmierzoną dokładnością. |
| `meta.access.mode` | W integracji z kontem sprawdź, czy wartość to api_key. Brakujący lub nierozpoznany klucz może zamiast tego korzystać ze wspólnej próby dla adresu IP. |
| `meta.usage` | Odczytaj charged_credits i billing_status. Udany wynik unknown jest płatny. Utrata odpowiedzi nie oznacza, że zapytanie było bezpłatne. |

- [Pola odpowiedzi i wyniki unknown](https://www.genderapi.io/pl/docs/v2/responses)
- [Dokładność i pewność wyników](https://www.genderapi.io/pl/accuracy-methodology)
- [Źródła danych i datowany profil bazy danych](https://www.genderapi.io/pl/data-provenance)

## Zdecyduj, kiedy korzystać z AI

forceToGenderize jest opcjonalne dla imion, adresów e-mail i nazw użytkowników. Gdy jest włączone, pomiń ai_mode lub użyj fallback; off i always są z nim sprzeczne i zwracają 422. Dodatnie saldo początkowe wystarcza do rozpoczęcia zapytania, nawet jeśli ostateczne obciążenie obniży saldo poniżej zera.

Tryb pseudonimów może zwrócić płeć razem z name: null. Może też zwrócić wynik unknown. Ani standardowe przejście na AI, ani analiza pseudonimów nie gwarantują poprawnej odpowiedzi ani wartości innej niż null.

| Opcja zapytania | Działanie | Kredyty za udane wyszukiwanie |
| --- | --- | --- |
| options.ai_mode: off | Korzysta tylko ze zbioru danych. | 1, także przy wyniku unknown |
| options.ai_mode: fallback | Najpierw sprawdza zbiór danych, a gdy nie zwróci on płci, korzysta ze standardowej AI. To ustawienie domyślne dla pojedynczych zapytań. | Łącznie 1, łącznie z przejściem na AI |
| options.ai_mode: always | Od razu korzysta z AI. | 2 |
| forceToGenderize: true | Najpierw sprawdza zbiór danych, a potem pozwala AI zinterpretować osobisty pseudonim lub alias, nawet bez prawdziwego imienia. | 1 za wynik rozstrzygnięty w zbiorze danych; łącznie 2, jeśli użyta zostanie AI |

- [Opcje AI i analiza pseudonimów](https://www.genderapi.io/pl/docs/v2/ai-options)
- [Kredyty i zużycie](https://www.genderapi.io/pl/docs/v2/credits-and-usage)

## Przetwarzaj listę imion bez utraty kontekstu

Wyślij do 50 elementów z kluczem API lub 10 w próbie dla adresu IP przez POST /api/v2/gender/batch. Nadaj elementom unikalne id i zachowaj oryginalną wartość każdego wiersza. Każdy element może mieć własne opcje kraju i AI; pomiń kraj, gdy jest nieznany.

W przeciwieństwie do pojedynczych zapytań, które domyślnie korzystają z trybu fallback, elementy partii domyślnie korzystają tylko ze zbioru danych. Ustaw options.ai_mode: fallback w każdym elemencie, który wymaga AI. Sprawdzaj każdy wynik, nawet po HTTP 200, zachowuj wyniki unknown i przed ponownym wysłaniem przejrzyj błędy oraz rozliczenie. Każdy udany standardowy element kosztuje 1 kredyt; jedno zapytanie HTTP z partią to nie jeden kredyt za prognozę.

- [Przykłady partii i częściowe błędy](https://www.genderapi.io/pl/docs/v2/batch#batch-application-workflow)
- [Obsługa wyników unknown w aplikacji](https://www.genderapi.io/pl/docs/v2/responses#application-decisions)

## Wiedz, co wysyłasz

Demo wysyła wpisaną wartość do GenderAPI.io dopiero po kliknięciu Analizuj. Jeśli zostanie użyta AI, przesłane type, value i kontekst kraju trafiają do skonfigurowanej usługi inferencji. Aby uzyskać prognozę wyłącznie ze zbioru danych, użyj w swojej integracji options.ai_mode: off bez forceToGenderize.

Polityka prywatności, umowa powierzenia przetwarzania danych i rejestr podmiotów przetwarzających opisują opublikowane zasady przetwarzania. Wynik jest wywnioskowanym powiązaniem; pierwszeństwo mają informacje przekazane przez samą osobę. Nie opieraj na nim decyzji, które mają istotne skutki dla danej osoby.

- [Polityka prywatności](https://www.genderapi.io/pl/privacy-policy)
- [Umowa powierzenia przetwarzania danych](https://www.genderapi.io/pl/data-processing-agreement)
- [Rejestr podmiotów przetwarzających](https://www.genderapi.io/pl/subprocessors)

## Czy V2 przyjmuje arabskie imiona ze znakami diakrytycznymi?

Przyjmuje imiona w Unicode, w tym tekst zapisany pismem arabskim. Normalizacja zbioru danych co do zasady nie usuwa arabskich oznaczeń samogłosek, dlatego zapisy z oznaczeniami i bez nich mogą dać różne dopasowania albo wynik unknown.

## Czy to narzędzie określa narodowość osoby arabskojęzycznej?

Nie. SA to kontekst kraju wybrany jawnie na potrzeby tej demonstracji. Pismo, powiązanie imienia ani zwrócone pole kraju nie dowodzą narodowości ani miejsca zamieszkania.

## Czy dla tej grupy imion opublikowano niezależną ocenę dokładności?

Ta strona nie publikuje takiej oceny. Przyjęcie danych wejściowych, pokazanie zapisanych liczb wystąpień ani zwrócenie wyniku pewności nie jest niezależnym pomiarem dokładności. Z metodologii dowiesz się, jakie informacje są dostępne i jakie pomiary nie zostały jeszcze opublikowane.

## Czy wynik bez prognozy zużywa kredyty?

Udany wynik unknown jest płatny. Standardowy tryb ze zbiorem danych lub fallback kosztuje łącznie 1 kredyt. Z forceToGenderize zapytanie kosztuje 1 kredyt, jeśli zbiór danych je rozstrzygnie, albo łącznie 2, jeśli użyta zostanie AI, także przy wyniku unknown. Błędy podlegają odrębnym zasadom rozliczania; sprawdź meta.usage.