Nápověda ke GenderAPI.io V2
Časté dotazy
Odpovědi k požadavkům V2, spolehlivosti, neznámým výsledkům, kreditům, ochraně soukromí a vašemu účtu. Pokud provozujete integraci s předchozí verzí, použijte dokumentaci V1.
Výsledky a spolehlivost
Porozumějte odhadům a jejich omezením
Kontext země, míra spolehlivosti a neznámé výsledky v API V2.
Určuje výsledek GenderAPI pohlaví konkrétní osoby?
Ne. GenderAPI odhaduje pohlaví ze signálů spojených se jménem, nebo při zapnuté volbě ze signálů v přezdívce. Odhad není ověřený údaj o osobě. Zachovejte nejistotu, respektujte genderovou identitu, kterou osoba sama uvádí, a nečiňte rozhodnutí se závažnými důsledky pouze na základě tohoto odhadu.
Jak kontext země ovlivňuje výsledek?
Volitelný kód země ISO velkými písmeny dodá požadavku regionální kontext. Odesílejte jej jen tehdy, když je země relevantní a známá. Stejné jméno se může v různých regionech používat odlišně; vrácená země popisuje vztah ke jménu a nedokládá státní občanství ani bydliště.
Co znamená míra spolehlivosti ve V2?
confidence je hodnota od 0 do 1, nebo null, pokud hodnota není k dispozici. Čtěte ji spolu s confidence_kind: observed_frequency je počet převažující kategorie v datové sadě vydělený celkovým počtem; model_reported je hodnota, kterou uvedla AI. Tyto hodnoty nejsou kalibrované pravděpodobnosti pro konkrétní osobu ani změřená přesnost produktu. Prahy pro ruční kontrolu nastavte podle reprezentativních dat.
Co znamená gender: null a účtuje se takový výsledek?
Úspěšný výsledek V2 s gender: null znamená, že dostupné signály nestačily k určení pohlaví. Jde o nativní hodnotu null formátu JSON, nikoli o řetězec "null". Úspěšný neznámý výsledek se účtuje podle ceny zvoleného režimu. Považujte jej za neznámý; chyba poskytovatele nebo požadavku je samostatný chybový případ.
Mohu odesílat jména v různých písmech?
Ano. Odesílejte jména v Unicode s původními znaky a významovou diakritikou a zachovejte česká písmena jako č, ř, ž nebo ů. Pokrytí a spolehlivost závisejí na jménu, regionu a dostupných signálech. Proto otestujte reprezentativní vzorek písem a zemí, se kterými vaše aplikace pracuje.
API a AI
Zvolte typ požadavku a nastavení AI
Typy požadavků ve V2, dávkové požadavky, použití AI a limity.
Mohu v jednom dávkovém požadavku analyzovat jména, e-mailové adresy a uživatelská jména?
Ano. POST /api/v2/gender/batch přijímá až 50 položek s API klíčem nebo až 10 ve zkušebním režimu podle IP. Každá položka má vlastní pole type a value, volitelné country a vlastní nastavení AI. Ve výchozím nastavení je AI u položek dávkového požadavku vypnutá. Kontrolujte každý výsledek: dávkový požadavek může vrátit HTTP 200, i když některé položky selhaly. Kredity se odečítají za každou úspěšně zpracovanou položku, včetně neznámých výsledků.
Jak funguje požadavek s e-mailovou adresou?
Použijte type: email s platnou adresou. API hledá použitelný signál jména v místní části před znakem @; doména o identitě ani zemi osoby nic neříká. Sdílené schránky a adresy bez signálu jména mohou vrátit neznámý výsledek. Jednotlivý požadavek ve výchozím nastavení použije AI, pokud datová sada výsledek neposkytne.
Jak funguje požadavek s uživatelským jménem?
Použijte type: username. Běžný požadavek hledá rozpoznatelné jméno v uživatelském nebo zobrazovaném jménu. Abstraktní přezdívky mohou vrátit neznámý výsledek. Zapněte forceToGenderize, pokud chcete, aby se po neúspěšném hledání v datové sadě použila AI s analýzou přezdívek; pohlaví pak lze určit i bez extrakce skutečného jména.
Kdy V2 používá AI?
Jednotlivé požadavky ve výchozím nastavení používají options.ai_mode: fallback: nejprve se hledá v datové sadě, a pokud pohlaví nelze určit, použije se AI, celkem za 1 kredit. off používá pouze datovou sadu, za 1 kredit; always datovou sadu přeskočí a použije AI, za 2 kredity. Položky dávkového požadavku mají ve výchozím nastavení off a AI mohou zapnout jednotlivě. Žádný z režimů nezaručuje výsledek jiný než null.
Co dělá forceToGenderize?
Tento volitelný příznak funguje se jmény, e-mailovými adresami i uživatelskými jmény, a to i u jednotlivých položek dávkového požadavku. Výsledek určený z datové sady stojí 1 kredit. Jinak se použije AI s analýzou přezdívek, celkem za 2 kredity, i když úspěšný výsledek zůstane neznámý. Skutečné jméno není potřeba. Vynechte ai_mode nebo použijte fallback; v kombinaci s off nebo always vrátí API chybu 422.
Jak se ve V2 odečítají kredity?
Skutečně odečtené kredity za operaci najdete v meta.usage.charged_credits a v billing_status zjistíte, zda bylo odečtení potvrzeno. Běžné odhady z datové sady a v režimu fallback stojí 1 kredit za každou úspěšně zpracovanou položku; always a AI s analýzou přezdívek stojí 2 kredity. Dokončené ověření telefonního čísla stojí 1 kredit, i když je výsledek neplatný. Stačí kladný počáteční zůstatek, takže konečné odečtení může zůstatek dostat do záporu. Kredity za neúspěšné odhady se vracejí; nepotvrzené odečtení musí prověřit podpora.
Má V2 limity počtu požadavků?
Ano. Aktuální výchozí hodnoty jsou 120 požadavků za minutu na účet, 600 požadavků za minutu na IP adresu a 2 souběžné operace na účet. Kromě toho platí sdílená kapacita služby. Požadavky POST jsou omezeny na 64 KiB; dávkové požadavky přijímají 50 položek s klíčem nebo 10 ve zkušebním režimu podle IP. Zpracujte HTTP 429 a Retry-After a nepředpokládejte, že požadavky v rámci těchto limitů budou vždy přijaty.
Mohu zopakovat požadavek, který selhal nebo vypršel?
Každý požadavek na odhad je nová operace a účtuje se běžným způsobem. Vypršení časového limitu nebo ztracená odpověď nedokazují, že kredity nebyly odečteny. Před dalším pokusem zkontrolujte billing_status; pokud odečtení není potvrzeno, kontaktujte podporu a uveďte request_id. U částečně neúspěšného dávkového požadavku po potvrzení odečtení znovu odešlete pouze neúspěšné položky. Při odpovědi 429 se řiďte hlavičkou Retry-After.
Kde najdu ukázky kódu a nástroje pro V2?
Průvodci V2 obsahují ukázky v cURL, JavaScriptu, Pythonu, PHP, Javě, C# a Go. Swagger a Postman používají stejnou specifikaci V2. Zvolte typ vstupu a API klíč uchovávejte v konfiguraci na straně serveru.
Mohu dál používat V1?
Ano. Stávající integrace V1 si zachovávají své endpointy a formáty odpovědí. V1 a V2 používají stejný API klíč a stejný zůstatek, liší se však pole požadavků, odpovědi a chyby. K údržbě stávajícího klienta použijte samostatnou dokumentaci V1 a při přechodu na V2 průvodce migrací.
Soukromí a soubory
Jak se zpracovávají data
Kde najdete aktuální informace o zpracování, uchovávání a mazání dat.
Ukládají se úspěšné požadavky na GenderAPI?
Zásady ochrany osobních údajů vysvětlují, která data požadavků, provozní data a bezpečnostní protokoly se mohou ukládat, k jakým účelům se zpracovávají a jak se mažou. Ověřte si tyto informace pro svou integraci a neodesílejte zbytečné osobní údaje.
Ukládají se e-mailové adresy z požadavků?
Zásady ochrany osobních údajů popisují, jak se zachází s e-mailovými adresami z požadavků a se souvisejícími technickými daty. E-mailová adresa může být osobním údajem: odesílejte jen to, co požadavek vyžaduje, a úplné adresy neukládejte do vlastních diagnostických protokolů.
Jak dlouho se uchovávají nahrané soubory Excel nebo CSV?
Uchovávání, mazání a zálohování nahraných souborů stanovují zásady ochrany osobních údajů. Exportujte výsledky, které potřebujete, a soubor smažte pomocí funkcí pracovního prostoru, jakmile jej už nepotřebujete. S dotazy k požadavkům vaší organizace na uchovávání dat se obraťte na podporu.
Mohou data požadavků nebo nahrané soubory zpracovávat poskytovatelé služeb?
Zásady ochrany osobních údajů a informace o dalších zpracovatelích popisují, jak poskytovatelé služeb zpracovávají data a jaká ochranná opatření platí. Při posuzování, kde se vaše data zpracovávají, projděte tyto dokumenty a případné smlouvy, které se na váš účet vztahují.
Zásady ochrany osobních údajů →Další zpracovatelé →Informace o GDPR →
Účet a podpora
Připojte klíče a spravujte účet
Bezplatné použití, autentizace, kontrola zůstatku a podpora.
Mohu GenderAPI vyzkoušet zdarma?
Ano. Registrovaný bezplatný účet získává 200 kreditů denně. Nezávisle na tom poskytuje zkušební režim podle IP ve V2 bez klíče 10 kreditů na veřejnou IP adresu každých 24 hodin; tento zůstatek se sdílí s V1 a s dalšími uživateli stejné IP adresy. V obou případech platí běžné ceny; počet kreditů nemusí vždy odpovídat počtu HTTP požadavků.
Jak autentizovat požadavky a chránit API klíč?
V důvěryhodném kódu na straně serveru použijte Authorization: Bearer YOUR_API_KEY; požadavky POST navíc vyžadují Content-Type: application/json. Skutečný klíč nevkládejte do kódu pro prohlížeč, veřejných repozitářů ani protokolů. Chybějící klíče, klíče s neplatným formátem nebo nerozpoznané klíče mohou vést ke zkušebnímu režimu podle IP; proto ověřte, že meta.access.mode má hodnotu api_key. Rozpoznané klíče, které jsou deaktivované, jejichž platnost vypršela nebo které jsou omezené, do zkušebního režimu nepřecházejí.
Jak zkontroluji zbývající kredity?
Zavolejte GET /api/v2/usage se svým klíčem v hlavičce Bearer. Tato kontrola zůstatku je bezplatná a vrací data.remaining_credits. Bez klíče se načte sdílený zůstatek zkušebního režimu podle IP. V1 a V2 používají stejný zůstatek účtu; hodnota remaining_credits v odpovědi s odhadem ukazuje zůstatek v okamžiku dokončení operace.
Kde mohu spravovat nebo zrušit předplatné?
Přihlaste se do aplikace GenderAPI a spravujte předplatné spojené s vaším API klíčem. V aktuálním nastavení účtu najdete svůj tarif i možnosti zrušení.
Kde mohu upravit fakturační údaje?
Fakturační a platební nastavení se spravuje pro každý API klíč nebo předplatné po přihlášení do aplikace GenderAPI.
Jak nahlásit nesprávný výsledek nebo získat pomoc s integrací?
Pošlete podpoře verzi API, endpoint, request_id a krátký reprodukovatelný příklad. Uveďte případný kód chyby, ale odstraňte API klíč a citlivé osobní údaje.
Technická znalostní báze
Průvodce implementací a odpovědným používáním
Odpovědi k výsledkům, ochraně osobních údajů a provozu V2 s odkazy na průvodce a verzí každé odpovědi v Markdownu.
Výsledky, spolehlivost a odpovědné používání
Nerozhodnutý odhad V2 vrací pro gender nativní hodnotu null formátu JSON, nikoli řetězec "null". Jméno může být nejednoznačné nebo dostupné signály nemusejí stačit; pokud jsou k dispozici, zkontrolujte result_status a reason. Neznámý výsledek zachovejte a nenuťte jej do žádné kategorie. Úspěšný odhad bez výsledku se účtuje podle ceny zvoleného režimu. Chyby požadavku nebo poskytovatele jsou samostatné chybové případy; údaje o odečtení kreditů najdete v meta.usage.
Přečíst celou odpověď →Jak se hodnotí přesnost GenderAPI?Smysluplné hodnocení přesnosti uvádí zkoumanou populaci, datum, metodu výběru vzorku, podíl neznámých výsledků a výsledky podle regionu a písma. Aktuální stránka o metodice popisuje protokol hodnocení, nikoli změřenou přesnost v procentech. Pole V2 confidence a confidence_kind vysvětlují, na jakých signálech výsledek stojí; nenahrazují hodnocení na reprezentativních datech.
Přečíst celou odpověď →Zdroje dat, ochrana osobních údajů a soulad s předpisy
Stránka o původu dat popisuje rámec pro dokumentaci kategorií zdrojů, kritérií výběru, licencí a omezení pro regiony a písma. Ověřený seznam zdrojů zatím zveřejněn není. Přečtěte si tuto stránku a pokud má vaše integrace požadavky na zdroje, kontaktujte podporu; nepředpokládejte zdroje, velikosti datových sad ani hodnoty pokrytí, které nejsou zdokumentovány.
Přečíst celou odpověď →Jak často se aktualizují data o jménech?Aktuální stránka o původu dat neuvádí společný harmonogram aktualizací pro všechny záznamy jmen ani pravidla zpracování. Pokud je pro vaše použití důležité, jak aktuální data jsou, zeptejte se podpory na konkrétní datovou sadu nebo proces a otestujte reprezentativní výsledky. Datum revize stránky neznamená, že byly ten den aktualizovány všechny podkladové záznamy.
Přečíst celou odpověď →Kde najdu informace o GDPR a smlouvě o zpracování dat?Zásady ochrany osobních údajů, informace o GDPR, smlouva o zpracování dat a seznam dalších zpracovatelů popisují zveřejněné podmínky zpracování a ochranná opatření. Projděte aktuální dokumenty a případné smlouvy, které se vztahují na váš účet. S dotazy týkajícími se vaší organizace, například k rolím při zpracování, předávání dat nebo žádostem subjektů údajů, se obraťte na GenderAPI; obecná odpověď mezi častými dotazy nenahrazuje platnou smlouvu.
Přečíst celou odpověď →Provoz API, chyby a odečítání kreditů
V důvěryhodném kódu na straně serveru použijte Authorization: Bearer YOUR_API_KEY. Požadavky POST ve V2 navíc vyžadují Content-Type: application/json. GET /api/v2/gender přijímá klíč i jako parametr dotazu, ale s hlavičkou zabráníte tomu, aby se přístupové údaje objevily v URL prohlížeče. Chybějící klíče, klíče s neplatným formátem nebo nerozpoznané klíče mohou vést ke sdílenému zkušebnímu režimu podle IP; v integraci s účtem ověřte, že meta.access.mode má hodnotu api_key. Rozpoznané klíče, které jsou deaktivované, jejichž platnost vypršela nebo které jsou omezené, do zkušebního režimu nepřecházejí.
Přečíst celou odpověď →Jak zacházet s limity počtu požadavků a opakováním?V2 má limity počtu požadavků a souběžných požadavků; zpracujte HTTP 429 a Retry-After. Každý opakovaný odhad je nová operace a účtuje se běžným způsobem. Po vypršení časového limitu, ztracené odpovědi nebo nepotvrzeném odečtení kreditů požadavky automaticky neopakujte. Nejprve zkontrolujte code, action a meta.usage.billing_status; při billing_reconciliation_required kontaktujte podporu a uveďte request_id. Omezený backoff používejte jen tehdy, když je odečtení potvrzeno a zdokumentovaná action další pokus povoluje.
Přečíst celou odpověď →Jak vykládat chyby ve V2?Chyby API V2 používají chybové stavové kódy HTTP a Problem Details podle RFC 9457 se stabilními poli code a action. Zpracování chyb stavte na těchto polích místo porovnávání textu v detail a request_id si uschovejte pro podporu. Úspěšný neznámý výsledek není chyba. Odpovědi na dávkové požadavky mohou obsahovat chyby jednotlivých položek, i s HTTP 200. Proxy může vrátit chybu v jiném formátu než JSON a ztracená nebo nečitelná odpověď nedokazuje, že nebyly odečteny žádné kredity.
Přečíst celou odpověď →Jak zkontroluji zbývající kredity?Z důvěryhodného kódu na straně serveru zavolejte GET /api/v2/usage s API klíčem v hlavičce Bearer. Tento požadavek je bezplatný a vrací data.remaining_credits; bez klíče se načte zůstatek sdíleného zkušebního režimu podle IP. V1 a V2 používají stejný zůstatek účtu. Pole meta.usage v odpovědi s odhadem ukazuje cenu operace a zůstatek v okamžiku jejího dokončení a při souběžných požadavcích se může měnit. Přístupové údaje nedávejte do protokolů a kontrolu zůstatku nepovažujte za důkaz, že konkrétní požadavek se ztracenou odpovědí nebyl zaúčtován.
Přečíst celou odpověď →Jak přejít z V1 na V2 bez výpadku?Nové integrace stavte na V2 a stávající klienty V1 nechte používat jejich zdokumentované endpointy, dokud nebudete chtít přejít na V2. Obě verze používají stejné API klíče a stejné kredity, liší se však pole požadavků, struktura odpovědí a formát chyb. Postupujte podle průvodce migrací, otestujte úspěšné i neznámé výsledky a chyby a před změnou endpointu upravte zpracování odpovědí. Dokumentace V1 zůstává k dispozici pro stávající integrace.
Přečíst celou odpověď →Jak rozpoznat chyby a sledovat dostupnost služby?Když požadavky selžou, pomocí vráceného kódu chyby rozlište provozní výpadky, neplatné vstupy, problémy s přístupem k účtu, vyčerpané kredity a limity počtu požadavků. Ve své integraci sledujte podíl úspěšných požadavků a doby odezvy. Při nevysvětlitelné chybě nebo nejasném odečtení kreditů kontaktujte podporu a uveďte request_id. Tvrzení o dostupnosti opírejte o měření; tato odpověď neuvádí žádnou zaručenou dostupnost v procentech.
Přečíst celou odpověď →Potřebujete další pomoc?
Pošlete nám reprodukovatelný příklad
Uveďte endpoint, parametry požadavku a vrácenou chybu, ale neposílejte produkční API klíč ani citlivé osobní údaje.