Dokumentace k API skloňování jmen

Adresa, kterou máte k dispozici:

http://www.jenikkozak.cz/api?klic=klic&pad=5&jmeno=Adelaida

Povinné parametry:

klic: kombinace číslic a písmen, kterými se odlišují dotazy od jednotlivých zákazníků. Klíč získáte při registraci.

pad: číslo označující pád jména, který chcete získat:

• Hodnota „2“ vrátí druhý pád jména (koho, čeho). Novinka
• Hodnota „3“ vrátí třetí pád jména (komu, čemu). Novinka
• Hodnota „4“ vrátí čtvrtý pád jména (koho, co). Novinka
• Hodnota „5“ vrátí pátý pád jména (oslovení).
• Hodnota „6“ vrátí šestý pád jména (kom, čem). Novinka
• Hodnota „7“ vrátí sedmý pád jména (kým, čím). Novinka
• Hodnota „0“ vrátí značku určující pohlaví nositele jména. Značka „f“ označuje ženu, „m“ muže a „mf“ API vrací v případě, že pohlaví nelze určit.

jmeno: občanské jméno psané v latince, jehož tvar chcete získat. Může obsahovat více jmen oddělených svislicí „|“, v takovém případě systém vrátí seznam zpracovaných jmen oddělených týmž znakem. Maximální délka tohoto parametru je 8000 znaků – odpovídá cca 300 kombinacím křestních jmen, příjmení a titulů z českého prostředí (včetně diakritiky).

Nepovinné parametry:

osloveni-zeny: fráze, která bude použita před jménem v případě, že se jedná o ženu. Výchozí hodnotou je „paní“.

osloveni-muze: bude použito na vytvoření tvaru jména muže. Výchozí hodnotou je „pane“.

osloveni-firmy: zadaný řetezec systém vrátí v případě, kdy zjistí, že zadané jméno nenáleží člověku, ale právnické osobě. Výchozí hodnotou je „vážení“. Využívá se pouze při vracení 5. pádu

pohlavi: znáte-li pohlaví nositele jména, uvedením tohoto parametru s hodnotou „1“ (ženské jméno) či „2“ (mužské jméno) můžete zpřesnit výsledek zejména u obourodých jmen. Výchozí hodnotou je „0“ – pohlaví neznámé.

tvar: čtyřciferné číslo, které umožňuje nastavit, které položky skript vrátí. Uvedení počátečních nul je nepovinné.

• Hodnota 1 na prvním místě udává, že bude ignorováno příjmení. (Není-li jedinou součástí zadaného řetězce.) Příklad: Josef Novák bude osloven pane Josefe.
• Hodnota 1 na druhém místě znamená, že budou ignorovány případné tituly. Příklad: Ing. Josef Novák bude osloven pane Josefe Nováku.
  Hodnota 3 na druhém místě použije titul i zbytek jména. Novinka Příklad: Ing. Josef Novák bude osloven pane inženýre Nováku, případně pane inženýre Josefe Nováku místo výchozího pane inženýre.
  Hodnota 4 na druhém místě použije zkratku titulu i zbytek jména. Velikost písmen zkratky i pozice titulu jsou případně opraveny. Novinka Příklad: Ing. Josef Novák bude osloven pane Ing. Nováku místo výchozího pane inženýre.
• Hodnota 1 na třetím místě určuje vypuštění úvodního pane / paní. Příklad: Josef Novák bude osloven Josefe Nováku.
  Hodnota 3 na třetím místě způsobí vypuštění úvodního pane / paní s výjimkou jmen obsahujících titul, který se používá pro oslovení. Novinka Příklad: Josef Novák bude osloven Josefe Nováku, Ing. Josef Novák bude osloven pane inženýre.
• Hodnota 1 na čtvrtém místě způsobí vypuštění křestních jmen. Příklad: Josef Novák bude osloven pane Nováku.
• Výchozí hodnotou je 0001. (≅ 1) Obsahuje-li jméno vědecké či akademické tituly, vytvoří se pořadovaný pád z nich; přidává se úvodní „pane“ / „paní“; křestní jména se při z oslovení vypouštějí, příjmení zůstávají.

