Search API Methods

Search V2

The 2nd version of search method was extended

The second version of the search method has been modified, mainly in the returned object area. The core change is the way the hierarchical facet values are presented in a way corresponding to his purpose (hierarchy).

This part of documentation describes version 2 and version 1 key differences only - please check first version of search section below for full description.

Request

Endpoint	Method	Header Key

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

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

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	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.
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.
PageNo	number	optional	Page number of results to return. If no PageNo value is sent, the default is that the first page of results will be returned. Reporting is impacted by sending the PageNo parameter, so it should not be passed for the first page unless the user is navigating back to the first page after visiting another page of results.	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination
MaxPerPage	number	optional	Maximum number of items to be returned on a page. This value needs to be one of the values configured within the Sorting/Pagination section of the Workbench. If no MaxPerPage value is sent, the default value from the Workbench will be used. The default can vary depending on the pagination set triggered. Entering 0 in the request will return only facets, no documents. See example	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination
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
PaginationSetCode	string	optional	PaginationSetCode can be used to specify a particular pagination set that should be used for the results. If not passed, the engine will evaluate the rules for each pagination set and pick the first applicable one.	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination > Pagination Code
SearchWithin	string	optional	SearchWithin should be populated if the user has applied a Search Within filter to the results. This functionality needs to be configured in the Hawksearch Workbench in order for it to work.	Workbench > Data Configuration > Facets
FacetSelections	Dictionary <string, object[]>	optional	This is the dictionary of key-value pairs where the key is the name of the facet. The value is the array of values for the selection.	The names and values of facets can be taken from the response from a previous calling of the search method. The name can be found in value of the Field object, unless ParamName is set, then use ParamName. The value can be found in the value of the Value object (within the Values object). Examples can be seen in Example 1.2 below.
FacetOverride	string array	optional	An array of facet names that should be returned in the response. If provided, only the facets listed will be returned. If no FacetOverride value is sent, the Workbench configuration will be used to determine and send appropriate facets based on the result set. If there is a Display Rules on facets will still be evaluated for facets set in FacetOverride. This means that the facet will not be returned, even if set in FacetOverride, if the Display Rule condition is not met. The Is Visible flag on facets will be honored even if the facet is set in the FacetOverride. This means that a facet set to not be visible will not be returned, even if set in FacetOverride. Passing an empty object will return no facets. See example	There are two places that can impact which facets are configured to be returned Workbench > Data Configuration > Facets > Editing a facet > Display Rule Workbench > Merchandising > Landing Page > Editing a page > Facet Configuration
FieldOverride	string array	optional	An array of field names that will be returned in the response. If provided, only the fields listed will be returned. If no FieldOverride value is sent, the Workbench configuration will be used. If the Skip from Custom flag is turned “on” for a field, it will not be returned in the response, even if set in the FieldOverride parameter.	Fields will not be returned unless the flag is set at the field level: Workbench > Data Configuration > Fields > Edit a field > Include in results = On
ClientData	ClientData Object	optional	See Client Data Object section.
IsInPreview	Boolean	optional	This is used by the Hawksearch Preview to set to true will display elements in a preview mode.	You can use this if you desire additional score information returned.
ExplainDocId	String	optional	This is used by the Hawksearch Preview to display the advanced explanation of an item’s score calculation.	You can use this if you desire additional score information returned.
SmartBar	Array of objects	optional	These are options that can be set by the user in the SmartBar. You can use this if you desire additional score information returned.
>BoostAndBury	Boolean	optional	This is used to enable or disable Boost and Bury Rules.	Workbench > Merchandising > Boost & Bury Rules
>VisibilityRules	Boolean	optional	This is used to enable or disable Visibility Rules.	Workbench > Merchandising > Visibility Rules
>PersonalizedBoost	Boolean	optional	This is used to enable or disable the boost for Recommended Items.	Workbench > Edit Boost for Recommended Items
>PopularityBoost	Boolean	optional	This is used to enable or disable the boost for Learning Search Multiplier.	Workbench > Edit Learning Search Multiplier
>ItemPin	Boolean	optional	This is used to enable or disable Pinning Rules.	Workbench > Merchandising > Item Pinning
>PopularitySalesBoost	Boolean	optional	This is used to enable or disable the boost for Orders Multiplier	Workbench > Keyword Search > AI Based Multipliers > Order Multiplier
>PopularityAdd2CartBoost	Boolean	optional	This is used to enable or disable the boost for Add2Carts Multiplier	Workbench > Keyword Search > AI Based Multipliers > Add2Carts Multiplier
Is100CoverageTurnedOn	Boolean	optional	If all of the records in a result set have the same value(s) in a facet, the facet does not provide value to the user. To flag such facets as not visible, set this flag to "true."
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
BoostQueries	Array	optional	Collection of boosting objects	For examples, see Dynamic Query Boost Search
>query	Alphanumeric string	optional	The field(s) and value(s) to be searched for
>boost	Integer	optional	The boost value for the particular filter provided by the query parameter
Variant	Object	optional	See Variant Object Section	Hawksearch 4.0 Variants

