Hawksearch v4.0 - Autocomplete API

Autocomplete is the quick suggestion feature also termed search-as-you-type. Generation information on this is available at - https://bridgeline.atlassian.net/wiki/spaces/HSKB/pages/3462493388

Following article depicts the API format for Autocomplete feature on Hawksearch v4.0

REST API endpoints:

Dev - https://searchapi-dev.hawksearch.net/api/autocomplete

Test - https://searchapi-test.hawksearch.net/api/autocomplete

Prod - https://essearchapi-na.hawksearch.com/api/autocomplete

Autocomplete V3

The Autocomplete V3 method is to be called when users have typed part of the keyword or the keyword is empty. The third version of the autocomplete method, contains minor modifications in the response structure (products object) .

To enable Autocomplete V3 on the Dashboard, please follow Update Top Product Categories instructions: Auto-Complete#Complete-UpdateTopProductCategories

Request

Endpoint	Method	Header Key

Endpoint	Method	Header Key
api/v3/autocomplete	POST	Content-Type: application/json
api/v3/autocomplete	POST	X-HawkSearch-IgnoreTracking: true/false

X-HawkSearch-IgnoreTracking key disables tracking in this instance. The value is set to false by default

See Version 1 Parameters

Response

Object	Data Type	Description

Object	Data Type	Description
Count	Numeric	The number of products that would be in search results if the search was executed.
ContentCount	Numeric	The number of content items that would be in search results if the search was executed.
TopFacets	Array of objects	The grouped categories with values and URLs for matching category names. The number of categories returned is configured in the Hawksearch Workbench unless overridden by the request parameters (see above).
>Value	String	Display name of category (example: Men » Jackets)
>Url	String	URL for displaying contents of the category (example: http://dev.hawksearch.net/sites/elasticdemo?department_nest=Jackets_4)
Products	Array of objects	See Products Object section.
Content	Array of objects	A set of objects for each content item returned. The number returned is configured in the Hawksearch Workbench > Keyword Search > Autocomplete > Update Top Content
>Value	String	Display label for the content item in Autocomplete. Field mapping can be done in Workbench > Keyword Search > Autocomplete
>Url	String	The URL for the link created. Field mapping can be done in Workbench > Keyword Search > Autocomplete
>Html	String	The display label in HTML format, if applicable. Configuration can be done in Workbench > Keyword Search > Autocomplete
>Thumb	Object	The thumbnail object that contains image data
>>Url	String	The URL for the thumbnail image. Field mapping can be done in Workbench > Keyword Search > Autocomplete
>>AltText	String	The Alternate Text for the thumbnail image
>Results	Array of objects	See Results Object section.
Popular	Array of objects	A set of Value and Url for each popular search term. The definition of Popular can be defined in the Hawksearch Workbench > Keyword Search > Autocomplete > Update Popular Searches
>Value	String	Display label for the popular search term
>Url	String	The URL for the link created If a redirect is applied to a popular search term, the URL will be used to redirect the user. The URL can be either relative or absolute. Redirect rules are configured in Workbench > Merchandising > Redirects.
SearchWebsiteUrl	String	Search website URL to be used to complete links
KeywordField	String	The name of the parameter used to pass the keyword entered by the user.
CategoryHeading	String	Will be included in the response if there are results to display. The CategoryHeading contains the text to display above the list of categories to display in Autocomplete.
ContentHeading	String	Will be included in the response if there are results to display. The ContentHeading contains the text to display above the list of content items to display in Autocomplete.
ProductHeading	String	Will be included in the response if there are results to display. The ProductHeading contains the text to display above the list of products to display in Autocomplete.
PopularHeading	String	Will be included in the response if there are results to display. The PopularHeading contains the text to display above the list of popular search terms to display in Autocomplete.
ViewAllButtonLabel	String	Will be included in the response if there are results to display. The ViewAllButtonLabel contains the text to display for the link to return all results from searching with the term entered.

{
    "TopFacets": {
        "department_nest": [
            {
                "Value": "Specials » Sat Dec 15th » Kids",
                "Url": "https://preview-dev.hawksearch.net/elasticdemo?department_nest=Kids",
                "FieldQSValue": "Kids",
                "RawValue": "3|Specials/Sat Dec 15th/Kids",
                "FacetName": "Department"
            },
            {
                "Value": "Specials » Sportswear » Mens",
                "Url": "https://preview-dev.hawksearch.net/elasticdemo?department_nest=Mens",
                "FieldQSValue": "Mens",
                "RawValue": "3|Specials/Sportswear/Mens",
                "FacetName": "Department"
            },
            {
                "Value": "Summer Sale » Camp & Hike » Tents & Shelters",
                "Url": "https://preview-dev.hawksearch.net/elasticdemo?department_nest=Tents-Shelters_1",
                "FieldQSValue": "Tents-Shelters_1",
                "RawValue": "3|Summer Sale/Camp & Hike/Tents & Shelters",
                "FacetName": "Department"
            }
        ],
        "Color-property": [
            {
                "Value": "Grey",
                "Url": "https://preview-dev.hawksearch.net/elasticdemo?Color-property=Grey",
                "FieldQSValue": "Grey",
                "RawValue": "Grey",
                "FacetName": "Color"
            }
        ]
    },
    "Count": 3,
    "ContentCount": 0,
    "ProductCount": 3,
    "Products": [
        {
            "ProductName": "Men's Jack SS Polo",
            "Sku": "",
            "Thumb": {
                "Url": "http://test.hawksearch.net/assets/1/14/DimThumbnail/Jack-SS-Polo_Nightsky.jpg",
                "AltText": ""
            },
            "Url": "https://preview-dev.hawksearch.net/elasticdemo/details?itemid=Item_140273",
            "Html": "<div class=\"hawk-sqItemImage\" ><img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Jack-SS-Polo_Nightsky.jpg' alt='' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Men's Jack SS Polo</h1>",
            "Results": {
                "Score": 1606.5238,
                "IsPin": false
            }
        },
        {
            "ProductName": "Boot Jack 25 Downtek",
            "Sku": "",
            "Thumb": {
                "Url": "http://test.hawksearch.net/assets/1/14/DimThumbnail/Boot-Jack-24-zm.jpg",
                "AltText": ""
            },
            "Url": "https://preview-dev.hawksearch.net/elasticdemo/details?itemid=Item_162525",
            "Html": "<div class=\"hawk-sqItemImage\" ><img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Boot-Jack-24-zm.jpg' alt='' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Boot Jack 25 Downtek</h1>",
            "Results": {
                "Score": 6.836272,
                "IsPin": false
            }
        },
        {
            "ProductName": "Jack Rabbit SL2 Footprint",
            "Sku": "16161093019000",
            "Thumb": {
                "Url": "http://test.hawksearch.net/assets/1/14/DimThumbnail/Big_Agnes_Jack_Rabbit_SL2_Footprint.png",
                "AltText": ""
            },
            "Url": "https://preview-dev.hawksearch.net/elasticdemo/details?itemid=Item_153223",
            "Html": "<div class=\"hawk-sqItemImage\" ><img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Big_Agnes_Jack_Rabbit_SL2_Footprint.png' alt='' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Jack Rabbit SL2 Footprint</h1>",
            "Results": {
                "Score": 0.03675415,
                "IsPin": false
            }
        }
    ],
    "Content": [],
    "Popular": [
        {
            "Value": "super <b>jacket</b>",
            "Url": "https://preview-dev.hawksearch.net/elasticdemo?keyword=super%20jacket",
            "RawValue": "super%20jacket"
        },
        {
            "Value": "columbia <b>jackets</b>",
            "Url": "https://preview-dev.hawksearch.net/elasticdemo?keyword=columbia%20jackets",
            "RawValue": "columbia%20jackets"
        }
    ],
    "SearchWebsiteUrl": "https://preview-dev.hawksearch.net/elasticdemo",
    "KeywordField": "keyword",
    "CategoryHeading": "Top Product Categories",
    "ContentHeading": "Top Content Match",
    "ProductHeading": "Top 3 Product Matches",
    "PopularHeading": "Popular Searches",
    "ViewAllButtonLabel": "View All Matches Please"
}

Autocomplete V2

The Autocomplete method is to be called when users have typed part of the keyword. The second version of the autocomplete method, contains minor modifications in the response structure (products object) .

Request

Endpoint	Method	Header Key

Endpoint	Method	Header Key
api/v2/autocomplete	POST	Content-Type: application/json
api/v2/autocomplete	POST	X-HawkSearch-IgnoreTracking: true/false

X-HawkSearch-IgnoreTracking key disables tracking in this instance. The value is set to false by default

See Version 1 Parameters

Response

Object	Data Type	Description

Object	Data Type	Description
Count	Numeric	The number of products that would be in search results if the search was executed.
ContentCount	Numeric	The number of content items that would be in search results if the search was executed.
Categories	Array of strings	Pairs of display values and URLs for matching category names. The number of categories returned is configured in the Hawksearch Workbench unless overridden by the request parameters (see above).
>Value	String	Display name of category (example: Men » Jackets)
>Url	String	URL for displaying contents of the category (example: http://dev.hawksearch.net/sites/elasticdemo?department_nest=Jackets_4)
Products	Array of objects	See Products Object section.
Content	Array of objects	A set of objects for each content item returned. The number returned is configured in the Hawksearch Workbench > Keyword Search > Autocomplete > Update Top Content
>Value	String	Display label for the content item in Autocomplete. Field mapping can be done in Workbench > Keyword Search > Autocomplete
>Url	String	The URL for the link created. Field mapping can be done in Workbench > Keyword Search > Autocomplete
>Html	String	The display label in HTML format, if applicable. Configuration can be done in Workbench > Keyword Search > Autocomplete
>Thumb	Object	The thumbnail object that contains image data
>>Url	String	The URL for the thumbnail image. Field mapping can be done in Workbench > Keyword Search > Autocomplete
>>AltText	String	The Alternate Text for the thumbnail image
>Results	Array of objects	See Results Object section.
Popular	Array of objects	A set of Value and Url for each popular search term. The definition of Popular can be defined in the Hawksearch Workbench > Keyword Search > Autocomplete > Update Popular Searches
>Value	String	Display label for the popular search term
>Url	String	The URL for the link created
SearchWebsiteUrl	String	Search website URL to be used to complete links
KeywordField	String	The name of the parameter used to pass the keyword entered by the user.
CategoryHeading	String	Will be included in the response if there are results to display. The CategoryHeading contains the text to display above the list of categories to display in Autocomplete.
ContentHeading	String	Will be included in the response if there are results to display. The ContentHeading contains the text to display above the list of content items to display in Autocomplete.
ProductHeading	String	Will be included in the response if there are results to display. The ProductHeading contains the text to display above the list of products to display in Autocomplete.
PopularHeading	String	Will be included in the response if there are results to display. The PopularHeading contains the text to display above the list of popular search terms to display in Autocomplete.
ViewAllButtonLabel	String	Will be included in the response if there are results to display. The ViewAllButtonLabel contains the text to display for the link to return all results from searching with the term entered.

Autocomplete

The Autocomplete method is to be called when users have typed part of the keyword. This is a full API version of the autocomplete.

Request

Endpoint	Method	Header Key

Endpoint	Method	Header Key
api/autocomplete	POST	Content-Type: application/json
api/autocomplete	POST	X-HawkSearch-IgnoreTracking: true/false

X-HawkSearch-IgnoreTracking key disables tracking in this instance. The value is set to false by default

Autocomplete Parameters

Name	Data Type	Required	Description	Source or Admin Section

Name	Data Type	Required	Description	Source or Admin Section
ClientGuid	String	required	API Client Guid	Tracking Key found in Admin > Account Info
Keyword	String	optional (from V3)	Search term entered by a user. If keyword is not included, all items configured to be returned will be returned. When this parameter is populated, the results will be matched against this term by the search engine.	Entered by the user
IsInPreview	Boolean	optional	This is used by the Hawksearch Preview to set to true will display elements in a preview mode.
Type	enumerator: Category, Product, Content, Popular	optional	To control the ability of returning numbers of rows, both ‘Type’ and ‘ProductCount’ parameters needs to be set. e.g.: Type=Category, ProductCount=2 Search response will return max 2 items for category suggestions.	Configured in Workbench > Keyword Search > Autocomplete
ProductCount	Numeric	optional	The maximum number of results to return for selected ‘Type’ (see above)
DisplayFullResponse	Boolean	optional	Flag set to true will display also full Document object for Products and Content suggestions
FieldOverride	Array of strings	optional	An array of field names that Hawksearch will return in a response
ClientData	Client Data object	optional	See Client Data Object section.
Query	String	optional	Use this to perform searches on one or more specific fields without needing to create facets for them.	For examples, see Field-specific Search
IndexName	string	optional	The name of the index against which the search must be performed	When the index was created, the IndexName was returned in the response from the Create method or the GetCurrentIndex method. This is also available on the Preview tab in dashboard.
CustomUrl	string	optional	Landing page Custom URL. When this parameter is populated, the resulting response will be determined by the configuration of the corresponding Landing Page.	This matches the Custom URL field within a Landing Page. Can be found Workbench > Merchandising > Landing Pages Keyword and CustomURL should never be passed in the same request.
PageId	number	optional	The unique identifier of the landing page(unique across the whole system)
SortBy	string	optional	The SortBy value corresponds with the Sorting configuration in the Hawksearch Workbench. This value needs to be one of the values configured within the Sorting/Pagination section of the Workbench. If no SortBy value is sent, the default value from the Workbench will be used. The default can vary depending on the sorting set triggered.	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination
SortingSetCode	string	optional	SortingSetCode can be used to specify a particular sorting set that should be used for the results. If not passed, the engine will evaluate the rules for each sorting set and pick the first applicable one.	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination > Sorting Code