Skip to content

Dokumentace dotazovaciho API periodika

Jump to bottom Edit New page
cosmo-cz edited this page Feb 14, 2020 · 4 revisions

Table of Contents

Dotazování na metadata periodik

API OKCZ verze 3.1 (od roku 2015) umožňuje dotazování na části monografie/číslo periodik. Slouží k tomu parametry:

  • part_no – Číslo části v případě monografie (podpole 245n MARC 21). Číslo vydání v případě periodika. Používá se u monografie i periodika.
  • part_name – Název části v případě monografie (podpole 245p MARC 21). Nepoužívá se u periodika.
  • part_year – Rok vydání periodika. Nepoužívá se u monografie.
  • part_volume – Ročník vydání periodika. Nepoužívá se u monografie.
  • part_note – Textová identifikace části monografie, nebo periodika pro knihovní IS, které nemají výše uvedené informace oddělené.
Ukázka: 
http://cache.obalkyknih.cz/api/books?multi=[{"isbn":"0322-9629","part_year":"rok 2016","part_no":"č. 8"}]

Pravidla při dotazování na části monografie a periodik:

Na části monografie se dotazuje pomocí kombinace dodatečných parametrů part_no (číslo části MARC21 podpole 245n) + part_name (název části MARC21 podpole 245p). Je povinný pouze jeden z těchto parametrů. Uvádí se data tak jak jsou obsažena v katalogu knihovny tj. normalizace na straně knihovního IS není nutná.

Na číslo periodika se dotazujeme pomocí kombinace dodatečných parametrů part_no + part_year + part_volume. Je povinná kombinace buďto part_no + part_year, nebo part_no + part_volume, ale doporučuje se dotazovat pomocí všech dostupných identifikátorů. Uvádí se data tak jak jsou obsažena v katalogu knihovny tj. normalizace na straně knihovního IS není nutná.

Pokud knihovní IS neobsahuje výše uvedené parametry odděleně, ale obsahuje je v textové podobě zapsané při katalogizaci, je možné uvádět i tento text/poznámku jako parametr part_note. Cílem není 100% shoda, to bohužel pomocí automatických procesů není možné. Cílem je zacílení na nejčastěji vyskytující se vzory. Zavedením parametru part_note se stává funkčnost API 3.1 nasaditelná pro široké spektrum knihovních IS.

Příklady:

  • Řetězec „2010, roč. 47, č. 1“ bude pomocí API rozeznáno jako rok:2010, ročník:47, číslo:1
  • Řetězec „2013 (Roč. 50): 20 + přílohy“ bude pomocí API rozeznáno jako rok:2013, ročník:50, číslo:20
  • Řetězec „leden 2013 + CD“ bude pomocí API rozeznáno jako rok:2013, číslo:1
  • apod.
V případě, že se dotazujeme na číslo monografie/periodika, které nebylo ještě skenováno,
bude nám poskytnut prázdný záznam, identifikovaný pomocí příznaku flag_bare_record = 1.

V případě dotazování na „souborný záznam“
tj. monografii/periodikum bez uvedení čísla/části bude poskytnuta:

  • v případě periodika obálka a obsah nejnovějšího skenovaného čísla periodika (ne posledně skenovaného, ale skutečně nejnovějšího – při skenovaní nového čísla periodika se u souborného záznamu tato obálka zobrazí),
  • v případě monografie obálka a obsah prvního skenovaného čísla monografie (je zaručeno, že tato obálka a obsah se po novém skenování nezmění),
  • zbylé položky meta datového API (toc fulltext, komentáře a hodnocení) patří „soubornému“ záznamu a ne číslu/části zobrazené na obálce,
  • meta datové API poskytne položku part_info obsahující identifikátory záznamu, kterému patří dohledaná obálka/obsah.
Je možné dotazovat se i na rozsah let/ročníků/čísel jednoduše oddělením let/ročníků/čísel pomocí pomlčky, čárky, nebo kombinace pomlčky a čárky. Např.: rok 2014 ročník 51 č. 1-12, nebo rok 2001-05,2007 č. 1-12 apod. Pro meta datový záznam v případě dotazu na rozsah platí tyto pravidla:
  • v případě periodika i monografie bude poskytnuta obálka i obsah prvního skenovaného čísla v tomto rozsahu (tím je zaručeno, že v průběhu času nedojde ke změně obálky/obsahu u stejného dotazu),
  • zbylé položky metadatového záznamu se vztahují na záznam, kterému patří obálka (identifikátory tohoto záznamu jsou vyjmenovány v položce part_info)
Praktické použití této nové vlastnosti API Obálek knih.cz je např. v knihovních systémech, které vedou samostatné záznamy pro jednotlivá čísla periodik/monografií, kdy bude možné zobrazit konkrétní obálku/obsah daného čísla/části. V předchozí verzi se při skenování např. aktuálního čísla periodika původní přepsalo, tj. u periodika identifikovaného pomocí ISSN existovala jedna obálka/obsah. V současné verzi se skenování a dotazování za pomocí uvedení dodatečných parametrů part_year + part_volume + part_no děje na úrovni jednotlivých čísel. V systémech, které neobsahují záznamy pro každé číslo periodika/monografie je možné zobrazení obálky např. v exemplářích apod.

Příklady dotazů:

Vícesvazková monografie 

http://cache.obalkyknih.cz/api/books?multi=[{"isbn":"9788025229033","nbn":"cnb002587539","part_name":"Rozvaliny Gorlanu"}]

Periodikum 

