====== 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://github.com/czcorpus/kontext/wiki/HTTP-API|KonText]]
  * [[manualy:treq:api|Treq]]
</WRAP>

Každé API běží na vlastní adrese:
  * KonText: ''https://korpus.cz/kontext-api/v0.17''
  * Treq: ''https://korpus.cz/treq/api/v1''

<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 KonText API ====

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

personal_access_token = '0a1b2c3d4e5f6-abc012...'
cookies_file = 'cookies.pickle'

with requests.Session() as s:
    # Load cookies
    try:
        with open(cookies_file, 'rb') as f:
            s.cookies.update(pickle.load(f))
    except FileNotFoundError:
        pass

    # Log in
    r = s.post('https://korpus.cz/login', data={'personal_access_token': personal_access_token})

    # Creating a concordance query
    request_body = {
        "type": "concQueryArgs",
        "maincorp": "syn2015",
        "usesubcorp": None,
        "viewmode": "kwic",
        "pagesize": 40,
        "attrs": ["word","tag"],
        "attr_vmode": "visible-kwic",
        "base_viewattr": "word",
        "ctxattrs": [],
        "structs": ["text","p","g"],
        "refs": [],
        "fromp": 0,
        "shuffle": 0,
        "queries": [
            {
                "qtype": "advanced",
                "corpname": "syn2015",
                "query": "[word=\"celou\"] [lemma=\"pravda\"]",
                "pcq_pos_neg": "pos",
                "include_empty": False,
                "default_attr": "word"
            }
        ],
        "text_types": {},
        "context":
        {
            "fc_lemword_wsize": [-5, 5],
            "fc_lemword": "",
            "fc_lemword_type": "all",
            "fc_pos_wsize": [-5, 5],
            "fc_pos": [],
            "fc_pos_type": "all"
        },
        "async": False
    }
    r = s.post('https://korpus.cz/kontext-api/v0.17/query_submit', params={'format': 'json'}, json=request_body)
    response_json = r.json()
    print(response_json)

    # Displaying a concordance
    conc_persistence_op_id = response_json['conc_persistence_op_id']
    r = s.get('https://korpus.cz/kontext-api/v0.17/view', params={'format': 'json', 'q': '~'+conc_persistence_op_id})
    print(r.json())

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

==== 3) R a KonText API ====

<code r>
library(httr)

# Log in
personal_access_token = '0a1b2c3d4e5f6-abc012...'
r <- POST("https://korpus.cz/login", body=list(personal_access_token=personal_access_token))

# Creating a concordance query
request_body <- '{
	"type": "concQueryArgs",
	"structs": ["text", "s"],
	"refs": ["%3Dtext.txtype", "%3Ddoc.author"],
	"queries": [
		{
			"qtype": "advanced",
			"corpname":"syn2020",
			"query": "[word=\\\"celou\\\"] [lemma=\\\"pravda\\\"]"
		}
	]
}'

r <- POST("https://korpus.cz/kontext-api/v0.17/query_submit?format=json", content_type_json(), body=request_body)

# Displaying a concordance
response_json <- content(r)
conc_persistence_op_id <- response_json$conc_persistence_op_id
params <- list(
	format="json",
	q=paste0("~", conc_persistence_op_id),
	refs="=text.txtype",
	refs="=doc.author",
	pagesize=100
)
r <- GET("https://korpus.cz/kontext-api/v0.17/view", query=params)
content(r)
</code>