Example SmartBar

{
    "ClientGuid": "{{client_guid}}",
    "IndexName": "{{index}}",
    "IsInPreview": false,
    "Keyword": "Trestle 15 Item_72351",
    "SmartBar": {
        "BoostAndBury": true,
        "VisibilityRules": false,
        "PersonalizedBoost": true,
        "PopularityBoost": true,
        "ItemPin": true,
        "PopularitySalesBoost": true,
        "PopularityAdd2CartBoost": true
    }
}

Response

Object	Data Type	Always	Description

Object	Data Type	Always	Description
Success	Boolean	Yes	Indicates if request was successful. If the result is nit successfull, please
Pagination	Pagination object	Yes	Summary of pagination details and a set of pagination options. See Pagination Object section.
Keyword	String	Yes	The Keyword value that was sent to Hawksearch in the request. If no Keyword was set in request, the value will be empty.
Results	Array of objects	Yes	See Results Object section.
Facets	Array of objects		See Facet Object section.
VisitorTargets	Array of objects		See VisitorTargets Object section.
Selections	Array of objects		See Selections Object section.
Sorting	Sorting Object		See Sorting Object section.
AdjustedKeyword	String	No	If this is populated, it indicates that the Keyword value returned 0 results, but the results in this response are from this AdjustedKeyword. A message should be displayed to the user informing them that their search was corrected to this string. This is the result of Auto Correct, which is configured in the Workbench > Keyword Search > Did You Mean
DidYouMean	Array of strings	Yes	If any strings are returned in the array, they should be displayed to the user as suggested search terms. This is the result of Did You Mean, which is configured in the Workbench > Keyword Search > Did You Mean
Merchandising	Array of objects	No	See Merchandising Object section.
FeaturedItems	Array of objects	No	See FeaturedItems Object section.
SearchDuration	Numeric	Yes	Number of milliseconds
Redirect	Redirect Object		See Redirect Object section.
PageContent	PageContent Object		See PageContent Object section.

Search

The Search method is used to retrieve search results or to retrieve the contents for a Landing Page. Either the Keyword or CustomUrl parameter should be included anytime this method is used. The following are use-cases for when this method should be used.

Retrieve Search Results

Search by keyword entered by user
Refinement of search results when user selects facet(s)
Another page of search results when user moves to another page of search results
Resorted results when user sorts search results
Refinement of search results when user applies a “search within” refinement

Retrieve Landing Pages

Initial loading of a Landing Page; for both content or product listing type of Landing Pages
Refinement of product listing on a Landing Page when user selects facet(s)
Another page of products when user moves to another page listed products of a Landing Page
Resorted products when user sorts items within a Landing Page
Refinement of product listing when user applies a “search within” refinement

Request

