HTTP API

KonText HTTP API

Table of contents

• Creating a concordance query
• Displaying a concordance
• Frequency distribution for text types

Creating a concordance query

While it is possible to use both simple and advanced query types it is strongly advised to use the advanced variant when dealing with the API as the query encoding is much easier in such case.

• URL: /query_submit?format=json
• HTTP Method: POST
• content type: application/json

Request body:

{
  "type": "concQueryArgs",
  "maincorp": "syn2020",
  "usesubcorp": null,
  "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": "syn2020",
      "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
}

Parameters

name	description
type	this is always a constant concQueryArgs
usesubcorp	null or name of user's subcorpus
viewmode	kwic|sen|align (align works only for parallel corpora)
pagesize	a positive number specifying size of the resulting page
attrs	a list of positional attributes we want to retrieve
attr_vmode	visible-all|visible-kwic|visible-multiline|mouseover
base_viewattr	the main attribute the flow of text will be based on
ctxattrs	TODO
structs	a list (possibly empty) of structural attributes to be shown
refs	a list (possibly empty) of additional metadata attached to each row
fromp	a number specifying a starting page
shuffle	`0
queries	a list of objects, each for active corpus (normally 1 item, for aligned corpora > 1)
queries[].qtype	advanced
queries[].corpname	"syn2020",
queries[].query	A CQL query (e.g. [word=\"their\"] [lemma=\"truth\"])
queries[].pcq_pos_neg	applies for aligned corpora queries
queries[].include_empty	true|false
queries[].default_attr	a positional attribute applied for simplied CQL expressions

Response:

• HTTP status: 201 Created (if without errors)
• content type: application/json

{
  "size": 110,
  "finished": true,
  "conc_args": {
    "maincorp": "syn2020",
    "viewmode": "kwic",
    "pagesize": 40,
    "attrs": "word,tag",
    "attr_vmode": "visible-kwic",
    "base_viewattr": "word",
    "structs": "text,p,g"
  },
  "query_overview": {
  },
  "Q": [ "~gUgICee6K2ka" ],
  "conc_persistence_op_id": "gUgICee6K2ka"
}

Parameters

name	description
size	size of the resulting concordance (in tokens)
finished	if async is set to true then this is always true
conc_persistence_op_id	a public ID of the resulting concordance
conc_args	additional parameters affecting how the concordance is displayed

Displaying a concordance

• URL: /view
• HTTP Method: GET

Parameters (in URL)

name	description
q	concordance persistence ID; the value must have a ~ prefix to distinct fully stored queries from legacy/NoSkE ones
format	for API use, json is required (without it, an HTML page is returned

Frequency distribution for text types

• URL: /freqtt
• HTTP Method: GET

Parameters (in URL)

name	description
q	concordance persistence ID; the value must have a ~ prefix to distinct fully stored queries from legacy/NoSkE ones
fttattr	dot-separated structure and structural attribute (e.g. doc.first_published)
ftt_include_empty	0,1 - if 1 then also values with no occurrences will be returned
flimit	0,1,...,N - a minimum absolute frequency of a searched phenomenon
format	json (otherwise, an HTML page is returned

Response:

• HTTP status: 200 OK (if without errors)
• content type: application/json

Important entries:

name (path)	description
Blocks	Frequency results (array)
Blocks[i]	Frequency results entry
Blocks[i].Head	Array of respective columns (typically - 1) value of a respective structural attr., 2) absolute frequency, 3) ipm
Blocks[i].Items	Array of individual lines
Blocks[i].Items[i].Word[0].n	Value of a respective structural attribute
Blocks[i].Items[i].freq	Absolute frequency
Blocks[i].Items[i].rel	Instances per million (ipm)