Postup napojení na sklonovani-jmen.cz

Krok 1: Nalezení klíče k API

Po registraci a aktivaci účtu kliknutím na odkaz v zaslaném e-mailu přejděte do Dokumentace. Tam se zobrazí URL obsahující parametr klic s hodnotou, kterou se identifikují vaše požadavky.

Krok 2: Otestování URL API

Kliknutím na odkaz v dokumentaci můžete s pomocí nepovinných parametrů výstup upravit podle svých potřeb. Ve výchozím nastavení bez nepovinných parametrů API využívá nejobvyklejší tvar oslovení.

Krok 3: Zavolání URL z aplikace

Získanou adresu zavolejte ze své aplikace. (V PHP se k tomu hodí sada funkcí cURL.)

Posílejte celé jméno

Přitom je potřeba dát pozor na to, že vstupem je celé jméno skládající se z titulů, křestních jmen a příjmení. Pokud některou z částí jména nechcete ve výstupu použít, deaktivujte ji příslušným parametrem, nikoliv jejím nezasláním. Systém totiž potřebuje celé jméno k tomu, aby mohl správně určit rod. Mnoho částí jmen je obourodých, i když to tak na první pohled nemusí vypadat. Například „Jana Nováková“ je ženské jméno, avšak „Tomáš Jana“ je mužské. Při zaslání pouze části jména se jinak velmi nízká chybovost zvyšuje více než 10×.

Jméno neupravujte

Jméno zasílejte ideálně v původním tvaru. Snahy o normalizaci jmen na straně vývojáře často jména „rozbíjejí“. Například zdánlivě nevinný převod počátečního znaku jména na velké písmeno a ostatních na malá často přepisuje i akademické tituly a komolí jména, která uprostřed obsahují velké písmeno (například MacGregor). Sklonovani-jmen.cz postupuje při úpravách významně citlivěji a zohledňuje původní velikost písmen. U mnoha zahraničních jmen a titulů se může velikost znaků lišit.

Snahy o přesun příjmení na první pozici často nedokážou zohlednit skutečnost, že jméno může obsahovat více křestních jmen nebo příjmení a mnohdy vůbec nepočítají s tituly, natož s několikanásobnými. Při zpracování jména se tak naráží na řetězce obsahující křestní jméno obklopené dvěma příjmeními či tituly.

Pozor na nastavení

V jednom požadavku můžete zaslat více jmen oddělených svislicí |. (Nazývám tento znak svislicí, abych působil náramně chytře, normální lidé tomu říkají „svislítko“.) V současné době ale není možné v jednom požadavku získat více tvarů stejného jména, například více pádů. V češtině se liší práce se jmény v různých pádech, a to zejména při oslovení. Např. nositele jména JUDr. Josef Novák oslovíte „pane doktore“, ale pro druhý pád (koho, čeho) spíše zvolíte variantu „JUDr. Josefa Nováka“ než „pana doktora“.

Pokud máte uloženou informaci o pohlaví nositele jména, můžete ji zaslat v nepovinném parametru pohlavi. Tím lze vynutit ohnutí jména, aniž by se systém snažil rod určit sám, což ne vždy je možné. Použijte tento parametr pouze v případě, že jste si jeho správností jistí.

Krok 4: Zpracování výsledků

Získanou hodnotu uložte.

V případě, že místo řetězce je vráceno číslo, jedná se o chybu, viz dokumentace. Ty je potřeba ošetřit například uložením univerzální hodnoty. S některými chybami je možné dál pracovat. Systém například upozorňuje, že zadaný řetězec nemůže být jménem – protože se jedná o kombinaci číslic nebo speciálních znaků. Takové záznamy si můžete označit jako pravděpodobně chybné.

Krok 5: Kontrola logů

Ověřte si v logu, zda jsou do služby na ohýbání jmen skutečně posílaná ta jména, která chcete zpracovat. Jestli se dotazy necyklí a podobně.

Čas od času je dobré zkontrolovat changelog, zda neproběhly dostatečně zásadní změny, aby stálo za to získané tvary aktualizovat.

Krok 5: Hotovo

Můžete se pustit do něčeho dalšího. :-)