Endpoint	Method	Header Key

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

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

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	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. Keyword and CustomURL should never be passed in the same request.
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.
PageNo	number	optional	Page number of results to return. If no PageNo value is sent, the default is that the first page of results will be returned. Reporting is impacted by sending the PageNo parameter, so it should not be passed for the first page unless the user is navigating back to the first page after visiting another page of results.	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination
MaxPerPage	number	optional	Maximum number of items to be returned on a page. This value needs to be one of the values configured within the Sorting/Pagination section of the Workbench. If no MaxPerPage value is sent, the default value from the Workbench will be used. The default can vary depending on the pagination set triggered. Entering 0 in the request will return only facets, no documents. See example	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination
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
PaginationSetCode	string	optional	PaginationSetCode can be used to specify a particular paginationset that should be used for the results. If not passed, the engine will evaluate the rules for each pagination set and pick the first applicable one.	Valid values are configured in Workbench > Data Configuration > Sorting/Pagination > Pagination Code
SearchWithin	string	optional	SearchWithin should be populated if the user has applied a Search Within filter to the results. This functionality needs to be configured in the Hawksearch Workbench in order for it to work.	Workbench > Data Configuration > Facets
FacetSelections	Dictionary <string, object[]>	optional	This is the dictionary of key-value pairs where the key is the name of the facet. The value is the array of values for the selection.	The names and values of facets can be taken from the response from a previous calling of the search method. The name can be found in value of the Field object, unless ParamName is set, then use ParamName. The value can be found in the value of the Value object (within the Values object). Examples can be seen in Example 1.2 below.
FacetOverride	string array	optional	An array of facet names that should be returned in the response. If provided, only the facets listed will be returned. If no FacetOverride value is sent, the Workbench configuration will be used to determine and send appropriate facets based on the result set. If there is a Display Rules on facets will still be evaluated for facets set in FacetOverride. This means that the facet will not be returned, even if set in FacetOverride, if the Display Rule condition is not met. The Is Visible flag on facets will be honored even if the facet is set in the FacetOverride. This means that a facet set to not be visible will not be returned, even if set in FacetOverride. Passing an empty object will return no facets. See example	There are two places that can impact which facets are configured to be returned Workbench > Data Configuration > Facets > Editing a facet > Display Rule Workbench > Merchandising > Landing Page > Editing a page > Facet Configuration
FieldOverride	string array	optional	An array of field names that will be returned in the response. If provided, only the fields listed will be returned. If no FieldOverride value is sent, the Workbench configuration will be used. If the Skip from Custom flag is turned “on” for a field, it will not be returned in the response, even if set in the FieldOverride parameter.	Fields will not be returned unless the flag is set at the field level: Workbench > Data Configuration > Fields > Edit a field > Include in results = On
ClientData	ClientData Object	optional	See Client Data Object section.
IsInPreview	Boolean	optional	This is used by the Hawksearch Preview to set to true will display elements in a preview mode.	You can use this if you desire additional score information returned.
ExplainDocId	String	optional	This is used by the Hawksearch Preview to display the advanced explanation of an item’s score calculation.	You can use this if you desire additional score information returned.
SmartBar	Array of objects	optional	These are used by the Hawksearch Preview	These are options that can be set by the user in the Preview SmartBar. You can use this if you desire additional score information returned.
>BoostAndBury	Boolean	optional	This is used by the Hawksearch Preview to enable or disable Boost and Bury Rules.	Workbench > Merchandising > Boost & Bury Rules
>VisibilityRules	Boolean	optional	This is used by the Hawksearch Preview to enable or disable Visibility Rules.	Workbench > Merchandising > Visibility Rules
>PersonalizedBoost	Boolean	optional	This is used by the Hawksearch Preview to enable or disable the boost for Recommended Items.	Workbench > Edit Boost for Recommended Items
>PopularityBoost	Boolean	optional	This is used by the Hawksearch Preview to enable or disable the boost for Learning Search Multiplier.	Workbench > Edit Learning Search Multiplier
>ItemPin	Boolean	optional	This is used by the Hawksearch Preview to enable or disable Pinning Rules.	Workbench > Merchandising > Item Pinning
Is100CoverageTurnedOn	Boolean	optional	If all of the records in a result set have the same value(s) in a facet, the facet does not provide value to the user. To flag such facets as not visible, set this flag to "true."
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

