====== API ======

Vybrané aplikace umožňují přístup pomocí [[https://cs.wikipedia.org/wiki/API|API]]. Přístup přes API však vyžaduje autentizaci vždy, tedy i u aplikací, které ji při běžném používání nevyžadují. Pro autentizaci slouží osobní přístupové tokeny.

===== Postup při získání osobního přístupového tokenu =====

  - Pokud nejste přihlášeni, přihlaste se.
  - Na stránce [[https://korpus.cz/account|uživatelského účtu]] v sekci "Osobní přístupové tokeny" klikněte "Nový", zvolte délku platnosti a potvrďte "OK".
  - Token si zkopírujte, bude zobrazen pouze jednou.

Takto lze vytvořit libovolné množství osobních přístupových tokenů. Je také možné tokeny libovolně mazat. Po vypršení platnosti tokenu je třeba vytvořit nový.

===== Použití =====

Token se posílá v HTTP požadavku na URL ''https://korpus.cz/login'' metodou POST jako parametr ''personal_access_token''.

V odpovědi přijde session cookie, kterou je následně potřeba posílat s každým dalším požadavkem. Pro rychlejší komunikaci je vhodné session cookie uložit a používat ji v rámci několika hodin opakovaně.

<WRAP tip important 60%>
Popisy API jednotlivých aplikací:
  * [[https://korpus.cz/mquery/api/docs/index.html|MQuery]]
  * [[manualy:treq:api|Treq]]
  * <del>[[https://github.com/czcorpus/kontext/wiki/HTTP-API|KonText]]</del> - KonText API již není podporováno a dále vyvíjeno a služba bude k dispozici pouze do konce roku 2026. Jako náhrada je k dispozici server MQuery s jednodušším API a lepší dokumentací.
</WRAP>

Každé API běží na vlastní adrese:

  * MQuery: ''https://korpus.cz/mquery/api''
  * Treq: ''https://korpus.cz/treq/api/v1''
  * <del>KonText: ''https://korpus.cz/kontext-api/v0.17''</del> - 

<WRAP round important 60%>
Každá aplikace má také vlastní **limity**, po jejichž překročení hrozí zablokování přístupu k API.
  * **KonText**: max. 12 požadavků za minutu a současně max. 5000 požadavků za den
  * **Treq**: max. 30 požadavků za minutu a současně max. 5000 požadavků za den
</WRAP>

===== Příklady =====

==== 1) curl a Treq API ====

<code bash>
#!/usr/bin/env bash

# Log in
curl --cookie cookies.txt --cookie-jar cookies.txt -X POST -F 'personal_access_token=0a1b2c3d4e5f6-abc012...' 'https://korpus.cz/login'
# Query Treq
curl --cookie cookies.txt --cookie-jar cookies.txt 'https://korpus.cz/treq/api/v1?from=cs&to=en&multiword=false&regex=true&lemma=true&ci=true&pkgs[0]=SYNDICATE&pkgs[1]=CORE&query=pravda&order=perc&asc=false'
</code>

==== 2) Python a MQuery API ====

<code python>
#!/usr/bin/env python3
import requests
import pprint
import pickle

personal_access_token = '0a1b2c3d4e5f6-abc012...'
cookies_file = 'cookies.pickle'
corpus = 'syn2020'
timeout = 10

with requests.Session() as s:
    # Load cookies
    try:
        with open(cookies_file, 'rb') as f:
            s.cookies.update(pickle.load(f))
    except FileNotFoundError:
        pass
    r = s.post('https://www.korpus.cz/login', data={'personal_access_token': personal_access_token}, timeout=timeout)
    r = s.get(
        f'https://www.korpus.cz/mquery/api/freqs/{corpus}',
        params=dict(
            q='[word="celou"] [lemma="pravda"]',
            attr='word'
        ),
        timeout=timeout
    )
    pprint.pp(r.json())

    # Store cookies
    with open(cookies_file, 'wb') as f:
        pickle.dump(s.cookies, f)</code>

==== 3) R a MQuery API ====

<code r>
library(httr)
library(jsonlite)

personal_access_token <- 'c7036d756212-3afbe17...'
cookies_file <- 'cookies.txt'
corpus <- 'syn2020'
timeout_secs <- 10

# Create a handle; use curl's cookiejar to persist cookies across sessions
handle <- handle('https://www.korpus.cz')
cookie_cfg <- config(
  cookiefile = cookies_file,
  cookiejar  = cookies_file
)

# Log in
r <- POST(
  'https://www.korpus.cz/login',
  handle = handle,
  cookie_cfg,
  body = list(personal_access_token = personal_access_token),
  encode = 'form',
  timeout(timeout_secs)
)

# Frequency query via MQuery
r <- GET(
  paste0('https://www.korpus.cz/mquery/api/freqs/', corpus),
  handle = handle,
  cookie_cfg,
  query = list(
    q = '[word="celou"] [lemma="pravda"]',
    attr = 'word'
  ),
  timeout(timeout_secs)
)

print(content(r))

</code>