Making requests to the API

Making requests to the API

Parameters

app_id, app_key

app_id and app_key are required authentication parameters. An incorrect or missing app_id or app_key will result in 403 Authentication failed error. Authentication parameters are generated when you create your account and are visible in the API Credentials page after you login.

  • app_id is a unique identifier for your application. It is generated automatically when you create your account.

  • app_key is a key for your application. You can generate up to 5 unique keys and manage them in your app description page.

word_id

word_id is a unique identifier that is very similar to an entry spelling. word_id is used whenever you request information about a specific word.

  • Remember to URL encode the word_id before sending a request.

    Example: the word `apr├Ęs-ski` should be converted to `apr%C3%A8s-ski`.

  • it is best practice to enter the word_id in lowercase and use an underscore for any spaces.

    Example: word_id for 'BBC' and 'historical cost accounting' would be 'bbc' and 'historical_cost_accounting' respectively.

Filtering

Filtering is available within some endpoints to filter the response to better suit your intended use. For example, the filter in the entry and lemmatron endpoints are used to deliver only the JSON bit your are interested in, whereas the filters in the wordlist endpoint can be used to include/exclude headwords matching specific features. You can use GET /filters/{endpoint} to explore which filters can be used with different endpoints.

In most cases you can use multiple filters and each filter can have multiple parameters. By listing multiple filters and parameters you are applying Boolean AND logic, meaning that given result MUST contain listed filters and parameters.

  • Parameters are separated by comma. For example lexicalCategory=noun,adverb,conjunction.
  • Filters are separated by semicolon. For example domains=anatomy;lexicalCategory=noun,adverb;region=gb.