Některé hodnoty a příklady vrácených tvarů 5. pádu uvádí následující tabulka:

Tvar	Mgr. Josef Novák	Josef Novák	Novák	Josef	Jana Nováková
1	pane magistře	pane Nováku	pane Nováku	pane Josefe	paní Nováková
0	pane magistře	pane Josefe Nováku	pane Nováku	pane Josefe	paní Jano Nováková
11	magistře	Nováku	Nováku	Josefe	Jano Nováková
10	magistře	Josefe Nováku	Nováku	Josefe	Jano Nováková
30	pane magistře	Josefe Nováku	Nováku	Josefe	Jano Nováková
101	pane Nováku	pane Nováku	pane Nováku	pane Josefe	paní Nováková
100	pane Josefe Nováku	pane Josefe Nováku	pane Nováku	pane Josefe	paní Jano Nováková
111	Nováku	Nováku	Nováku	Josefe	Nováková
110	Josefe Nováku	Josefe Nováku	Nováku	Josefe	Jano Nováková
300	pane magistře Josefe Nováku	pane Josefe Nováku	pane Nováku	pane Josefe	paní Jano Nováková
400	pane Mgr. Josefe Nováku	pane Josefe Nováku	pane Nováku	pane Josefe	paní Jano Nováková
1000	pane magistře	pane Josefe	pane Nováku	pane Josefe	paní Jano
1110	Josefe	Josefe	Nováku	Josefe	Jano
(Tabulka obsahuje pouze některé příklady. Hodnoty na jednotlivých pozicích lze libovolně kombinovat.)

format: s hodnotou „json“ vrátí výsledky ve formátu JSON. V opačném případě systém vrátí text/html.

Chyby:

V případě, že při ohýbání jména dojde k problémům, vrátí server pouze číslo chyby:

• 1: Chybný nebo neuvedený klíč.
  
• 2: V této verzi se nepoužívá.
  
• 3: Byl vyčerpán kredit. Nebo jeho zůstatek neumožňuje zpracování celého zaslaného seznamu jmen.
  
• 4: Parametr pad neobsahuje očekávanou hodnotu.
  
• 5: Parametr jmeno neobsahuje hodnotu.
  
• 6: Chybí některý z povinných parametrů (klíč, pad a jmeno).
  
• 7: Řetězec zadaný v parametru jmeno s největší pravděpodobností není jménem ani fyzické, ani právnické osoby. (Obsahuje například číslice či zavináč.)
• 8: Řetězec zadaný v parametru jmeno je jménem právnické osoby.
  V případě, že je požadován 5. pád, systém vrátí hodnotu nepovinného parametru osloveni-firmy, jehož výchozí hodnotou je „vážení“.

Zjištění technických parametrů účtu:

http://www.jenikkozak.cz/api?klic=klic&informace=2
Tento tvar adresy slouží ke zjišťování údajů o účtu. Její použití je samozřejmě bezplatné.

Použité povinné parametry:

klic: kombinace číslic a písmen, kterými se odlišují dotazy od jednotlivých zákazníků. Klíč získáte při registraci.
informace: kód určující typ získané informace. Může obsahovat tyto hodnoty:

• 1: Vrátí počet zbývajících celých dní, po které je předplacený kredit platný. (Dnešní den není započítán.)
• 2: Zbývající kredit.
• 3: V této verzi se nepoužívá.
• 4: Zbývající denní bezplatný kredit.

Zpracování seznamu jmen

Přes API lze zaslat více jmen oddělených svislicí „|“. Celkový počet takto zaslaných jmen nesmí překročit předplacený kredit.

Dávkové zpracování seznamu jmen

Alternativně můžete využít formulář pro dávkové zpracování seznamu. Rozsah seznamu nesmí překročit výši předplaceného kreditu.