ASEP API

K datům z repozitáře ASEP lze nově přistupovat pomocí REST API.

Odkaz na dokumentaci: https://asep.lib.cas.cz/apidoc/swagger/?urls.primaryName=CAV+Test+environment#/

API má jak testovací (výchozí), tak i produkční prostředí. Přepínat mezi nimi lze ve Swagger rozhraní vpravo nahoře.

Přístup k API

Pro přístup k API je třeba vytvoření nového účtu. 

V případě zájmu o přístup požádejte o vytvoření API účtu pro váš ústav na emailu arl@knav.cz

Prvotní autentizace probíhá pomocí HTTP Basic Auth, kdy je nutné poslat GET request pomocí auth volání s vaším jménem a heslem. Následně je vám vrácen Bearer token, který slouží k autentizaci v dalších částech API. Platnost Auth tokenu je 4 hodiny. Více detailů viz API dokumentace ve Swaggeru

  • Ictx pro Akademii věd je cav
  • V případě, že posíláte volání na testovací prostředí (asep.lib.cas.cz/apiarl/test), je nutné před jméno vložit předponu test-. Tj. zadávat ve formátu test-<vase-jmeno>

cURL call pro basic auth (na testovací server) by tedy vypadal nějak takto: 

curl -X 'GET' \
     'https://asep.lib.cas.cz/apiarl/test/v1/cav/auth' \
    -H 'accept: application/json' \
    -H 'Authorization: Basic encrypted basic auth'

Stahování dat + příklady

Pro získávání záznamů slouží sekce “Rec” (records). Pro získání všech záznamů, které odpovídají zadaným parametrům slouží následující volání: 

GET https://{server}/apiarl/{ns}/v1/{ictx}/list/{class}/{page}/{field}?{params}

Vyžaduje autentizaci pomocí Bearer tokenu (viz výše)

  • {class} může být buď hodnota
    • CavUnEpca pro katalogové záznamy (publikace, výsledky, projekty, datasety)
    • CavUnAut pro autoritní záznamy
  • {page} nastavte při prvním volání na hodnotu „1“ (první stránka výsledků). Následně opakujte volání pro získání dalších stránek a zvyšujte hodnotu {page} o 1 do maxima (pageLast), podle celkového počtu stránek a nastavené velikosti stránky (pageSize), což jsou hodnoty, které vrátí výsledek prvního volání.
  • {field} slouží k nastavení toho, podle jakého pole z katalogu vyhledáváte. V případě jednoduchých dotazů je třeba zadat vyhledávací pole z katalogu.  Seznam všech validních hodnot {field} k dispozici níže na stránce, v sloupečku “podpole 200 $a). V případě komplikovanějších/složených dotazů je třeba využít pqf syntaxu (viz pqf dotazy). V takovém případě nastavte {field} na hodnotu pqf
  • {param} jsou hodnoty vašich klíčových slov. Ať už jako termín, tak jako pqf dotaz. Seznam pqf kódů k sestavení příslušného dotazu k dispozici níže na stránce, v sloupečku “podpole 200c”
  • {fmt} určuje formátování návratového formátu. Může jít buď o 
    • Prázdná hodnota – MARC-JSON
    • lex – lexikální MARC JSON
    • marc – řádkový MARC JSON

Jednoduché dotazy

Jednoduché dotazy používají identifikátor, vložený do pole {field} a následně hledaný termín ve formátu „term=…“

Tyto záznamy slouží k vyhledávání podle jednotlivých kritérií, nebo podle kritérií jednoho typu

Příklad: Publikační záznamy autora Cyrila Fischera ve formátu řádkový MARC JSON

class = CavUnEpca

field = au

param = „fischer cyril"

fmt = marc

curl -X 'GET' \
    'https://asep.lib.cas.cz/apiarl/test/v1/cav/list/CavUnEpca/1/au?term=%22fischer%20cyril%22&pageSize=10&fmt=marc'
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <hodnota tokenu>'

Příklad: Všechny záznamy Ústavu teoretické a aplikované mechaniky AV ČR ve formátu řádkový MARC-JSON

class = CavUnEpca

field = ustav

param = utam

fmt = marc

curl -X 'GET' \
    'https://asep.lib.cas.cz/apiarl/test/v1/cav/list/CavUnEpca/1/ustav?term=utam-f&pageSize=10&fmt=marc' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <hodnota tokenu>'

PQF dotazy 

PQF (Prefix Query Format) je forma syntaxe pro dotazovací formát bib1, implementovaného jako součást knihovního protokolu Z39.50PQF dotazy by měly být použity v případě, že potřebujete kombinovat dvě a více kategorií (např. Autor-ústav, ústav-rok, autor-ústav-rok atd.). 

