# Určení pohlaví z e-mailové adresy

> Využijte jmenný signál v e-mailové adrese s GenderAPI.io V2. Vyzkoušejte vyhledání v reálném čase, porovnejte možnosti datové sady a AI a zjistěte, jak zacházet s neznámými výsledky a hromadnými seznamy e-mailových adres.

Canonical HTML: https://www.genderapi.io/cs/determine-gender-from-email

Last reviewed: 2026-09-30

## Co může prozradit e-mailová adresa?

Pošlete syntakticky platnou e-mailovou adresu s type: email. GenderAPI.io hledá jmenný signál v části před @ a potom vrátí strukturovaný odhad. Neověřuje schránku, neidentifikuje jejího vlastníka ani neurčuje genderovou identitu této osoby.

Shoda v datové sadě získává kandidáty z částí adresy a může zkoušet omezený počet podřetězců. Režim přezdívek zachovává shodu celých částí, ale tyto kandidáty z podřetězců nepřidává. Pokud se shoduje více záznamů, vybere se kandidát s nejvyšším uloženým celkovým počtem; nemusí to být zamýšlené křestní jméno. Než získané jméno použijete v záznamu kontaktu, zkontrolujte data.name a data.match.

| Příklad vstupu | Jak ho vyložit |
| --- | --- |
| `alice.smith@example.com` | Lokální část obsahuje možné části jména. Shoda je možná, ale samotný vstup neurčuje, který kandidát bude vybrán. |
| `alice+news@example.com` | Vyhledávání v datové sadě pro své kandidáty odstraní příponu za znakem plus. AI dostane pokyn ji ignorovat, obdrží však odeslanou hodnotu. |
| `support@example.com` | Rolová adresa neposkytuje spolehlivý signál osobního jména. Celé sdílené schránce nepřiřazujte pohlaví jedné osoby. |
| `prenses@example.com` | Volitelné forceToGenderize umožní pokus podle významu přezdívky, pokud datová sada nepřinese výsledek. V tomto režimu skutečné jméno není potřeba. |
| `not-an-email` | Neplatná syntaxe vrátí chybu validace, nikoli úspěšný neznámý výsledek. |

## Odešlete vyhledání e-mailu ze své aplikace

Příklad používá váš stávající API klíč v hlavičce Bearer a explicitní fallback. Ukázkovou adresu nahraďte vstupem, který smíte zpracovávat. country uvádějte jen tehdy, když máte relevantní kontext; e-mailová doména neurčuje, kde se osoba nachází. Bez kontextu země toto pole vynechte.

Příklad spusťte na svém serveru s nastaveným GENDERAPI_API_KEY. Díky POST zůstane e-mailová adresa mimo URL požadavku. Výsledek v reálném čase se může lišit od ilustrativní odpovědi v ukázce.

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.

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í.

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.

**cURL**

cURL 7.76+ v shellu POSIX. Spusťte v terminálu.

```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": "email",
  "value": "alice.smith@example.com",
  "country": "US",
  "options": {
    "ai_mode": "fallback"
  }
}'
```

**JavaScript / Node.js**

Node.js 22+; vestavěné fetch. Uložte jako example.mjs a spusťte 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": "email",
  "value": "alice.smith@example.com",
  "country": "US",
  "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+; standardní knihovna. Uložte jako example.py a spusťte 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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"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+ s rozšířením cURL. Uložte jako example.php a spusťte php example.php.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"email","value":"alice.smith@example.com","country":"US","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+; standardní HTTP klient. Uložte jako GenderApiExample.java a spusťte 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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"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**

