Corpus Search

Provides a list of frequencies in the specified corpus. Offers more flexibility.

Changed on

The difference from the wordlist is that this enpoint allows to customize how the results are displayed.

get/search/struct_wordlist

Request

  • The document declares no server URL.
  • Auth: HTTP basic

Query parameters

corpnamestring required

Corpus name. To query your own corpus (e.g. username john, corpus mycorpus), use value user/john/mycorpus.

wlattrstring required
Example:lc

Sets the corpus attribute you want to work with. Some corpora may have specific additional attributes.

Basic examples:

  • word
  • lc
  • lemma
  • lemma_lc
  • lempos
  • lempos_lc
  • tag
  • pos

For list of available word list attributes see /ca/api/corpora/{corpusId}

wlstruct_attr1'word' | 'lemma' | 'tag' | 'lempos' required

Sets the attributes used for generating the wordlist. Up to 3 attributes are allowed (see wlstruct_attr2 and wlstruct_attr3). Some corpora may contain additional specific attributes.

wlstruct_attr2'word' | 'lemma' | 'tag' | 'lempos'

Additional optional attribute that should be included in the result.

wlstruct_attr3'word' | 'lemma' | 'tag' | 'lempos'

Additional optional attribute that should be included in the result.

wlnums'frq' | 'docf' | 'arf'

The type of frequency. The values stand for: frq -> absolute or raw frequency, docf -> document frequency. arf -> average reduced frequency.

wlmaxfreqinteger

Sets the maximum frequency limit in the wordlist.

wlminfreqinteger

Sets the minimum frequency limit. Items with a lower frequency will not be included.

wlmaxitemsinteger

Sets the number of items to be returned in the API response. It is not limited for user corpora, in preloaded corpora can be some limitation. This parameter is often used with wlpage to help with pagination in frontend development.

wlpatstring

Sets a regex to filter the results. Relevant only in a simple wordlist.

wlsort'frq' | 'docf'

Sets the sorting of the results. The default is frq, i.e. by absolute frequency. Docf means document frequency.

wlblackliststring

A deny list (formerly known as blacklist) is a list of items that should be excluded from the result. The values should be be separated by a newline symbol (without commas between values). In the URL, the newline symbol is %0A.

include_nonwords1 | 0

Includes, or excludes, nonwords in the in the result. Nonwords are tokens which do not start with letter of the alphabet (e.g. numbers, punctuation). The regex to match the nonwords is [^[:alpha:]].*. Certain specialized corpora may use their own specific definition of nonwords.

relfreq1 | 0

Includes the relative frequency of each item in the result.

reldocf1 | 0

Calculate the document frequency for each item in the result. Must be used with addfreqs set to docf.

wlicase1 | 0

Sets the case sensitivity of the corpus, i.e. the data are extracted from a lowercased version of the corpus. It is used for case insensitive analysis. Parameter "1" means case sensitivity, "0" means case insensitivity.

wlpageinteger

To select page of the response. The number of items on the page is specified by parameter wlmaxitems.

format'json' | 'xml' | 'csv' | 'tsv' | 'txt' | 'xls'

The format of the output. Empty value is interpreted as JSON. Not every endpoint supports all formats.

random1 | 0

Parameter that represents if the wordlist is created from the first 10 milions lines of corpus. One if yes, no if he wordlist is created from the whole corpus.

wltype'simple' | 'struct_wordlist'
Example:simple

Parameter to set the format of ouput. Is it always set to simple, for the struct_wordlist is another enpoint called struct_wordlist.

Response

OK

fcritstring
paginginteger
concsizeinteger
fullsizeinteger
numofcollsinteger
hitleninteger
wllimitinteger
lastpageinteger
mlboolean
api_versionstring
manatee_versionstring

Example response

{
  "fcrit": "fcrit=lemma%2Fe+0+word%2Fe+0+lempos%2Fe+0",
  "FCrit": [
    {
      "fcrit": "lemma/e 0 word/e 0 lempos/e 0"
    }
  ],
  "Blocks": [
    {
      "Head": [
        {
          "n": "lemma",
          "id": "lemma/e"
        }
      ],
      "total": 77,
      "totalfrq": 13931,
      "Items": [
        {
          "Word": [
            {
              "n": "dog"
            }
          ],
          "frq": 6829,
          "fbar": 301,
          "pfilter": ";q=p0+0+0+%5Blemma%3D%22dog%22%5D;q=p0+0+0+%5Bword%3D%22dog%22%5D;q=p0+0+0+%5Blempos%3D%22dog-n%22%5D",
          "pfilter_list": [
            [
              "p0 0 0 [lemma=\"dog\"]"
            ]
          ],
          "poc": 47.765265440302166,
          "fpm": 60.78558113676994
        }
      ]
    }
  ],
  "paging": 1,
  "concsize": 14297,
  "fullsize": 14297,
  "Desc": [
    {
      "op": "Query",
      "arg": "[lemma_lc=\"(dog.*)\"]",
      "nicearg": "(dog.*)",
      "rel": 127.26,
      "size": 14297,
      "tourl": "q=q%5Blemma_lc%3D%22%28dog.%2A%29%22%5D"
    }
  ],
  "hitlen": 1,
  "wllimit": 1000,
  "lastpage": 1,
  "ml": true,
  "api_version": "5.63.12",
  "manatee_version": "2.36.7-SkE-2.223.6",
  "request": {
    "wlmaxfreq": "0",
    "wlpage": "1",
    "random": "0",
    "wlstruct_attr1": "lemma",
    "wltype": "struct_wordlist",
    "fmaxitems": "20000",
    "wlpat": "(dog.*)",
    "wlnums": "frq",
    "wlattr": "lemma_lc",
    "wlicase": "1",
    "wlmaxitems": "20000",
    "wlstruct_attr3": "lempos",
    "relfreq": "1",
    "include_nonwords": "1",
    "wlsort": "frq",
    "wlstruct_attr2": "word",
    "corpname": "preloaded/bnc2_tt21",
    "reldocf": "1",
    "wlminfreq": "5"
  }
}

Changes

    • breaking

      for the query request parameter wlicase, default value 0 was added

    • info

      query request parameter random was deprecated