Tato PQF syntaxe je stejná, jako ve starém API i2.ws.search. 

PQF dotazy pokládáte tak, že do pole {field} vyplníte hodnotu “pqf”. Jako {param} následně vložíte naformátovaný pqf dotaz. 

Příklad: Všechny záznamy Ústavu teoretické a aplikované mechaniky, kde autor má příjmení “Fischer”

class = CavUnEpca

field = pqf

param = @and @attr 1=1 'Fischer' @attr 1=2462 'utam-f'

fmt = marc

curl -X 'GET' \
    'https://asep.lib.cas.cz/apiarl/test/v1/cav/list/CavUnEpca/1/pqf?term=%40and%20%40attr%201%3D1%20%27Fischer%27%20%40attr%201%3D2462%20%27utam-f%27&pageSize=10&fmt=marc' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer MTA4Mzc2QTNERjEzNjAxMzQ1QjA'

Tabulka validních vyhledávacích polí a hodnot PQF atributů

Tabulka pro katalogové záznamy (class = „CavUnEpca“)

Podpole 200 $a (Field) Český název Anglický název Podpole 200 $c (Hodnota PQF attributů)
SZ Druh dokumentu Document Type 2024
USTAV Ústav Institute AVCR 2462
ODDP Oddělení autora Author’s section 2010
ROKSB Rok sběru Data collection year 2456
DATZAP Datum zápisu (dd.mm.rrrr) Date of create (dd.mm.yyyy) 2485
T001N Systémové/asepové číslo System Number 2426
VYZ Výzkumný záměr Institutional research plan 2403
GRANTA Poskytovatel Funding providers 2061
GRANTAF Poskytovatel Funding providers 2404
GRANT infrastruktura Project 2405
UNA_PRNAZ Projekt Project 2441
SPL Spolupráce Cooperation 2013
NAV Návaznosti Traceability 2071
IOWN Vlastník Owner 2407
ZIOWN Vlastník Owner 2074
PRAD Ustav Workplace 2017
AUKDZ Autoři v neodeslaných záznamech The authors unsent records 2396
TZV Typ zdroje výsledku Resource type result 2019
RVO Inst. podpora RVO Institutional support 2021
EMB Vydavatel Publisher 2022
NAZEV Název Title 4
AUTHORPR Autor Author 7
IDA ID autora Auyhor ID 2029
SPI Spolupracující instituce Cooperating institutions 2028
ISKOD ISSN/ISBN/ISMN ISSN/ISBN/ISMN 2030
PROTH Rozlišení projektu Project resolution 2014
ZHA Výběr autora Author selection 2032
ZTN Název týmu Team name 2033
ZTU Hodnoceno pro ústav Evaluated for Institute 2034
ZUT Zařazení WOS/SCOPUS WOS/SCOPUS classification 2035
ZHOD Stav plných textů k hodnocení Status of full text for evaluation 2036
ZDOI DOI DOI 2046
ZIDC SCOPUS PUBMED) 2047
ZMDT Dataset Dataset 2052
ZMDS Stav metadatového záznamu Metadata record status 2050
ZMDL Link na metadatový záznam Link to metadata record 2051
ZNNZ Indexace vazeb u neodeslaných záznamu Link indexing for unsent records 2055
ZPROG Programy AV CAS programmes 2057
ZPROGR Programy AV Programmes 2057
ZOECD Obor OECD Science Area 2058
ZSML Smlouvy Licence 2059
PRAH Ústav – hostitel Institute ASCR – hosts 2070
DKF Formulár Data sheet 2406
ZZPZ Způsob publikování Method of publishing 2073
ZDV Všechny verze datového záznamu 2074
ZWDUP Duplicita záznamu staženého z wos se záznamem v databázi 2075
UPSB Přístup k plnému textu Access to fulltext 2092
ZAODD Oddělení 2077
APP První domácí autor 2015
PRA Ústav Institute ASCR 2069
LANGUAGE Jazyk dokumentu Language 2415
AUTHOR Autor Author 7
UPS Plný text Fulltext 2018
UPS_MAIN Informácie o súboroch z Content Servera Informace o souborech z Content Servera 2350
T001 Systémové/asepové číslo Sysno 12
ANY Všechna pole All Fields 1016
TITLE Název Title 4

 

Tabulka pro autoritní záznamy (class = „CavUnAut“)