Example 1.1 Retrieving search results

{
    "ClientGuid" : "client_guid",
    "Keyword" : "jack",
    "ClientData":{
        "VisitorId" : "2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",
        "Custom" : {"some key" : "some value"},
        "HttpTrueClientIp" : "68.72.70.2",
        "UserAgent" : "some agent",
        "Source" : ""
    }
}

Example 1.2 Filtering and sorting the search results (with a field override)

{
    "ClientGuid" : "client_guid",
    "Keyword" : "jack",
    "FieldOverride" : ["itemname", "isonsale"],
    "SortBy" : "saleprice",
    "FacetSelections": {
        "pricerange": ["1,25"],
        "Brand": [
          "Columbia Sportswear",
          "Patagonia"
        ],
        "zip_postal_code_range": ["ba3,bl6"]
    },
    "ClientData":{
          "VisitorId" : "2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",
          "Custom" : {"some key" : "some value"},
          "HttpTrueClientIp" : "68.72.70.2",
          "UserAgent" : "some agent",
          "Source" : ""
    }
}

Example 1.3 Retrieving Landing Page contents

{
    "ClientGuid" : "client_guid",
    "CustomUrl" : "/best-sellers",
    "ClientData":{
          "VisitorId" : "2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",
          "Custom" : {"some key" : "some value"},
          "HttpTrueClientIp" : "68.72.70.2",
          "UserAgent" : "some agent",
  "Source" : ""
     }
}

Example 1.4 Pagination selections

{
    "ClientGuid" : "client_guid",
    "keyword" : "jacket",
    "PageNo" : 3,
    "MaxPerPage" : 24
}

Example Max Per Page override

Entering MaxPerPage equal to 0 in the request will return only facets, no result documents:

Request:
{
    "ClientGuid" : "client_guid",
    "MaxPerPage" : 0
}

Response:
{
    "Facets": [
        {
            "FacetId": 1,
            "Name": "Department",
            "Field": "department_nest",
            "FieldType": "string",
             ....
        }
    ],
    "Success": true,
    "Pagination": {
        "NofResults": 2400,
        "CurrentPage": 0,
        "MaxPerPage": 0,
        "NofPages": 0,
        "Items": [],
        "IsShowFirstLink": true,
        "IsShowLastLink": true,
        "NumberOfPageLinks": 5
    },
    "Keyword": "",
    "Results": [],
	...
}

Example Filtering results with a Facet Override parameter

To return an array of facets, the associated facet field names should be provided:

{
    "ClientGuid" : "client_guid",
    "FacetOverride" : ["department_nest", "price"]
}

To return no Facet object an empty array can be passed:

{
    "ClientGuid" : "client_guid",
    "FacetOverride" : [""]
}

Response

Object	Data Type	Always	Description

Object	Data Type	Always	Description
Success	Boolean	Yes	Indicates if the request was successful.
Pagination	Pagination object	Yes	Summary of pagination details and a set of pagination options. See Pagination Object section.
Keyword	String	Yes	The Keyword value that was sent to Hawksearch in the request. If no Keyword was set in request, the value will be empty.
Results	Array of objects	Yes	See Results Object section.
Facets	Array of objects		See Facet Object section.
VisitorTargets	Array of objects		See VisitorTargets Object section.
Selections	Array of objects		See Selections Object section.
Sorting	Sorting Object		See Sorting Object section.
AdjustedKeyword	String	No	If this is populated, it indicates that the Keyword value returned 0 results, but the results in this response are from this AdjustedKeyword. A message should be displayed to the user informing them that their search was corrected to this string. This is the result of Auto Correct, which is configured in the Workbench > Keyword Search > Did You Mean
DidYouMean	Array of strings	Yes	If any strings are returned in the array, they should be displayed to the user as suggested search terms. This is the result of Did You Mean, which is configured in the Workbench > Keyword Search > Did You Mean
Merchandising	Array of objects	No	See Merchandising Object section.
FeaturedItems	Array of objects	No	See FeaturedItems Object section.
SearchDuration	Numeric	Yes	Number of milliseconds
Redirect	Redirect Object		See Redirect Object section.
PageContent	PageContent Object		See PageContent Object section.