http://cache.obalkyknih.cz/api/books?multi=[{"isbn":"0322-9629","part_year":"2014","part_volume":"51","part_no":"8"}]

Dotaz na periodikum systému, který neobsahuje oddělenou informaci o roku / ročníku / čísle 

http://cache.obalkyknih.cz/api/books?multi=[{"isbn":"0322-9629","part_note":"R.2014 Roč.51 Č.14"}]

Dotaz na rozsah čísel periodika (svázaný ročník periodika) 

http://cache.obalkyknih.cz/api/books?multi=[{"isbn":"0322-9629","part_year":"2014","part_volume":"51","part_no":"1-12"}]

http://cache.obalkyknih.cz/api/books?multi=[{"isbn":"0322-9629","part_note":"R.2014 Roč.51 Č.1-12"}]

Dotazování na obálky periodik

V případě dotazu na souborný záznam se situace nemění. Bude poskytnut náhled obálky:

  • V případě periodika obálky nejaktuálnějšího čísla (ne posledně skenovaného, ale nejaktuálnějšího podle informací o vydání),
  • V případě monografie obálka první skenované části daného díla.
Dotazování na čísla periodik / části monografií je možné podle stejných dodatečných parametrů s předponou „part_“ jako je tomu v případě metadat.

Příklad dotazu na část monografie: 

http://cache.obalkyknih.cz/api/cover?multi={"isbn":"9788025229033","nbn":"cnb002587539","part_name":"Rozvaliny Gorlanu"}

Příklad dotazu na část periodika: 

http://cache.obalkyknih.cz/api/cover?multi={"isbn":"0322-9629","part_year":"R.2014","part_volume":"Roč.51","part_no":"Č.14"}

Příklad dotazu na část periodika knihovním IS, který neobsahuje oddělenou informaci o roku / ročníku / čísle: 

http://cache.obalkyknih.cz/api/cover?multi={"isbn":"0322-9629","part_note":"R.2014 Roč.51 č.14"}

Příklad dotazu na rozsah čísel periodika (svázané ročníky): 

http://cache.obalkyknih.cz/api/cover?multi={"isbn":"0322-9629","part_year":"2014","part_volume":"51","part_no":"1-12"}

http://cache.obalkyknih.cz/api/cover?multi={"isbn":"0322-9629","part_note":"2014 51 1-12"}

Výsledky při dotazu na část monografie/číslo periodika:

  • V případě, že část existuje, bude obálka poskytnuta.
  • V případě, že část neexistuje, bude vrácen prázdný průhledný GIF obrázek 1x1px
  • V případě, že se dotazujeme na souborný záznam, bude vrácena:
    • nejnovější obálka v případě periodika,
    • první existující část v případě monografie.
  • V případe dotazu na rozsah čísel periodika (svázaný ročník), bude vrácena první existující obálka v rozsahu (tím je zaručeno, že při dalším skenování bude vrácena stejná obálka na stejný dotaz).

Dotazování na TOC periodik

V případě dotazu na souborný záznam se situace nemění. Bude poskytnut náhled obsahu:

  • V případě periodika obsah nejaktuálnějšího čísla (ne posledně skenovaného, ale nejaktuálnějšího podle informací o vydání),
  • V případě monografie obsah první skenované části daného díla.
Dotazování na čísla periodik / části monografií je možné podle stejných dodatečných parametrů s předponou „part_“ jako je tomu v případě metadat.

Příklad dotazu na část monografie: 

http://cache.obalkyknih.cz/api/toc/thumbnail?multi={"isbn":"9783510968466","part_no":"Část A"}

Příklad dotazu na část periodika: 

http://cache.obalkyknih.cz/api/toc/thumbnail?multi={"isbn":"0322-9629","part_year":"R.2014","part_volume":"Roč.51","part_no":"č.14"}

Příklad dotazu na část periodika knihovním IS, který neobsahuje oddělenou informaci o roku / ročníku / čísle: 

http://cache.obalkyknih.cz/api/toc/thumbnail?multi={"isbn":"0322-9629","part_note":"R.2014 Roč.51 č.14"}

Příklad dotazu na rozsah čísel periodika (svázané ročníky): 

http://cache.obalkyknih.cz/api/toc/thumbnail?multi={"isbn":"0322-9629","part_year":"2014","part_volume":"51","part_no":"1-12"}

Výsledky při dotazu na část monografie/číslo periodika:

  • V případě, že část existuje, bude náhled obsahu poskytnut.
  • V případě, že část neexistuje, bude vrácen prázdný průhledný GIF obrázek 1x1px
  • V případě, že se dotazujeme na souborný záznam, bude vrácen:
    • náhled obsahu nejnovějšího čísla v případě periodika,
    • náhled obsahu první existující část v případě monografie.
  • V případe dotazu na rozsah čísel periodika (svázaný ročník), bude vrácen náhled obsahu prvního skenovaného čísla z rozsahu (tím je zaručeno, že při dalším skenování bude vrácen stejný náhled obsahu na stejný dotaz).

Úpravy

  • 14.3.2020 - Normalizace částí periodik jaro / léto / podzim / zima na 1,2,3 / 4,5,6 / 7,8,9 / 10,11,12 se nebude provádět. Důvodem je konflik se souběžnou číselnou řadou čísel periodik. Jaro / léto / podzim / zima se budou brát jako speciály. V případě rozsahů např. Jaro/Léto se normalizuje jako speciál na jaro_leto.
Add a custom footer
Add a custom sidebar
Clone this wiki locally