Podpole 200 $a (Field) Český název Anglický název Podpole 200 $c (Hodnota PQF attributů)
AU Autor Author 1003
AUP Autor osobní jméno Author 1
AUPD Osobní jméno Author 2409
AUA Akce/Konference Conference 3
AUK Autor-kód záznamu Author Sysno 1013
AUK1 Autor-kód záznamu + druh.dok Author Sysno/Doc.kind 2479
AUKH objednávka predplatné exemplára 2480
SUBJECT Předmět (klíč.slova) Subject h. and keywords 21
UDC MDT UDC 14
EDITION Edice Series 5
PLACEP Místo vydání Publication Place 59
PUBL Nakladatel Publisher 1018
ISBN ISBN scopus-ISBN 7
ISSN ISSN scopus-ISSN 8
ISBNISSN ISSN 2480
SOURCE Zdrojový dokument Source Title 2499
SIG Signatury Call number 2481
TR Přírůskové číslo Track No. 2482
TISZ Ser./soub.záz./titul Ser./soub.záz./titul 2444
S600 Hesla osobní jméno Personal name entry 2469
S601 Hesla akce/korporace Event/Festival/Corporation 2471
S605 Hesla název filmu Film titles 2473
S607 Hesla gografické 2468
S608 Hesla form. deskriptor Formal descriptors 2474
S610 Předmět (klíč.slova) Keywords 2475
SRCA Autor zdroj.dok. Author of source document 2496
SRCD Zdroj.dok.datum Publication date (YYYYMMDD) 2495
KATO Kategória ohlasu Response Category 2458
KAK Kategória podľa AK Category by AK 2437
KPC Kategorie publikační činnosti Publication Category 2461
MRA Místo konání akce Conference Place 2488
SMRA Heslo – místo konání akce Keyword – Conference Place 2489
RECDN Recenzovaný dok. Reviewed document 2498
RECDA Autor recenzov.dok. Author of reviewed document 2497
TI1 Hlavní název Title 2412
TIAS Časopisy/názvové údaje Serial titles 2425
TIASZ Časopisy(soub.záznamy)/názv. údaje Serial (Complete) 2424
TIASR Časopisy(sváz.ročníky)/názvové údaje Serial (Volume) 2423
AVAIL Prístupnosť Availability 2435
AVAILP Dostupnost podle poboček Availability by branches 2513
TICL Časopisy(jednotlivá čísla)/titul Serial (Number) 2442
KSK Konspekt – skupina konspektu Conspectus – category 2378
KSPK Konspekt – předmětová kategorie Conspectus – division 2379
S606 Hesla MeSH MeSH Keywords 2472
IF Impakt faktor Impact factor 2455
UNH_SI0 Signatura Call number 5
SUBBASE Báze dat Base 2432
BRANCH Pobočka Branch 2514
DK Druh dokumentu Document Type 1031
DOCDK Druh dokumentu Document Type 1032
TOC fulltext obsahu fulltext toc 2376
SECURE fulltext dokumentu fulltext of document 2600
ZNPQ Žánr dokumentu Document genre 1031
DKPQ Druh publikácie Document type 1031
DATE Rok vydání Publication Year 31
COUNTRY Země vydání Country 55
COUNTRY21 Země vydání Country 55
LGT Jazyk textu Text Language 2415
CONTD Dokumenty pre doručovanie obsahu Language 2492
DS Další zpracování Next processing 2492
YEV Rok vykazování Year of submition 2456
DEXT Specifikace zdrojů Sources specifications 2539
UNA_AUP Autorita osobní jméno Personal name entry 1
UNA_AUP2 Autorita osobní jméno bez odkazů Personal name entry 2486
AUC Autorita korporace Corporation name entry 2
UNA_A215 Geografické jméno Name geographic 58
UNA_AU Autorita vstupní prvek Entry element 1003
UNA_CIT Místo akce/konference Conference place 2014
MP Oblast působení 2425
MU Místo úmrtí Place of death 2427
RE100 Regionální autority – jména osob a rodin (rodů) Subject headings in English 2457
UNA_A250U Mdt-slovný popis Mdt-term 2466
UNA_A230E Edice Edition 2466
UNA_DTKA Rok konání akce Year of conference 2468
UNA_AUM Místo akce/konference Conference place 2471
MN Místo narození Place of birth 2473
UNA_DTUM Rok úmrtí Year of death 2477
UNA_DTNA Rok narození Year of birthday 2478
UNA_A250 Věcné téma Subject headings 2480
UNA_A230 Autorita film názvové údaje Film title entry 2484
UNA_DT1 Datum vytvoření záznamu Record creation date 31
UNA_960 Heslo anglicky Subject headings in English 2494
AUCR Pracoviště (název, zkratka) Workplace shortcut 2498
UNA_DTVY Výročie 2475
UNA_DTUD Rok udalosti 2476
UNA_DK Druh autority NC 1031
A150 Klíčová slova Keywords 2480