Highlight Text

Highlights the specified terms in the text you submit.

The Highlight Text API finds specified terms in your input text and adds HTML tag around them. It returns your input text, with the added HTML tags.

Quick Start

You must provide input text, and a list of the terms that you want to highlight. For example:

/1/api/[async|sync]/highlightext/v1?text=we+are+good+friends+and+everyone+likes+us&highlight_expression=friend

Haven OnDemand returns the text, wrapped in <span class="highlight"> tags.

{
  "text": "we are good <span class=\"highlight\">friends</span> and everyone likes us"
}

You can then use a simple CSS rule to apply the highlight:

span.highlight { background-color:#FFFF00; }

Stemming

Haven OnDemand highlighting does not simply highlight the exact text that you send in the highlight_expression parameter. It applies language stemming rules to highlight words with the same root, which means that it can highlight all the information in the text that is relevant to the search term or the highlight expression of your choice.

/1/api/[async|sync]/highlighttext/v1?The+workers+he+was+doing+work+with+while+he+was+working+9+to+5+were+interesting&highlight_expression=working

This example returns the following highlighting result:

{
  "text": "The <span class=\"highlight\">workers</span> he was doing <span class=\"highlight\">work</span> with while he was <span class=\"highlight\">working</span> 9 to 5 were interesting"
}

In this simple example, the highlight expression term working is highlighted, and all the other words with the same stem are also highlighted. In long text documents it can be very useful to highlight relevant terms without knowing how they are phrased.

Usage

The start_tag parameter allows you to change the default <span class="highlight"> tag to suit your needs. For example:

/1/api/[async|sync]/highlighttext/v1?text=we+are+good+friends+and+everyone+likes+us&highlight_expression=friend&start_tag=<strong>

This example makes the matching text bold by wrapping it in the <strong> tag. Haven OnDemand automatically creates the ending HTML tag from your start tag.

{
  "text": "we are good <strong>friends</strong> and everyone likes us"
}

You can match multiple terms by entering them separated by commas in the highlight_expression parameter. The start_tag parameter also supports any attribute added to the tag, such as class or style. For example:

/1/api/[async|sync]/highlighttext/v1?text=The best time to plant a tree was 20 years ago. The second best time is now&highlight_expression=best,second&start_tag=<font color="red">

This example returns the following result:

{
  "text": "The <font color="red">best</font> time to plant a tree was 20 years ago. The <font color="red">second</font> <font color="red">best</font> time is now"
}
Synchronous
https://api.havenondemand.com/1/api/sync/highlighttext/v1
Asynchronous
https://api.havenondemand.com/1/api/async/highlighttext/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 document to process. 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 text content to highlight.
url
string A publicly accessible HTTP URL from which the document to highlight can be retrieved.
highlight_expression
string The terms to highlight in the specified text. Separate the terms with spaces, pluses (+), or commas (,).
Optional
Name Type Description
end_tag
string The closing HTML tag to use to highlight a link term. If omitted, this is generated automatically from the start_tag.
start_tag
string The opening HTML tag to use to highlight a link term. Default value: <span style="background-color: yellow">.

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.
Highlight Text Response {
text ( string ) The source text, including HTML tags to highlight the specified link terms.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "text": {
            "type": "string"
        }
    },
    "required": [
        "text"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/highlighttext/v1
/api/api-example/1/api/sync/highlighttext/v1
Examples
See this API for yourself - select one of our examples below.
Highlight 'friend'
we are good friends and everyone likes us
Highlight 'best' and 'second'
The best time to plant a tree was 20 years ago. The second best time is now
Highlight 'right' and 'worst'
The biggest competitive advantage is to do the right thing at the worst time
Parameters
Required
Select file Change Remove
Name Type Value
highlight_expression
string
Optional
Name Type Value
end_tag
string
start_tag
string


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.