GenderAPI.io V2: odpovědi JSON a spolehlivost

Porozumějte odpovědi JSON

Úspěšné jednotlivé odpovědi obsahují data a meta. Následující příklad z datové sady je skutečná odpověď získaná 1. října 2026 s API klíčem; nahrazen byl pouze zůstatek účtu. Nepředstavuje naměřenou přesnost produktu a požadavek v reálném čase může vrátit jiný výsledek. Požadavky s API klíčem vracejí 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 spolu s limitem zkušebního režimu a časem jeho obnovení.

{
  "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
    }
  }
}

• Úplná schémata odpovědí a příklady dávek

Pole odpovědi s odhadem

Vrácená vstupní pole

Pole shody v datové sadě

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

Úspěšný neznámý výsledek

HTTP 200 znamená, že operace byla dokončena; pohlaví nezaručuje. Zachovejte JSON null a nepřevádějte ho na male, female, prázdný řetězec ani nulovou spolehlivost. data.result_status a data.reason kontrolujte odděleně od chyb HTTP.

Tento skutečný příklad pouze s datovou sadou, získaný 1. října 2026, vrací source: none a reason: not_found a přesto stojí 1 kredit. Řádek datové sady se shodnými počty může vrátit reason: ambiguous se zachovaným sample_count. Neznámý výsledek AI používá source: ai a reason: insufficient_evidence.

{
  "data": {
    "input": {
      "type": "name",
      "value": "zzzxxyy",
      "country": null
    },
    "name": null,
    "gender": null,
    "country": null,
    "confidence": null,
    "confidence_kind": null,
    "sample_count": null,
    "source": "none",
    "result_status": "unknown",
    "reason": "not_found",
    "country_source": null,
    "match": {
      "name": null,
      "method": null,
      "scope": null,
      "country": null
    }
  },
  "meta": {
    "request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
    "duration_ms": 10,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Interpretace spolehlivosti a podkladů shody

Spolehlivost 0,9 je na stupnici 0–1. U observed_frequency znamená dominantní počet vydělený celkovým počtem ve vybraném záznamu datové sady; nejde o naměřenou celkovou přesnost produktu. Skóre model_reported poskytuje AI a není kalibrováno podle četností v datové sadě.

Prahovou hodnotu pro svou aplikaci zvolte na základě vlastních hodnoticích dat a confidence_kind. Skóre z datové sady a z AI přímo neporovnávejte, jako by měřila totéž. U AI mají match.name, match.scope a match.country hodnotu null, protože nebyl vybrán žádný řádek datové sady; match.method je model_inference.

U celých jmen může výsledek z datové sady pocházet z jedné části jména, ne z celého řetězce. data.input zachovává odeslanou hodnotu; data.name popisuje vrácené jméno a data.match kandidáta a rozsah vyhledávání.

Rozhodněte, co má vaše aplikace udělat dál

Nejprve zpracujte chyby požadavku a jednotlivých položek a potom zkontrolujte result_status. U jednotlivého odhadu čtěte data; u dávky použijte stejné rozhodnutí na data každé úspěšné položky. Neznámé výsledky v aplikaci zachovejte a nevynucujte místo nich označení male nebo female.

• Rozlišujte provozní selhání od neznámých výsledků
• Použijte tato rozhodnutí u dávky

Zvolte prahové hodnoty na základě vlastního vyhodnocení

Neexistuje univerzální hranice spolehlivosti, díky které by byl odhad správný. observed_frequency a model_reported vyhodnocujte zvlášť na reprezentativních, nezávisle označených příkladech z vašeho použití. Četnost v datové sadě a skóre, které uvádí sama AI, jsou různé signály, i když mají obě hodnotu 0,9. Měřte, jak často vaše pravidlo vrací odpověď a jak často jsou tyto odpovědi správné; pro vše ostatní ponechte neznámý výsledek nebo ruční kontrolu.

Pokud je například result_status identified, ale confidence_kind je model_reported, použijte pravidlo vyhodnocené pro AI, nikoli prahovou hodnotu pro datovou sadu. Pokud bylo použito forceToGenderize, je name: null spolu s pohlavím jiným než null platné: alias lze vyložit i bez získání skutečného křestního jména. Zda odhad přinesl odpověď, posuzujte podle gender a result_status, ne jen podle name. Stále jde o odhad, nikoli o ověření identity osoby.

• Metriky vyhodnocení a omezení spolehlivosti
• Profil datové sady a hranice podkladů
• Analýza přezdívek a name s hodnotou null

Související průvodci

• Dávková odpověď a chyby jednotlivých položek
• Stav účtování a zbývající kredity
• Kompatibilita odpovědí a opakování požadavků