---
title: "Retrieve a list of frequencies of a word/words derived from a corpus."
method: GET
path: "/stats/frequency/words/{source_lang}/"
tags: ["LexiStats"]
---

# Retrieve a list of frequencies of a word/words derived from a corpus.

`GET /stats/frequency/words/{source_lang}/`

This endpoint provides a list of frequencies for a given word or words. Unlike the /word/ endpoint, the results are split into the smallest units. <br> <br> To exclude a specific value, prepend it with the minus sign ('-'). For example, to get frequencies of the lemma 'happy' but exclude superlative forms (i.e., happiest) you could use options 'lemma=happy;grammaticalFeatures=-degreeType:superlative'. <br> <br> Parameters can be provided in PATH, GET or POST (form or json). The parameters in PATH are overridden by parameters in GET, POST and json (in that order). In PATH, individual options are separated by semicolon and values are separated by commas (where multiple values can be used). <br> <br> The parameters wordform/trueCase/lemma/lexicalCategory also exist in a plural form, taking a lists of items. Examples:
* PATH: /wordforms=happy,happier,happiest
* GET: /?wordforms=happy&wordforms=happier&wordforms=happiest
* POST (json):
```javascript
  {
    "wordforms": ["happy", "happier", "happiest"]
  }
```
A mor complex example of retrieving frequencies of multiple lemmas:
```
  {
      "lemmas": ["happy", "content", "cheerful", "cheery", "merry", "joyful", "ecstatic"],
      "grammaticalFeatures": {
          "adjectiveFunctionType": "predicative"
      },
      "lexicalCategory": "adjective",
      "sort": ["lemma", "-frequency"]
  }
```
Some queries with "collate" or "sort" can exceed the 30s timeout, in which case the API will return an error message with status code 503. You mitigate this by providing additional restrictions such as "minFrequency" and "maxFrequency". <br> <br> You can use the parameters "offset" and "limit" to paginate through large result sets. For convenience, the HTTP header "Link" is set on the response to provide links to "first", "self", "next", "prev" and "last" pages of results (depending on the context). For example, if the result set contains 50 results and the parameter "limit" is set to 25, the Links header will contain an URL for the first 25 results and the next 25 results. <br> <br> Some libraries such as python's `requests` can parse the header automatically and offer a convenient way of iterating through the results. For example:
```python def get_all_results(url):
    while url:
        r = requests.get(url)
        r.raise_for_status()
        for item in r.json()['results']:
          yield item
        url = r.links.get('next', {}).get('url')
```

## Path parameters

- `source_lang` string, required

## Query parameters

- `corpus` string
- `wordform` string
- `trueCase` string
- `lemma` string
- `lexicalCategory` string
- `grammaticalFeatures` string
- `sort` string
- `collate` string
- `minFrequency` integer
- `maxFrequency` integer
- `minNormalizedFrequency` number, float
- `maxNormalizedFrequency` number, float
- `offset` integer
- `limit` integer

## Headers

- `app_id` string, required
- `app_key` string, required

## Response `200`

Successful response.

- StatsWordResultList — Schema for lexi-stats results for a word/trueCase/lemma/lexicalCategory returned as a list of frequencies per wordform-trueCase-lemma-lexicalCategory entry.
  - `metadata` object — Additional Information provided by OUP
  - `results` object[] — A list of found words along with their frequencies
    - `frequency` integer, required — The number of times a word appears in the entire corpus
    - `lemma` string, required — A lemma of the word.
    - `lexicalCategory` string, required — A lexical category such as 'verb' or 'noun'
    - `normalizedFrequency` integer, required — The number of times a word appears on average in 1 million words
    - `trueCase` string, required — A given written realisation of a an entry (e.g., "lay") usually lower case
    - `wordform` string, required — A given written realisation of a an entry (e.g., "lay") preserving case

## Other responses

- `400` — Invalid option name...; Option ... must have a value.; The option 'minFrequency' has to have an non-negative integer parameter.; The option 'maxFrequency' has to have an non-negative integer parameter.; The option 'limit' has to have an non-negative integer parameter.; The option 'offset' has to have an non-negative integer parameter.
- `404` — language is not in...
- `500` — Internal Error. An error occurred while processing the data.

---

[API](https://skmtc.net/oxforddictionaries/apis/untitled-api.md) · [All operations](https://skmtc.net/oxforddictionaries/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oxforddictionaries/untitled-api/versions/6acbf89f6aeb/schema)