Expand Terms

Returns a list of matching possible terms for a wildcard, stem, or fuzzy expansion.

The Expand Terms API returns a list of terms that match a term that you provide, according to a specified expansion.

Quick Start

The Expand Terms API has two required parameters, text and expansion. You set the text parameter to the term that you want to expand, and expansion to the method you want to use to expand the term.

For example:

/1/api/[async|sync]/expandterms/v1?text=probabilit*&expansion=wild

Note: You can use the file, reference and url parameters to submit input as a file, Haven OnDemand object store reference, or URL. However, in all cases, the API accepts only a single term.

There are three different expansions available:

  • Fuzzy. Return a list of words with a similar spelling to the word you provide. For example, if you provide the term fassion, it might return the terms fashion and fission.

    The API expands the term by comparing it to unstemmed terms in a common English reference source. It finds the terms in this source that are similar to the original term (according to an internally-configured tolerance level).

    You can use this to find corrections for a misspelled term.

  • Stem. Returns a list of terms that have the same stem as the word you provide.

    Stems are the common roots for similar words, such as plurals and verb forms. For example, the terms helpful, helping, and helps all stem to help. The API stems the term that you provide, and compares it to unstemmed terms in a common English reference source. It finds the terms in this source that have the same stem as the original term.

    You can use this expansion to find more information about what a particular keyword query might return.

  • Wild. Returns a list of the terms that match a wildcard term that you provide. For example, if you provide the term f*ion, it might return the terms function, faction, fashion, fission, and fusion.

    You can use a question mark (?) to represent a single unknown character, and an asterisk (*) to represent any number of unknown characters (including zero).

    The API expands the term by comparing it to terms in a common English reference source. It finds the terms that match the wildcard pattern.

    You can use this expansion to find more information about what a wildcard query might match.

The API returns the list of expanded terms. For example:

{
  "terms": [
    {
      "term": "PROBABILIT"
    },
    {
      "term": "PROBAB"
    },
    {
      "term": "PROBABILITIST"
    },
    {
      "term": "PROBABILITY1"
    },
    {
      "term": "PROBABILITYDISTRIB"
    }
  ]
}

By default the results are listed in their stemmed form (the word root). You can optionally set the stemming parameter to false to return the full unstemmed results.

The max_terms parameter allows you to choose the maximum number of terms to return. You can use the sort parameter to return the results in alphabetical order, or in order of the number of documents the expansion occurs in.

Synchronous
https://api.havenondemand.com/1/api/sync/expandterms/v1
Asynchronous
https://api.havenondemand.com/1/api/async/expandterms/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
binary A file containing the terms to expand. Multipart POST only.
reference
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding document is passed to the API.
text
string The terms to expand.
url
string A publicly accessible HTTP URL from which the terms to expand can be retrieved.
expansion
enum The method to use to expand the specified term.
Optional
Name Type Description
max_terms
number The maximum number of expanded terms or term phrases to return. Default value: 50.
sort
enum The criteria to use to order the result terms. Default value: alphabetical.
stemming
boolean Set this parameter to false to return the list of terms in their unstemmed form. Default value: true.
Enumeration Types

This API's parameters use the enumerations described below:

expansion
The method to use to expand the specified term.
fuzzy Similar spelling
stem Same stem
wild Wildcard expansion
sort
The criteria to use to order the result terms.
none No sorting
deprecated - use alphabetical or documents instead
alphabetical Alphabetical
documents Number of document occurrences

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Expand Terms Response {
terms ( array[Terms] ) The details of the expanded terms.
}
Expand Terms Response:Terms {
documents ( integer , optional) The number of documents that the expanded term occurs in.
term ( string ) The expanded term.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "terms": {
            "items": {
                "properties": {
                    "documents": {
                        "type": "integer"
                    },
                    "term": {
                        "type": "string"
                    }
                },
                "required": [
                    "term"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "terms"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/expandterms/v1
/api/api-example/1/api/sync/expandterms/v1
Examples
See this API for yourself - select one of our examples below.
Wilcard expansion
Expand 'probabilit*' with 'wild' expansion
Fuzzy expansion
Expand 'probability' with 'fuzzy' expansion
Stemming expansion
Expand 'probability' with 'stem' expansion
Parameters
Required
Select file Change Remove
Name Type Value
expansion
enum
Optional
Name Type Value
max_terms
number
sort
enum
stemming
boolean
(Default: True)


ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.