Example 1.5

The basic structure of the response. Individual examples of the arrays can be found in the Objects section.

{
    "Success": true,
    "Pagination": {},
    "Keyword": "jacket",
    "Results": [],
    "Facets": [],
    "Selections": {},
    "Sorting": {},
    "DidYouMean": [],
    "Merchandising": {},
    "FeaturedItems": {},
    "SearchDuration": 12
}

Compare

The compare method is to be called when users willing to compare one or more items. This is a full API version of the compare.

Request

Endpoint	Method	Header Key

Endpoint	Method	Header Key
api/v2/compare	POST	Content-Type: application/json

Name	Data Type	Required	Description

Name	Data Type	Required	Description
ClientGuid	String	required	API Client Guid
Ids	Array of strings	required	An array of unique identifiers of items that will be compare. The maximum number of items to be compared at one time cannot exceed five.
FieldOverride	Array of strings	optional	An array of field names that if passes, Hawksearch will return in a response. If not specified response will return all fields marked as "Include in Results" in dashboard.
IndexName	String	optional	The name of the index that should be queried to get compared items data.

Example 2.2

{
"ClientGuid": "client_guid",
"Ids": [
"Item_147628",
"Item_147844"
],
"FieldOverride": [
"itemname",
"price",
"imagealttag",
"sku"
]
}

Response

Object	Data Type	Always	Description

Object	Data Type	Always	Description
Success	Boolean	Yes	Indicates if request was successful.
Results	Array of objects	Yes	See Compare Results Object section.

Example 3.2

{
    "Success": true,
    "Results": [
        {
            "DocId": "Item_147844",
            "Score": 1,
            "Document": {
                "imagealttag": {
                    "value": [
                        "GLACIAL-FLEECE-HALF-ZIP-JACKET-Fuse-Green-Grill"
                    ],
                    "compare": false
                },
                "price": {
                    "value": [
                        "+0000000000000030.0000"
                    ],
                    "compare": false
                },
                "itemname": {
                    "value": [
                        "Boy's Glacial Half Zip Jacket Junior"
                    ],
                    "compare": false
                },
                "sku": {
                    "value": [
                        "\r\n    "
                    ],
                    "compare": true
                }
            }
        },
        {
            "DocId": "Item_147628",
            "Score": 1,
            "Document": {
                "imagealttag": {
                    "value": [
                        "GIRLS-PEARL-PLUSH-FULL-ZIP-Bright-Plum-Black"
                    ],
                    "compare": false
                },
                "price": {
                    "value": [
                        "+0000000000000060.0000"
                    ],
                    "compare": false
                },
                "itemname": {
                    "value": [
                        "Girl's Pearl Plush Full Zip Junior"
                    ],
                    "compare": false
                },
                "sku": {
                    "value": [
                        "\r\n    "
                    ],
                    "compare": true
                }
            }
        }
    ]
}

Objects

FAQs

Where do I find the ClientGuid?

When logged into the Hawksearch Workbench, click on the account icon found on the right side of the top bar, next to the logout icon. When your account page loads, look at the bottom where the Tracking Key Guid is displayed.

How does Autocorrect work?

When turned on in the Workbench (Keyword Search > Did You Mean > Auto Correct), Auto Correct will get triggered when the engine initially finds zero results with the keyword passed. Before returning a response to the front-end, the engine will evaluate other terms to see if a close match exists. The values that are used in this comparison are the values of fields where the “Include in dictionary” is set to “on.”

The Minimum Score slider found on the admin screen below is used to set the minimum score match for compared keywords. The higher the value on this slider, the more selective the comparison will be when finding a close match.

Hawksearch Knowledge Base

Hawksearch v4.0 - Search API

Search API Methods

Search V2

Request

Example SmartBar

Response

Search

Request

Response

Example 1.5

Compare

Request

Example 2.2

Response

Example 3.2

FAQs

Where do I find the ClientGuid?

How does Autocorrect work?

Related content