Konzolová aplikace .NET 8+. Použijte jako Program.cs v konzolovém projektu a potom spusťte 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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"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+; standardní knihovna. Uložte jako main.go a spusťte 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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"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)
    }
}
```

- [Úplná reference V2 pro e-mailové adresy](https://www.genderapi.io/cs/docs/v2/gender-from-email)

## 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.

| Pole | Jak ho použít |
| --- | --- |
| `data.gender / data.result_status` | male nebo female používejte jen u výsledku identified. U neznámého výsledku zachovejte původní hodnotu JSON null. |
| `data.name / data.match` | Zkontrolujte 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_kind` | Spolehlivost 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_count` | Rozlišujte dataset, ai a none. Výsledky AI nemají uloženou velikost vzorku. Velikost vzorku není naměřená přesnost. |
| `meta.access.mode` | V 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. |

- [Pole odpovědi a neznámé výsledky](https://www.genderapi.io/cs/docs/v2/responses)
- [Vysvětlení přesnosti a spolehlivosti](https://www.genderapi.io/cs/accuracy-methodology)
- [Zdroje dat a datovaný profil datové sady](https://www.genderapi.io/cs/data-provenance)

## 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žadavku | Chování | Kredity za úspěšné vyhledání |
| --- | --- | --- |
| options.ai_mode: off | Použije pouze datovou sadu. | 1, včetně neznámého výsledku |
| options.ai_mode: fallback | Nejprve 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: always | Použije přímo AI. | 2 |
| forceToGenderize: true | Nejprve 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 |

- [Možnosti AI a analýza přezdívek](https://www.genderapi.io/cs/docs/v2/ai-options)
- [Kredity a využití](https://www.genderapi.io/cs/docs/v2/credits-and-usage)

## Zpracujte seznam e-mailových adres v dávkách

Použijte POST /api/v2/gender/batch s polem items obsahujícím položky s type: email. Přístup s registrovaným API klíčem podporuje až 50 položek, zkušební režim podle IP až 10. Každé položce ponechte jedinečné id, abyste mohli výsledky přiřadit zpět k původnímu řádku. Odpověď navíc zachovává pořadí vstupů a uvádí index.

Položky dávky mají ve výchozím nastavení režim pouze s datovou sadou. U každé položky, která potřebuje běžnou záložní AI, nastavte options.ai_mode: fallback. Dvě úspěšné položky s fallback stojí celkem 2 kredity, a to i při neznámých výsledcích; jeden požadavek HTTP neznamená jeden kredit za odhad.

Kontrolujte každou položku, i když dávka vrátí HTTP 200. Uložte úspěšné i neznámé výsledky a teprve po kontrole chyb a potvrzeného účtování znovu odešlete neúspěšné položky. Po vypršení časového limitu neposílejte celou úspěšnou dávku znovu, aniž byste zkontrolovali výsledek účtování.

- [Příklady, limity a částečná selhání dávek](https://www.genderapi.io/cs/docs/v2/batch)

## 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.

- [Zásady ochrany osobních údajů](https://www.genderapi.io/cs/privacy-policy)
- [Smlouva o zpracování osobních údajů](https://www.genderapi.io/cs/data-processing-agreement)
- [Další zpracovatelé](https://www.genderapi.io/cs/subprocessors)

## Dokáže API získat z e-mailové adresy křestní jméno?

Pokud lokální část obsahuje použitelný signál, může vrátit kandidáta na jméno. Možná je shoda celých částí i podřetězců, proto zkontrolujte data.match. Výsledek nedokazuje křestní jméno vlastníka schránky.

## Vrátí adresa jako info@ nebo support@ pohlaví?

Sdílené rolové adresy obvykle neposkytují žádné podklady pro osobní jméno. Neznámý výsledek je platný. AI ani režim přezdívek nepovažujte za ověření osob, které sdílenou schránku používají.

## Stojí neznámý výsledek pro e-mailovou adresu kredity?

Ano. Úspěšné běžné vyhledání e-mailové adresy stojí 1 kredit, včetně záložní AI a neznámých výsledků. Vynucená analýza přezdívek stojí 1 kredit za výsledek z datové sady, nebo celkem 2 kredity, pokud se použije AI. U chyb je výsledek účtování uveden zvlášť v meta.usage.

## Odstraní se e-mailová doména před zpracováním pomocí AI?

Takové odstranění se neslibuje. Kandidáti z datové sady pocházejí z lokální části, zatímco AI obdrží odeslanou hodnotu s pokynem ignorovat doménu a příponu za znakem plus. Pokud to váš postup vyžaduje, použijte režim pouze s datovou sadou.