Search API
API Docs
Detailed technical documentation is available here - Search API Documentation
Domains
HawkSearch has three environments available: Development, Test and a load-balanced Production. When using the search API methods in this document, the following domains can be used to access each environment after your engine has been set-up in that environment.
Before You Begin
Please ensure that your client-specific endpoints are configured before implementing any API integrations. Please refer to this article to learn more about client-specific endpoints and reach out to our CSD team for any questions.
Development
client-specific URL: https://enginename.dev.searchapi-na.hawksearch.com
Configurations for an engine in this location are maintained in the HawkSearch Workbench at dev.hawksearch.net.
Test
client-specific URL: https://enginename.test.searchapi-na.hawksearch.com
Configurations for an engine in this location are maintained in the HawkSearch Workbench at test.hawksearch.net.
Production
client-specific URL: https://enginename.searchapi-na.hawksearch.com
Configurations for an engine in this location are maintained in the Hawksearch Workbench at dashboard-na.hawksearch.com.
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 |
|---|---|---|
| api/v2/search | POST | Content-Type: application/json |
| X-HawkSearch-IgnoreTracking: true/false |
X-HawkSearch-IgnoreTracking key disables tracking in this instance. The value is set to false by default
Parameters
| Name | Data Type | Required | Description | Source or Admin Section |
|---|---|---|---|---|
| ClientGuid | String | Yes | API Client Guid | Tracking Key found in Admin > Account Info |
| RequestType | String | No | This field determines how the search engine processes and interprets the input provided in the "Keyword" field. The value should be one of the following: 1. DefaultSearch: This is the default operation for search queries. If the RequestType field is not specified or is explicitly set to "DefaultSearch", the search engine performs a normal keyword search. 2. ConceptSearch: This search type is designed to interpret natural language more effectively, enabling the engine to return results that are contextually and semantically related to the query, even if the exact keywords are not present in the content. 3. ImageSearch: In this search type, the engine processes image data or descriptions of images provided in the "Keyword" field to find and return relevant images or items. This is particularly useful for searches where visual similarity or content is more important than textual keyword matching. 4. UnifiedSearch: This search type combines multiple search capabilities, keyword, concept, and image search (if enabled), into a single query. By setting RequestType to "UnifiedSearch", the engine processes the input to return a broader set of relevant results. | Configuration of the Concept Search and Image Search can be found in: 1. Concept Search: Workbench >>> Concept Search 2. Image Search: Workbench >>> Image Search |
| Keyword | String | No | 1. When the RequestType is set to DefaultSearch (a.k.a Keyword Search): This field represent the 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. 2. When Concept Search is enabled and RequestType is set to ConceptSearch: This field is used to capture the user’s query to conduct a more thematic or contextual search. 3. When Image Search is enabled and the RequestType is set to ImageSearch: This field is used to capture the user’s query to conduct a image search with description of images. | Entered by the user. |
| ImageData | String | No | This field should be the Base64-encoded representation of the image you wish to search with (i.e. the one user uploaded). Before submitting an Image Search request, please ensure the image is properly converted to Base64 format. | Configuration of the Image Search can be found in: Image Search: Workbench >>> Image Search |
| kValue | Number | No | This is a critical parameter that determines the number of nearest neighbor results to return for a given search query in Concept and Image Search. The default "kValue" is set to 3. Adjusting the "kValue" can significantly affect the search outcomes: 1. Increasing "kValue" allows for a broader set of results, potentially capturing more items that are less similar to the search input. This can be useful for more comprehensive searches where broader results are desired.2. Decreasing "kValue" narrows down the results, focusing on the closest matches to the query. This is beneficial for highly targeted searches where only the most relevant results are required. | |
| IndexName | String | No | 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 | No | 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 | No | 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 | No | 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. | Valid values are configured in Workbench > Data Configuration > Sorting/Pagination |
| SortBy | String | No | 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 | No | 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 | No | 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 | No | 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 []> | No | 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 | Array of strings | No | 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. | 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 |
| FacetHierarchyLevelOverride | Dictionary<string, object> | No | Allows overriding facet hierarchy levels for specified facets. Options for StartLevel and EndLevel. | Configurable in Workbench > Data Configuration > Facets > Add/Edit Facet > Checkbox & Link List > Parent/Top Level of Hierarchy |
| FieldOverride | Array of strings | No | 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 | No | See Client Data Object section. | |
| IsInPreview | Boolean | No | 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 | No | 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 | No | 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 | No | This is used to enable or disable Boost and Bury Rules. | Workbench > Merchandising > Boost & Bury Rules |
| > VisibilityRules | Boolean | No | This is used to enable or disable Visibility Rules. | Workbench > Merchandising > Visibility Rules |
| > PersonalizedBoost | Boolean | No | This is used to enable or disable the boost for Recommended Items. | Workbench > Edit Boost for Recommended Items |
| > PopularityBoost | Boolean | No | This is used to enable or disable the boost for Learning Search Multiplier. | Workbench > Edit Learning Search Multiplier |
| > ItemPin | Boolean | No | This is used to enable or disable Pinning Rules. | Workbench > Merchandising > Item Pinning |
| > PopularitySalesBoost | Boolean | No | This is used to enable or disable the boost for Orders Multiplier | Workbench > Keyword Search > AI Based Multipliers > Order Multiplier |
| > PopularityAdd2CartBoost | Boolean | No | This is used to enable or disable the boost for Add2Carts Multiplier | Workbench > Keyword Search > AI Based Multipliers > Add2Carts Multiplier |
| Is100CoverageTurnedOn | Boolean | No | 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 | No | 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 | No | Collection of boosting objects | For examples, see Dynamic Query Boost Search |
| > query | Alphanumeric string | No | The field(s) and value(s) to be searched for | |
| > boost | Integer | No | The boost value for the particular filter provided by the query parameter | |
| Variant | Object | No | See Variant Object Section | Hawksearch 4.0 Variants |
Examples
{
"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
}
}
Examples - Facet Hierarchy Level Override
{
"ClientGuid":"{{client_guid}}",
"FacetOverride":["department_nest"],
"FacetHierarchyLevelOverride":{
"department_nest" :{
"StartLevel":3,
"EndLevel" : 3
}
}
}
Response
| Name | Data Type | Required | 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 Featured Items 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 |
|---|---|---|
| api/search | POST | Content-Type: application/json |
| X-HawkSearch-IgnoreTracking: true/false |
X-HawkSearch-IgnoreTracking key disables tracking in this instance. The value is set to false by default
Parameters
| Name | Data Type | Required | Description | Source or Admin Section |
|---|---|---|---|---|
| ClientGuid | String | Yes | API Client Guid | Tracking Key found in Admin > Account Info |
| Keyword | String | No | 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 | No | 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 | No | 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 | No | 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. | Valid values are configured in Workbench > Data Configuration > Sorting/Pagination |
| SortBy | String | No | 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 | No | 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 | No | 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 | No | 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[]> | No | 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 | Array of strings | No | 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 | Array of strings | No | 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 | No | See Client Data Object section. | |
| IsInPreview | Boolean | No | 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 | No | 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 | No | 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 | No | This is used by the Hawksearch Preview to enable or disable Boost and Bury Rules. | Workbench > Merchandising > Boost & Bury Rules |
| > VisibilityRules | Boolean | No | This is used by the Hawksearch Preview to enable or disable Visibility Rules. | Workbench > Merchandising > Visibility Rules |
| > PersonalizedBoost | Boolean | No | This is used by the Hawksearch Preview to enable or disable the boost for Recommended Items. | Workbench > Edit Boost for Recommended Items |
| > PopularityBoost | Boolean | No | This is used by the Hawksearch Preview to enable or disable the boost for Learning Search Multiplier. | Workbench > Edit Learning Search Multiplier |
| > ItemPin | Boolean | No | This is used by the Hawksearch Preview to enable or disable Pinning Rules. | Workbench > Merchandising > Item Pinning |
| Is100CoverageTurnedOn | Boolean | No | 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 | No | Use this to perform searches on one or more specific fields without needing to create facets for them. | For examples, see Field-specific Search |
| BoostQuery | String | No | Use this to perform boosts on one or more specific fields. | For examples, see Field-Boost Search |
Examples
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
| Name | Data Type | Required | 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 | No | See Facet Object section. |
| VisitorTargets | Array of objects | No | See VisitorTargets Object section. |
| Selections | Array of objects | No | See Selections Object section. |
| Sorting | Sorting object | No | 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 Featured Items Object section. |
| SearchDuration | Numeric | Yes | Number of milliseconds |
| Redirect | Redirect object | No | See Redirect Object section. |
| PageContent | PageContent object | No | See Page Content Object section. |
Examples
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 |
|---|---|---|
| api/v2/compare | POST | Content-Type: application/json |
Parameters
| Name | Data Type | Required | Description |
|---|---|---|---|
| ClientGuid | String | Yes | API Client Guid |
| Ids | Array of strings | Yes | 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 | No | 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 | No | The name of the index that should be queried to get compared items data. |
Examples
Example 2.2
{
"ClientGuid": "client_guid",
"Ids": [
"Item_147628",
"Item_147844"
],
"FieldOverride": [
"itemname",
"price",
"imagealttag",
"sku"
]
}
Response
| Name | Data Type | Required | Description |
|---|---|---|---|
| Success | Boolean | Yes | Indicates if request was successful. |
| Results | Array of objects | Yes | See Compare Results Object section. |
Examples
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
Pagination Object
A pagination object will always be returned in the response from the Search method, even if there are 0 results. Pagination settings can be configured in the Hawksearch Workbench. The configurations include how many results appear per page, the default number per page and the display value for the user.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| NoOfResults | Number | Yes | Number of total items in the result set. |
| CurrentPage | Number | Yes | The page number returned |
| MaxPerPage | Number | Yes | The number of items returned for the page. Entering 0 in the request will return only facets, no documents. |
| NoOfPages | Number | Yes | The total number of pages for the result set (with the current MaxPerPage) |
| Items | Array of objects | Yes | Set of pagination options |
| > Label | String | Yes | Display label for user’s pagination option (i.e. 24 per page) |
| > PageSize | Number | Yes | Maximum number of items that will be returned per page when this option is selected. |
| > Selected | Boolean | Yes | True or false, indicating if this is the option selected. Only 1 Pagination Item will have Selected=true. |
| > Default | Boolean | Yes | True or false, indicating if this is the default option. Only 1 Pagination Item will have Selected=true. |
| IsShowFirstLink | Boolean | Yes | True or false, indicating if a link to the first page should be displayed. This is configured Workbench > Data Configuration > Sorting/Pagination > Show First Link |
| IsShowLastLink | Boolean | Yes | True or false, indicating if a link to the last page should be displayed. This is configured Workbench > Data Configuration > Sorting/Pagination > Show Last Link |
| NumberOfPagesLink | Number | Yes | This is the number of page links that should be displayed to the user. This is configured Workbench > Data Configuration > Sorting/Pagination > Number of Page Links |
Examples
Example 10.1 - An object in a response with no results:
"Pagination": {
"NofResults": 0,
"CurrentPage": 1,
"MaxPerPage": 12,
"NofPages": 1,
"Items": [
{
"Label": "12 Items Per Page",
"PageSize": 12,
"Selected": true,
"Default": true
},
{
"Label": "24 Items Per Page",
"PageSize": 24,
"Selected": false,
"Default": false
},
{
"Label": "36 Items Per Page",
"PageSize": 36,
"Selected": false,
"Default": false
}
]
}
Example 10.2 - An object in a response with results
"Pagination": {
"NofResults": 91,
"CurrentPage": 1,
"MaxPerPage": 12,
"NofPages": 7,
"Items": [
{
"Label": "12 Items Per Page",
"PageSize": 12,
"Selected": true,
"Default": true
},
{
"Label": "24 Items Per Page",
"PageSize": 24,
"Selected": false,
"Default": false
},
{
"Label": "36 Items Per Page",
"PageSize": 36,
"Selected": false,
"Default": false
}
]
}
Results Object
The Results Object is returned in the Search method and the Autocomplete method.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| Results | Array of objects | Yes | An entry in the array for each item returned in search results. |
| DocId | String | Value of the unique key | |
| Score | Number | The relevancy score that has been calculated by the Hawksearch engine. | |
| Document | Contains properties | Contains the fields assigned to each item. This is driven by the fields defined in Hawksearch Workbench. | |
| BestFragment | String | The Best Fragment feature creates synopsis of a larger field that can be used for display. The types of field that utilized this feature are: Long Description, Title, Content (body content), or Name. This is configured in Workbench > Data Configuration > Fields | |
| Explain | Contains properties | Explain will only shown when "IsInPreview" is set to "true" | |
| > TotalBoost | Number | The sum of the boost of all the Boost & Bury rules applied. | |
| > Rules | Array of objects | ||
| >> IsTrigger | Boolean | true: The rule is activated only when predefined conditions are met. false: The rule is universally applied, independent of any conditions. | |
| >> Name | String | Name of the Boost & Bury rule applied | |
| >> RuleId | Number | The id of this rule | |
| >> Boost | Number | The boost value of this rule. Value is configured in Workbench > Merchandising > Boost & Bury Rules > Add/Edit Boost & Bury Rule > Select Items to Boost | |
| >> Priority | Number | The priority of this rule | |
| > VisibilityRules | Array of objects | Visbility rules will only shown when "VisibilityRules" within "SmartBar" Object is set to "false" | |
| >> IsTrigger | Boolean | true: The rule is activated only when predefined conditions are met. false: The rule is universally applied, independent of any conditions. | |
| >> Name | String | Name of the Visibility rule applied | |
| >> RuleId | Number | The id of this rule | |
| >> Priority | Number | The priority of this rule | |
| IsPin | Boolean | True or false, indicating if the record has been pinned into its place. Pinning is configured in Preview or in Workbench > Merchandising > Item Pinning |
Examples
Example 11.1 - The values in the Document object will vary. This is dependent on the fields that are configured in your Hawksearch engine workbench, and the fields that are flagged to be included in the results.
{
"DocId": "Item_119547",
"Score": 775.7318,
"Document": {
"image": [
"http://test.hawksearch.net/assets/1/14/DimThumbnail/Womens-Trabagon-Rain-Jacket-Watermelon.jpg"
],
"itemname": [
"Women's Trabagon Rain Jacket"
],
"isonsale": [
"Yes"
],
"size-property": [
"Small",
"Medium",
"Large",
"Extra Large"
],
"color-property": [
"Black",
"Blue",
"Red",
"Pink",
"Green"
],
"itemtypeid": [
"3"
],
"saleprice": [
"+0000000000000039.9700"
],
"rating": [
"+0000000000000003.0000"
],
"type": [
"Item"
],
"url": [
"/details.aspx?itemid=Item_119547"
],
"ratingrange": [
"+0000000000000003.0000"
],
"imagealttag": [
"Womens-Trabagon-Rain-Jacket-Watermelon"
],
"subdepartmentpath": [
"1|Summer Sale",
"1|Specials",
"1|Women",
"1|Sale"
],
"price": [
"+0000000000000060.0000"
],
"department_nest": [
"1|Summer Sale",
"2|Summer Sale/Women",
"3|Summer Sale/Women/Jackets",
"1|Women",
"2|Women/Jackets",
"3|Women/Jackets/Casual Jackets",
"3|Women/Jackets/Rain Jackets",
"1|Specials",
"2|Specials/Sat Dec 15th",
"3|Specials/Sat Dec 15th/Kids",
"3|Specials/Sat Dec 15th/Women's"
],
"id": [
"Item_119547"
],
"sku": [
"\r\n "
],
"brand": [
"White Sierra"
]
}
}
Example 11.2 - An example of the complete Explain object when "IsInPreview" is set to "true", and "VisibilityRules" is set to "false"
"Explain": {
"TotalBoost": 300.0,
"Rules": [
{
"IsTrigger": false,
"Name": "Joe Rule",
"RuleId": 30489,
"Boost": 100.0,
"Priority": 1
},
{
"IsTrigger": false,
"Name": "Global test with current month",
"RuleId": 56645,
"Boost": 200.0,
"Priority": 2
},
{
"IsTrigger": false,
"Name": "Current Year Boost And Bury Rule",
"RuleId": 56630,
"Boost": 0.0,
"Priority": 3
}
],
"VisibilityRules": [
{
"IsTrigger": false,
"Name": "HSP-159 Test ",
"RuleId": 30546,
"Priority": 1
}
]
}
Selections Object
The Selections Object may be contained in the response from the Search method.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| Selections | Set of object | Yes | Will contain an entry for each facet that has one or more selections. Will be empty if no facet selections have been made. |
| > [field name of facet] | |||
| >> Label | String | Display name for facet | |
| >> Items | Array of objects | Will contain an entry for each selection made within the facet. | |
| >>> Label | String | Display label for facet value | |
| >>> Value | String | Value for facet value. If this is an OpenRange type of facet, this string holds the lower and upper bounds that were entered. |
Examples
Example 12.1
"Selections": {
"brand": {
"Label": "Brand",
"Items": [
{
"Label": "Marmot",
"Value": "Marmot"
},
{
"Label": "Columbia Sportswear",
"Value": "Columbia Sportswear"
}
]
},
"isonsale": {
"Label": "On Sale",
"Items": [
{
"Label": "Yes",
"Value": "Yes"
}
]
}
}
Example 12.2
"Selections": {
"zip_postal_code_range": {
"Label": "Postal Code",
"Items": [
{
"Label": "ba3,bl6",
"Value": "ba3,bl6"
}
]
}
}
Sorting Object
The Sorting Object may be contained in the response from the Search method.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| Items | Array of objects | Yes | |
| > Label | String | Yes | Name of the sorting option. This is the label to display to users. |
| > Value | String | Yes | The value to be used to specify the sort order once user selects it. This value is passed in the SortBy object in the Search method. |
| > IsDefault | Boolean | Yes | Indicates if this sorting option was configured to be the default. |
| > Selected | Boolean | Yes | Indicates if this sorting option is currently being used for the current result set. |
Examples
The sorting options returned depend on the configuration in the Hawksearch Workbench > Data Configuration > Sorting/Pagination.
Example 13.1
"Sorting": {
"Items": [
{
"Label": "Best Match",
"Value": "score",
"IsDefault": true,
"Selected": true
},
{
"Label": "Title (A-Z)",
"Value": "titleasc",
"IsDefault": false,
"Selected": false
},
{
"Label": "Title (Z-A)",
"Value": "titledesc",
"IsDefault": false,
"Selected": false
},
{
"Label": "Price: Lowest to Highest",
"Value": "salepriceasc",
"IsDefault": false,
"Selected": false
},
{
"Label": "Price: Highest to Lowest",
"Value": "salepricedesc",
"IsDefault": false,
"Selected": false
}
]
}
Merchandising Object
Merchandising can be placed by using Campaigns in the Hawksearch Workbench. The Campaign will determine if the content should appear and in what zone. The Merchandising Object may be contained in the response from the Search method.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| Merchandising | Array of objects | Yes | |
| > Items | Array of objects | Yes | |
| >> Zone | String | Yes | The name of the zone in which the content should be placed. The zone names are configured in the Hawksearch Workbench > Merchandising > Campaigns > Zones |
| >> Title | String | Yes | The title of the Campaign that is triggering this content to appear. Not intended to display to the user. |
| >> CampaignId | Integer | Yes | The id of the Campaign that is triggering this content to appear. Not intended to display to the user. |
| >> BannerId | Integer | Yes | The id of the Banner that is triggering this content to appear. Not intended to display to the user. |
| >> ContentType | String | Yes | Value can be “image,” “custom,” or “widget.” (Further custom programming required to use the “widget” type.) |
| >> ImageUrl | String | No | If ContentType=image, this holds the url where the image is located. |
| >> AltTag | String | No | If ContentType=image, this may be included with the value to be used as the Alt Tag value. |
| >> ForwardUrl | String | No | If ContentType=image, this may be included. If present, the image should be linkable to the URL provided in the ForwardUrl object. |
| >> Output | String | No | If ContentType=custom, the Output object will contain the HTML to display. |
| >> IsMobile | Boolean | Yes | Indicates of this content piece was flagged for mobile in the Workbench > Merchandising > Content Items |
| >> MobileContentType | String | No | Value can be “image,” “custom,” or “widget.” (Further custom programming required to use the “widget” type.) It will be sent if the IsMobile object is True. |
| >> MobileImageUrl | String | No | If MobileContentType=image, this holds the url where the image is located. |
| >> MobileWidgetArgs | String | No | Reserved for the ContentType=widget. (Further custom programming required to use the “widget” type.) |
| >> IsTrackingEnabled | Boolean | Yes | Indicates of this content piece was flagged to have tracking enabled in the Workbench > Merchandising > Content Items |
| >> MobileIsTrackingEnabled | Boolean | No | Indicates if this content piece was flagged to have tracking enabled for mobile in the Workbench > Merchandising > Content Items |
| >> Target | String | No | If the Target setting on the content item is “same window,” this object will not be included in the response. If the Target setting on the content item is “new window,” this object will hold a string, “_blank” |
| >> MobileAltTag | String | No | If MobileContentType=image, this may be included with the value to be used as the Alt Tag value. |
| >> MobileForwardUrl | String | No | If MobileContentType=image, this may be included. If present, the image should be linkable to the URL provided in the MobileForwardUrl object. |
| >> MobileWidth | String | No | Width of image provided in MobileImageUrl. |
| >> MobileHeight | String | No | Height of image provided in MobileImageUrl. |
| >> MobileTarget | String | No | If the Mobile Target setting on the content item is “same window,” this object will not be included in the response. If the Mobile Target setting on the content item is “new window,” this object will hold a string, “_blank”. |
| >> IsTablet | Boolean | Yes | Indicates of this content piece was flagged for tablet in the Workbench > Merchandising > Content Items |
| >> TabletContentType | String | No | Value can be “image,” “custom,” or “widget.” (Further custom programming required to use the “widget” type.) It will be sent if the IsTablet object is True. |
| >> TabletImageUrl | String | No | If TabletContentType=image, this holds the url where the image is located. |
| >> TabletIsTrackingEnabled | Boolean | No | Indicates if this content piece was flagged to have tracking enabled for tablet in the Workbench > Merchandising > Content Items |
| >> TabletAltTag | String | No | If TabletContentType=image, this may be included with the value to be used as the Alt Tag value. |
| >> TabletForwardUrl | String | No | If TabletContentType=image, this may be included. If present, the image should be linkable to the URL provided in the TabletForwardUrl object. |
| >> TabletWidth | String | No | Width of image provided in TabletImageUrl. |
| >> TabletHeight | String | No | Height of image provided in TabletImageUrl. |
| >> TabletTarget | String | No | If the Tablet Target setting on the content item is “same window,” this object will not be included in the response. If the Tablet Target setting on the content item is “new window,” this object will hold a string, “_blank”. |
| >> TabletOutput | String | No | If ContentType=custom, the Output object will contain the HTML to display. |
| >> TabletWidgetArgs | String | No | Reserved for the ContentType=widget. (Further custom programming required to use the “widget” type.) |
Examples
Example 14.1
{
"Zone": "Bottom",
"Title": "Free Shipping",
"ContentType": "image",
"ImageUrl": "http://dev.hawksearch.net/sites/elasticdemo//assets/1168/FreeShipping.jpg",
"AltTag": "Free Shipping",
"ForwardUrl": "http://www.google.com",
"IsMobile": false,
"IsTrackingEnabled": true,
"MobileIsTrackingEnabled": false,
"CampaignId": 12345,
"BannerId": 67890,
"IsTablet": false
}
Example 14.2
{
"Zone": "LeftBottom",
"Title": "Popular Tags",
"ContentType": "widget",
"Output": [
{
"keyword": "jacket",
"count": 41
},
{
"keyword": "test",
"count": 40
},
{
"keyword": "keen",
"count": 21
}
],
"IsMobile": false,
"IsTrackingEnabled": false,
"CampaignId": 12345,
"BannerId": 67890,
"IsTablet": false
}
Featured Items Object
The Featured Items Object may be contained in the response from the Search method.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| FeaturedItems | Array of objects | Yes | |
| > Items | Array of objects | Yes | |
| >> Zone | String | Yes | The name of the zone in which the content should be placed. The zone names are configured in the Hawksearch Workbench > Merchandising > Campaigns > Zones |
| >> Title | String | Yes | The title of the Campaign that is triggering this content to appear. Not intended to display to the user. |
| >> CampaignId | Integer | Yes | The id of the Campaign that is triggering this content to appear. Not intended to display to the user. |
| >> BannerId | Integer | Yes | The id of the Banner that is triggering this content to appear. Not intended to display to the user. |
| >> ContentType | String | Yes | Value can be “image,” “custom,” or “widget.” (Further custom programming required to use the “widget” type.) |
| >> ImageUrl | String | No | If ContentType=image, this holds the url where the image is located. |
| >> AltTag | String | No | If ContentType=image, this may be included with the value to be used as the Alt Tag value. |
| >> ForwardUrl | String | No | If ContentType=image, this may be included. If present, the image should be linkable to the URL provided in the ForwardUrl object. |
| >> Output | String | No | If ContentType=custom, the Output object will contain the HTML to display. |
| >> IsMobile | Boolean | Yes | Indicates of this content piece was flagged for mobile in the Workbench > Merchandising > Content Items |
| >> MobileContentType | String | No | Value can be “image,” “custom,” or “widget.” (Further custom programming required to use the “widget” type.) It will be sent if the IsMobile object is True. |
| >> MobileImageUrl | String | No | If MobileContentType=image, this holds the url where the image is located. |
| >> MobileWidgetArgs | String | No | Reserved for the ContentType=widget. (Further custom programming required to use the “widget” type.) |
| >> IsTrackingEnabled | Boolean | Yes | Indicates of this content piece was flagged to have tracking enabled in the Workbench > Merchandising > Content Items |
| >> MobileIsTrackingEnabled | Boolean | Yes | Indicates if this content piece was flagged to have tracking enabled for mobile in the Workbench > Merchandising > Content Items |
| >> Target | String | No | If the Target setting on the content item is “same window,” this object will not be included in the response. If the Target setting on the content item is “new window,” this object will hold a string, “_blank”. |
| >> MobileAltTag | String | No | If MobileContentType=image, this may be included with the value to be used as the Alt Tag value. |
| >> MobileForwardUrl | String | No | If MobileContentType=image, this may be included. If present, the image should be linkable to the URL provided in the MobileForwardUrl object. |
| >> MobileWidth | String | No | Width of image provided in MobileImageUrl. |
| >> MobileHeight | String | No | Height of image provided in MobileImageUrl. |
| >> MobileTarget | String | No | If the Mobile Target setting on the content item is “same window,” this object will not be included in the response. If the Mobile Target setting on the content item is “new window,” this object will hold a string, “_blank”. |
| >> IsTablet | Boolean | Yes | Indicates of this content piece was flagged for tablet in the Workbench > Merchandising > Content Items |
| >> TabletContentType | String | No | Value can be “image,” “custom,” or “widget.” (Further custom programming required to use the “widget” type.) It will be sent if the IsTablet object is True. |
| >> TabletImageUrl | String | No | If TabletContentType=image, this holds the url where the image is located. |
| >> TabletIsTrackingEnabled | Boolean | No | Indicates if this content piece was flagged to have tracking enabled for tablet in the Workbench > Merchandising > Content Items |
| >> TabletAltTag | String | No | If TabletContentType=image, this may be included with the value to be used as the Alt Tag value. |
| >> TabletForwardUrl | String | No | If TabletContentType=image, this may be included. If present, the image should be linkable to the URL provided in the TabletForwardUrl object. |
| >> TabletWidth | String | No | Width of image provided in TabletImageUrl. |
| >> TabletHeight | String | No | Height of image provided in TabletImageUrl. |
| >> TabletTarget | String | No | If the Tablet Target setting on the content item is “same window,” this object will not be included in the response. If the Tablet Target setting on the content item is “new window,” this object will hold a string, “_blank”. |
| >> TabletOutput | String | No | If ContentType=custom, the Output object will contain the HTML to display. |
| >> TabletWidgetArgs | String | No | Reserved for the ContentType=widget. (Further custom programming required to use the “widget” type.) |
| >> Items | Array of objects | Yes | |
| >>> DocId | String | Yes | Value of the unique key |
| >>> Score | Number | Yes | The relevancy score that has been calculated by the Hawksearch engine. This is not relevant for the product spotlighting. (The same object structure as Results is used.) |
| >>> Document | Array of objects | Yes | Contains the fields assigned to each item. This is driven by the fields defined in Hawksearch Workbench. |
Examples
Example 15.1
"FeaturedItems": {
"Items": [
{
"Zone": "Top",
"Title": "Our Best Rated Jackets",
"ContentType": "featured",
"IsMobile": false
"IsTrackingEnabled": false,
"MobileIsTrackingEnabled": false,
"CampaignId": 12345,
"BannerId": 67890,
"Items": [
{
"DocId": "Item_73519",
"Score": 1,
"Document": {
"image": [
"http://test.hawksearch.net/assets/1/14/DimThumbnail/Patagonia-Womens-Re-Tool-Snap-T-Fleece-Pullover-Tailored-Grey-w-Shock-Pink.jpg"
],
"itemname": [
"Women's Re-Tool Snap-T® Fleece Pullover"
],
"isonsale": [
"No"
],
"size-property": [
"Extra Small",
"Small",
"Medium",
"Large",
"Extra Large"
],
"color-property": [
"Black",
"Red",
"Green",
"Blue",
"Pink",
"Grey"
],
"itemtypeid": [
"3"
],
"saleprice": [
"+0000000000000119.0000"
],
"rating": [
"+0000000000000005.0000"
],
"type": [
"Item"
],
"url": [
"/details.aspx?itemid=Item_73519"
],
"ratingrange": [
"+0000000000000005.0000"
],
"imagealttag": [
"Patagonia-Womens-Re-Tool-Snap-T-Fleece-Pullover-Tailored-Grey-w-Shock-Pink"
],
"subdepartmentpath": [
"1|Specials",
"1|Summer Sale",
"1|Women"
],
"price": [
"+0000000000000119.0000"
],
"department_nest": [
"1|Women",
"2|Women/Jackets",
"3|Women/Jackets/Fleece Jackets",
"1|Summer Sale",
"2|Summer Sale/Women",
"3|Summer Sale/Women/Jackets",
"1|Specials",
"2|Specials/Sat Dec 15th",
"3|Specials/Sat Dec 15th/Women's",
"2|Summer Sale/Packs",
"3|Summer Sale/Packs/Backpacking Packs",
"3|Specials/Sat Dec 15th/Kids"
],
"id": [
"Item_73519"
],
"sku": [
"\r\n "
],
"brand": [
"Patagonia"
]
}
},
{
"DocId": "Item_74040",
"Score": 1,
"Document": {
"image": [
"http://test.hawksearch.net/assets/1/14/DimThumbnail/White-Sierra-Youth-Trabagon-Rain-Jkt-vivid-bright-yellow.jpg"
],
"itemname": [
"Trabagon Rain Jacket / Youth"
],
"isonsale": [
"Yes"
],
"size-property": [
"Extra Small",
"Small",
"Medium",
"Large",
"Extra Large"
],
"color-property": [
"Black",
"Blue",
"Orange",
"Red",
"Pink"
],
"itemtypeid": [
"3"
],
"saleprice": [
"+0000000000000032.9700"
],
"rating": [
"+0000000000000005.0000"
],
"type": [
"Item"
],
"url": [
"/details.aspx?itemid=Item_74040"
],
"ratingrange": [
"+0000000000000005.0000"
],
"imagealttag": [
"White-Sierra-Youth-Trabagon-Rain-Jkt-vivid-bright-yellow"
],
"subdepartmentpath": [
"1|Summer Sale",
"1|Sale",
"1|Specials",
"1|Kids"
],
"price": [
"+0000000000000055.0000"
],
"department_nest": [
"1|Kids",
"2|Kids/Girls 5-20",
"3|Kids/Girls 5-20/Jackets",
"2|Kids/Boys 5-20",
"3|Kids/Boys 5-20/Jackets",
"1|Specials",
"2|Specials/Sun Dec 23rd",
"3|Specials/Sun Dec 23rd/Girls 5-20",
"3|Specials/Sun Dec 23rd/Boys 5-20",
"2|Specials/Sat Dec 15th",
"3|Specials/Sat Dec 15th/Kids",
"2|Specials/Sat Dec 8th",
"3|Specials/Sat Dec 8th/Girl's",
"3|Specials/Sat Dec 8th/Boy's",
"1|Summer Sale",
"2|Summer Sale/Kids",
"3|Summer Sale/Kids/Girls 5-20",
"3|Summer Sale/Kids/Boys 5-20",
"2|Summer Sale/Packs",
"3|Summer Sale/Packs/Backpacking Packs"
],
"id": [
"Item_74040"
],
"sku": [
"\r\n "
],
"brand": [
"White Sierra"
]
}
}]}}
Client Data Object
This object may be contained in the response from the Search method and Autocomplete method.
Description
| Name | Data Type | Required | Description | Notes |
|---|---|---|---|---|
| VisitorId | String | Yes | This is visitor id that is used for tracking. | |
| Custom | String | No | Can be used to send information used for evaluating Visitor Targets. | This is what was previously called ‘hawkcustom.’ The value can be used to trigger a Visitor Target as configured in Workbench > Merchandising > Visitor Tagets. |
| HttpTrueClientIp | String | No | Client IP used for evaluating Visitor Targets. | Should contain the IP address of end user that has made a request for search |
| UserAgent | String | No | Browser user agent used for evaluating Visitor Targets. | Should contain the user agent of end user that has made a request for search |
| Source | String | No | Source used for evaluating Visitor Targets. | This was previously called ‘hawksource.’ Can be used to track the source the user came from (i.e. email, Instagram, etc) |
| > Origin | Origin Object | No | Coordinates to provide current location. | |
| ZipCode | String | No | This parameter is used for zip code search tracking. |
Examples
Example 16.1
"ClientData":{
"VisitorId" : "2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",
"Custom" : {"some key" : "some value"},
"HttpTrueClientIp" : "68.72.70.2",
"UserAgent" : "some agent",
"Source" : ""
}
Example of selecting a Language
Note
Prerequisite: A Visitor target rule needs to be defined as: 'Language is en'
ClientData request:
"ClientData":{
"Custom" : {"language" : "en"}
}
Search response:
"VisitorTargets":[
{
"Id" : "10805",
"Name" : "English"
}
]
Example of selecting a Custom field:
Note
Prerequisite: A Visitor target rule needs to be defined as: 'Custom is product'
ClientData request:
"ClientData":{
"Custom" : {"custom" : "Products"}
}
Search response:
"VisitorTargets":[
{
"Id" : "12345",
"Name" : "Products"
}
]
Products Object
This object is contained in the response from the Autocomplete method.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| Products | Array of objects | Yes | |
| > ProductName | String | Yes | Name of the item (if applicable) |
| > Sku | String | Yes | Sku of the item (if applicable) |
| > Thumb | String | Yes | URL of image of the item (if applicable) |
| > Url | String | Yes | URL of product page (if applicable) |
| > Html | String | Yes | HTML to display the item in autocomplete. |
| > Results | Array of objects | No | This will only be populated if the parameter, DisplayFullResponse, is sent in with ‘true’ as a value. See the Results Object section. |
Examples
This example shows the products in the response when DisplayFullResponse was set to “false.”
Example 17.1
"Products": [
{
"ProductName": "Jack Rabbit SL2 Footprint",
"Sku": "16161093019000",
"Thumb": "<img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Big_Agnes_Jack_Rabbit_SL2_Footprint.png' />",
"Url": "http://dev.hawksearch.net/sites/elasticdemo//details.aspx?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' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Jack Rabbit SL2 Footprint</h1>",
"Results": {
"Score": 0
}
},
{
"ProductName": "Men's Jack SS Polo",
"Sku": "\r\n ",
"Thumb": "<img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Jack-SS-Polo_Nightsky.jpg' />",
"Url": "http://dev.hawksearch.net/sites/elasticdemo//details.aspx?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' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Men's Jack SS Polo</h1>",
"Results": {
"Score": 0
}
},
{
"ProductName": "Boot Jack 25 Downtek",
"Sku": "\r\n ",
"Thumb": "<img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Boot-Jack-24-zm.jpg' />",
"Url": "http://dev.hawksearch.net/sites/elasticdemo//details.aspx?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' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Boot Jack 25 Downtek</h1>",
"Results": {
"Score": 0
}
}
]
Example 17.2
This example shows the products in the response when DisplayFullResponse was set to “true.”
"Products": [
{
"ProductName": "Jack Rabbit SL2 Footprint",
"Sku": "16161093019000",
"Thumb": "<img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Big_Agnes_Jack_Rabbit_SL2_Footprint.png' />",
"Url": "http://dev.hawksearch.net/sites/elasticdemo//details.aspx?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' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Jack Rabbit SL2 Footprint</h1>",
"Results": {
"DocId": "Item_153223",
"Score": 1685.5974,
"Document": {
"image": [
"http://test.hawksearch.net/assets/1/14/DimThumbnail/Big_Agnes_Jack_Rabbit_SL2_Footprint.png"
],
"itemname": [
"Jack Rabbit SL2 Footprint"
],
"isonsale": [
"Yes"
],
"itemtypeid": [
"1"
],
"saleprice": [
"+0000000000000034.9700"
],
"rating": [
"+0000000000000000.0000"
],
"type": [
"Item"
],
"url": [
"/details.aspx?itemid=Item_153223"
],
"ratingrange": [
"+0000000000000000.0000"
],
"imagealttag": [
"Jack Rabbit SL2 Footprint"
],
"subdepartmentpath": [
"1|Sale",
"1|Specials",
"1|Summer Sale",
"1|Camp & Hike"
],
"price": [
"+0000000000000050.0000"
],
"department_nest": [
"1|Camp & Hike",
"2|Camp & Hike/Tents & Shelters",
"3|Camp & Hike/Tents & Shelters/Tent Accessories",
"1|Summer Sale",
"2|Summer Sale/Camp & Hike",
"3|Summer Sale/Camp & Hike/Tents & Shelters",
"1|Specials",
"2|Specials/Sat Dec 15th",
"3|Specials/Sat Dec 15th/Kids"
],
"id": [
"Item_153223"
],
"sku": [
"16161093019000"
],
"brand": [
"Big Agnes"
]
}
}
},
{
"ProductName": "Men's Jack SS Polo",
"Sku": "\r\n ",
"Thumb": "<img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Jack-SS-Polo_Nightsky.jpg' />",
"Url": "http://dev.hawksearch.net/sites/elasticdemo//details.aspx?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' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Men's Jack SS Polo</h1>",
"Results": {
"DocId": "Item_140273",
"Score": 726.0669,
"Document": {
"image": [
"http://test.hawksearch.net/assets/1/14/DimThumbnail/Jack-SS-Polo_Nightsky.jpg"
],
"itemname": [
"Men's Jack SS Polo"
],
"isonsale": [
"Yes"
],
"size-property": [
"Medium",
"Large"
],
"color-property": [
"Blue",
"Grey",
"Brown",
"Green"
],
"itemtypeid": [
"3"
],
"saleprice": [
"+0000000000000043.9700"
],
"rating": [
"+0000000000000002.0000"
],
"type": [
"Item"
],
"url": [
"/details.aspx?itemid=Item_140273"
],
"ratingrange": [
"+0000000000000002.0000"
],
"imagealttag": [
"Jack-SS-Polo_Nightsky"
],
"subdepartmentpath": [
"1|Sale",
"1|Summer Sale",
"1|Summer Clearance",
"1|Specials",
"1|Men",
"1|Deals for Dad"
],
"price": [
"+0000000000000055.0000"
],
"department_nest": [
"1|Men",
"2|Men/Shirts",
"3|Men/Shirts/Casual Shirts",
"1|Specials",
"2|Specials/Sportswear",
"3|Specials/Sportswear/Mens",
"1|Summer Sale",
"2|Summer Sale/Packs",
"3|Summer Sale/Packs/Backpacking Packs",
"2|Specials/Sat Dec 15th",
"3|Specials/Sat Dec 15th/Kids",
"2|Summer Sale/Men",
"3|Summer Sale/Men/Shirts"
],
"id": [
"Item_140273"
],
"sku": [
"\r\n "
],
"brand": [
"Toad&Co"
]
}
}
},
{
"ProductName": "Boot Jack 25 Downtek",
"Sku": "\r\n ",
"Thumb": "<img class='hawk-sqItemImage-thumb' src='http://test.hawksearch.net/assets/1/14/DimThumbnail/Boot-Jack-24-zm.jpg' />",
"Url": "http://dev.hawksearch.net/sites/elasticdemo//details.aspx?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' /></div>\r\n<div class=\"hawk-sqItemContent\">\r\n<h1 class=\"hawk-sqItemName\">Boot Jack 25 Downtek</h1>",
"Results": {
"DocId": "Item_162525",
"Score": 5.6634693,
"Document": {
"image": [
"http://test.hawksearch.net/assets/1/14/DimThumbnail/Boot-Jack-24-zm.jpg"
],
"itemname": [
"Boot Jack 25 Downtek"
],
"isonsale": [
"No"
],
"size-property": [
"Reg Left",
"Long Left"
],
"color-property": [
"Grey",
"Navy"
],
"itemtypeid": [
"3"
],
"saleprice": [
"+0000000000000189.9500"
],
"rating": [
"+0000000000000001.5000"
],
"type": [
"Item"
],
"url": [
"/details.aspx?itemid=Item_162525"
],
"ratingrange": [
"+0000000000000001.5000"
],
"imagealttag": [
"Boot-Jack-24-zm"
],
"subdepartmentpath": [
"1|Specials",
"1|Camp & Hike"
],
"price": [
"+0000000000000189.9500"
],
"department_nest": [
"1|Camp & Hike",
"2|Camp & Hike/Sleeping Bags",
"3|Camp & Hike/Sleeping Bags/Adult Sleeping bags",
"1|Specials",
"2|Specials/Sat Dec 15th",
"3|Specials/Sat Dec 15th/Kids"
],
"id": [
"Item_162525"
],
"sku": [
"\r\n "
],
"brand": [
"Big Agnes"
]
}
}
}
]
Origin Object
This object contains geographical coordinates.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| Latitude | String | Yes | Latitude is the measurement of distance north or south of the Equator. |
| Longitude | String | Yes | Longitude is the measurement east or west of the prime meridian. |
Facet Object
The settings for facets are controlled in the Hawksearch Workbench, in the Facets section, under Data Configuration. Details about these settings are documented in the Hawksearch online help. Click here to view. The Facet Object may be contained in the response from the Search method.
Description
| Name | Data Type | Required | Description |
|---|---|---|---|
| FacetId | Number | Yes | Unique identifier assigned to facet by Hawksearch |
| Name | String | Yes | Display name for the facet. |
| Field | String | Yes | The name of the field that populates the facet values. |
| FieldType | String | Yes | Possible values: string range numeric search |
| FacetType | String | Yes | Possible values: checkbox nestedcheckbox* link nestedlink* slider swatch rating size openRange searchwithin recentsearches relatedsearches * nested facets need additional coding required on Hawksearch side. |
| DisplayType | String | Yes | Possible values: default scrolling truncating This is used in the display of the facet. See the Facet Examples section. |
| MaxCount | Numeric | Yes | Indicates the maximum number of facet values that are being returned. |
| MinHitCount | Numeric | Yes | Indicates the minimum number of results each facet value needs to have in order to be returned. |
| ParamName | String | No | If this is set, it is to be used as the facet name if passed in the FacetSelections. If not set, the value of the Field object would be used. (This is only applicable when a slider and range facets are both configured for the same field.) |
| SortBy | String | Yes | Indicates the sorting logic that is used for this facet’s values. The possible values for this are the parameters for sorting set options that are configured in Workbench > Data Configuration > Sorting/Pagination |
| ExpandSelection | Boolean | Yes | Indicates if the user should be able to apply more than one filter value from this facet. |
| IsNumeric | Boolean | Yes | Indicates if facet values are numeric. |
| IsCurrency | Boolean | Yes | Indicates if facet values are currency (and should be displayed appropriately). |
| IsSearch | Boolean | Yes | Indicates if search is enabled for this facet. If it is enabled, a search box should be available for users to filter the facet values by typing in the search box. |
| ScrollHeight | Number | Yes | If facet display type is Scrolling, this value is the height in pixels for the window inside scroll box. Only to be used if DisplayType is “scrolling.” |
| ScrollThreshold | Number | Yes | If the number of facet values exceeds this number and DisplayType is “scrolling,” then the facet should be displayed as scrolling list; if not, display as “default.” |
| TruncateThreshold | Number | Yes | If the number of facet values exceeds this number and DisplayType is “truncate,” then the facet should be displayed as truncated list; if not, display as “default.” |
| Tooltip | String | No | Text to display when user hovers over a help icon. |
| SearchThreshold | Number | Yes | To be used if IsSearch=true. The number of facet values must be this number or higher for the facet search box to display. |
| AlwaysVisible | Boolean | Yes | If false, indicates that sometimes this facet will not be returned. The conditions that trigger its display are maintained in the Workbench. |
| NumericPrecision | Number | Yes | his is an optional configuration when facets are FieldType of numeric. This number indicates how many decimal places should be displayed for the numeric values in this facet's value list. |
| Showfacetimagecount | Boolean | Yes | If FieldType=Range, this indicates if the items count should be displayed next to the range value. |
| IsCollapsible | Boolean | Yes | Indicates if the facet can be collapsed and expanded by the user. |
| IsCollapsedDefault | Boolean | Yes | If IsCollapsible=true, this indicates if the facet should initially be collapsed or expanded. |
| SortOrder | Numeric | Yes | The display order of the facet in the facet list. |
| IsVisible | Boolean | Yes | Indicates if the facet is set to be visible. This may be returned as No if all records in the results set all have the same value(s) for the facet. |
| NofVisible | Numeric | Yes | This is maximum number of values that could be returned for the facet. |
| Height | Numeric | Yes | Same as ScrollHeight |
| SwatchData | Array of objects | No | Will be included if FacetType is ‘swatch.’ See example of swatch facet in Example 18.3. |
| > Value | String | Yes | Match this value to the Value object in the Values array. |
| > AssetName | String | Yes | Name of the asset |
| > AssetUrl | String | Yes | URL of the asset |
| > IsDefault | Boolean | Yes | Indicates if value is the default. |
| > Color | String | Yes | Color of the asset. |
| FacetRangeDisplayType | Numeric | Yes | Indicates type of facet range display |
| PreloadChildren | Boolean | Yes | Indicates if setting in Workbench is set to On or Off. |
| ShowSliderInputs | Boolean | Yes | To be used if FacetType is ‘slider’. If ShowSliderInputs is true, input boxes should be available for user to enter values. |
| Ranges | Array of objects | Yes | Always present, but will only be populated if the facet is numeric and not a slider |
| > Label | String | Yes | Label of the value to display |
| > Value | String | Yes | Value to use when setting the facet value selection |
| > IsNumeric | Boolean | Yes | Indicates if the values are numeric |
| > LBound | String | Yes | Lower value of the range |
| > UBound | String | Yes | Upper value of the range |
| Values | Array of objects | ||
| > Label | String | No | Label of the value to display |
| > Value | String | No | Value to use when setting the facet value selection |
| > Count | Numeric | Yes | Number of results in current set that have this facet value |
| > Selected | Boolean | Yes | Indicates if this facet value has been selected |
| > RangeStart | String | No | Used for displaying the slider facet. RangeStart indicates what the starting point of the range to display, either on basis of what the user selected by sliding the slider, or if they have no selection it reflects the lowest price product. |
| > RangeEnd | String | No | Used for displaying the slider facet. RangeEnd indicates what the end point of the range to display is, either on basis of what the user selected by sliding the slider, or if they have no selection, it reflects the highest price product. |
| > RangeMin | String | No | Used for displaying the slider facet. RangeMin indicates lowest value for the range in the list of products displayed. |
| > RangeMax | String | No | Used for displaying the slider facet. RangeMax indicates highest value for the range in the list of products displayed. |
| > Path | String | No | Used for nested facets |
| > Level | Numeric | No | Used for nested facets. Returned only in v2 of Search API |
| > Children | Array of objects | No | Used for nested facets. Returned only in v2 of Search API. Since V2 of API returns nested facet values in hierarchy form, children is an array of Values. |
Examples
Example 18.1 Link List – Searchable, Collapsible, Truncated
{
"FacetId": 272,
"Name": "Brand",
"Field": "brand",
"FieldType": "string",
"FacetType": "link",
"DisplayType": "truncating",
"MaxCount": 200,
"MinHitCount": 1,
"ParamName": "brand",
"SortBy": "6",
"ExpandSelection": true,
"IsNumeric": false,
"IsCurrency": false,
"IsSearch": true,
"ScrollHeight": 250,
"ScrollThreshold": 10,
"TruncateThreshold": 10,
"SearchThreshold": 10,
"AlwaysVisible": true,
"Values": [
{
"Label": "The North Face",
"Value": "The North Face",
"Count": 45
},
{
"Label": "Columbia Sportswear",
"Value": "Columbia Sportswear",
"Count": 17
},
{
"Label": "White Sierra",
"Value": "White Sierra",
"Count": 3
},
{
"Label": "Spyder",
"Value": "Spyder",
"Count": 9
},
{
"Label": "Skhoop",
"Value": "Skhoop",
"Count": 1
},
{
"Label": "Sea To Summit",
"Value": "Sea To Summit",
"Count": 2
},
{
"Label": "Royal Robbins",
"Value": "Royal Robbins",
"Count": 1
},
{
"Label": "Prana",
"Value": "Prana",
"Count": 1
},
{
"Label": "Obermeyer",
"Value": "Obermeyer",
"Count": 1
},
{
"Label": "Mountain Hardwear",
"Value": "Mountain Hardwear",
"Count": 2
},
{
"Label": "Jupa",
"Value": "Jupa",
"Count": 4
},
{
"Label": "Craghoppers",
"Value": "Craghoppers",
"Count": 1
},
{
"Label": "Coghlans",
"Value": "Coghlans",
"Count": 1
},
{
"Label": "Big Agnes",
"Value": "Big Agnes",
"Count": 1
},
{
"Label": "Aventura",
"Value": "Aventura",
"Count": 1
}
],
"Tooltip": "Please select one or more brands.",
"IsCollapsible": true,
"IsCollapsedDefault": false,
"SortOrder": 2834,
"IsVisible": true,
"NofVisible": 15,
"Height": 250,
"FacetRangeDisplayType": 0,
"PreloadChildren": false,
"ShowSliderInputs": false
}
Example 18.2 Nested Checkbox List – Searchable, Collapsible, Truncated
{
"FacetId": 12114,
"Name": "Department",
"Field": "department_nest",
"FieldType": "string",
"FacetType": "nestedcheckbox",
"DisplayType": "truncating",
"MaxCount": 0,
"MinHitCount": 1,
"ParamName": "department_nest",
"SortBy": "ScoreAndAlphaAndAlpha",
"ExpandSelection": true,
"IsNumeric": false,
"IsCurrency": false,
"IsSearch": true,
"ScrollHeight": 0,
"ScrollThreshold": 0,
"TruncateThreshold": 5,
"SearchThreshold": 0,
"AlwaysVisible": true,
"Values": [
{
"Label": "Specials",
"Value": "Specials",
"Count": 90,
"Path": "Specials"
},
{
"Label": "Sat Dec 15th",
"Value": "Sat-Dec-15th",
"Count": 90,
"Path": "Specials/Sat Dec 15th"
},
{
"Label": "Kids",
"Value": "Kids",
"Count": 90,
"Path": "Specials/Sat Dec 15th/Kids"
},
{
"Label": "Men's",
"Value": "Men-s",
"Count": 12,
"Path": "Specials/Sat Dec 15th/Men's"
},
{
"Label": "Women's",
"Value": "Women-s",
"Count": 15,
"Path": "Specials/Sat Dec 15th/Women's"
},
{
"Label": "Sat Dec 8th",
"Value": "Sat-Dec-8th",
"Count": 53,
"Path": "Specials/Sat Dec 8th"
},
{
"Label": "Boy's",
"Value": "Boy-s",
"Count": 21,
"Path": "Specials/Sat Dec 8th/Boy's"
},
{
"Label": "Girl's",
"Value": "Girl-s",
"Count": 20,
"Path": "Specials/Sat Dec 8th/Girl's"
},
{
"Label": "Toddler's",
"Value": "Toddler-s",
"Count": 16,
"Path": "Specials/Sat Dec 8th/Toddler's"
},
{
"Label": "Sun Dec 23rd",
"Value": "Sun-Dec-23rd",
"Count": 40,
"Path": "Specials/Sun Dec 23rd"
},
{
"Label": "Boys 5-20",
"Value": "Boys-5-20_1",
"Count": 21,
"Path": "Specials/Sun Dec 23rd/Boys 5-20"
},
{
"Label": "Girls 5-20",
"Value": "Girls-5-20_1",
"Count": 20,
"Path": "Specials/Sun Dec 23rd/Girls 5-20"
},
{
"Label": "Fri Dec 21st",
"Value": "Fri-Dec-21st",
"Count": 8,
"Path": "Specials/Fri Dec 21st"
},
{
"Label": "Kid's",
"Value": "Kid-s",
"Count": 8,
"Path": "Specials/Fri Dec 21st/Kid's"
},
{
"Label": "Outerwear",
"Value": "Outerwear",
"Count": 4,
"Path": "Specials/Outerwear"
},
{
"Label": "Men",
"Value": "Men_2",
"Count": 1,
"Path": "Specials/Outerwear/Men"
},
{
"Label": "Women",
"Value": "Women_2",
"Count": 3,
"Path": "Specials/Outerwear/Women"
},
{
"Label": "Sportswear",
"Value": "Sportswear",
"Count": 1,
"Path": "Specials/Sportswear"
},
{
"Label": "Mens",
"Value": "Mens",
"Count": 1,
"Path": "Specials/Sportswear/Mens"
},
{
"Label": "Kids",
"Value": "Kids_1",
"Count": 58,
"Path": "Kids"
},
{
"Label": "Baby & Toddler 6M-4T",
"Value": "Baby--Toddler-6M-4T",
"Count": 17,
"Path": "Kids/Baby & Toddler 6M-4T"
},
{
"Label": "Fleece",
"Value": "Fleece_2",
"Count": 1,
"Path": "Kids/Baby & Toddler 6M-4T/Fleece"
},
Above is example JSON used for the facet pictured. Not all JSON is displayed here, to preserve space.
Example 18.3 Color Swatch
{
"FacetId": 73410,
"Name": "Color",
"Field": "color-property",
"FieldType": "string",
"FacetType": "swatch",
"DisplayType": "truncating",
"MaxCount": 10,
"MinHitCount": 1,
"SortBy": "Score",
"ExpandSelection": false,
"IsNumeric": false,
"IsCurrency": false,
"IsSearch": true,
"ScrollHeight": 150,
"ScrollThreshold": 10,
"TruncateThreshold": 5,
"SearchThreshold": 10,
"AlwaysVisible": true,
"IsCollapsible": false,
"IsCollapsedDefault": false,
"SortOrder": 5786,
"IsVisible": true,
"NofVisible": 10,
"Height": 150,
"SwatchData": "[{\"Value\":\"White\",\"AssetName\":\"white2.png\",\"AssetUrl\":\"\",\"IsDefault\":true,\"Color\":null},{\"Value\":\"empty\",\"AssetName\":\"emptySwatch.png\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"red\",\"AssetName\":\"reg.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"green\",\"AssetName\":\"green.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"brown\",\"AssetName\":\"brown.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"black\",\"AssetName\":\"black.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"Blue\",\"AssetName\":\"blue.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"Navy\",\"AssetName\":\"navy.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"Yellow\",\"AssetName\":\"yellow.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"Purple\",\"AssetName\":\"purple.png\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},{\"Value\":\"Grey\",\"AssetName\":\"grey.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null}]",
"FacetRangeDisplayType": 0,
"PreloadChildren": false,
"ShowSliderInputs": false,
"Ranges": [],
"Values": [
{
"Label": "Black",
"Value": "Black",
"Count": 41,
"Selected": false
},
{
"Label": "Blue",
"Value": "Blue",
"Count": 34,
"Selected": false
},
{
"Label": "Grey",
"Value": "Grey",
"Count": 24,
"Selected": false
},
{
"Label": "Pink",
"Value": "Pink",
"Count": 16,
"Selected": false
},
{
"Label": "Red",
"Value": "Red",
"Count": 21,
"Selected": false
},
{
"Label": "Purple",
"Value": "Purple",
"Count": 14,
"Selected": false
},
{
"Label": "White",
"Value": "White",
"Count": 14,
"Selected": false
},
{
"Label": "Green",
"Value": "Green",
"Count": 12,
"Selected": false
},
{
"Label": "Navy",
"Value": "Navy",
"Count": 8,
"Selected": false
},
{
"Label": "Orange",
"Value": "Orange",
"Count": 6,
"Selected": false
}
]
},
Example 18.4 Range Slider
{
"FacetId": 91942,
"Name": "Price slider",
"Field": "Price",
"FieldType": "range",
"FacetType": "slider",
"DisplayType": "default",
"MaxCount": 0,
"MinHitCount": 0,
"ParamName": "priceslider",
"SortBy": "ScoreAndAlphaAndAlpha",
"ExpandSelection": false,
"IsNumeric": false,
"IsCurrency": false,
"CurrencySymbol": "$",
"IsSearch": false,
"ScrollHeight": 0,
"ScrollThreshold": 0,
"TruncateThreshold": 0,
"SearchThreshold": 0,
"AlwaysVisible": true,
"ShowItemsCount": false,
"Tooltip": "",
"IsCollapsible": false,
"IsCollapsedDefault": false,
"SortOrder": 8,
"IsVisible": true,
"NofVisible": 0,
"Height": 0,
"SwatchData": [],
"FacetRangeDisplayType": 1,
"PreloadChildren": false,
"ShowSliderInputs": true,
"Ranges": [],
"Values": [
{
"Count": 57,
"Selected": false,
"RangeStart": "230",
"RangeEnd": "899",
"RangeMin": "0"
"RangeMax": "1229"
}
],
"HiddenValues": [],
"ShowFacetCount": false
}
Example 18.5 Open Range
{
"FacetId": 150883,
"Name": "Create Date",
"Field": "createdate",
"FieldType": "range",
"FacetType": "openRange",
"DataType": "datetime",
"DisplayType": "default",
"MaxCount": 0,
"MinHitCount": 0,
"ParamName": "",
"SortBy": "Alpha",
"ExpandSelection": true,
"IsNumeric": false,
"IsCurrency": false,
"CurrencySymbol": "",
"IsSearch": false,
"ScrollHeight": 0,
"ScrollThreshold": 0,
"TruncateThreshold": 0,
"SearchThreshold": 0,
"AlwaysVisible": true,
"ShowItemsCount": false,
"Tooltip": "",
"IsCollapsible": false,
"IsCollapsedDefault": false,
"SortOrder": 18,
"IsVisible": true,
"NofVisible": 0,
"Height": 0,
"SwatchData": [],
"FacetRangeDisplayType": 1,
"PreloadChildren": false,
"ShowSliderInputs": false,
"Ranges": [],
"Values": [
{
"Count": 53,
"Selected": false,
"RangeStart": "2020-10-27T22:13:20Z",
"RangeEnd": "2021-09-03T23:32:12Z",
"RangeMin": "2020-10-27T22:13:20Z",
"RangeMax": "2021-09-03T23:32:12Z"
}
],
"HiddenValues": [],
"ShowFacetCount": false
}
Redirect Object
This object may be contained in the response from the Search method.
| Name | Data Type | Description |
|---|---|---|
| Location | String | When this object is populated, the string will hold a URL that should be used to redirect the user. The URL may be relative or absolute. Redirect Rules are configured in Workbench > Merchandising > Redirects |
| Target | String | If this string holds the value, "_blank", the URL in the Location object should open in a new window/tab. This is configured in the Target field in the Redirects section of the Workbench. |
Examples
Example 19.1
"Redirect": {
"Location": "/careers",
"Target": "_blank"
}
Compare Results Object
The Results Object is returned in the Search method and the Autocomplete method.
| Name | Data Type | Required | Description |
|---|---|---|---|
| Results | Array of objects | Yes | An entry in the array for each item returned in compare results. |
| DocId | String | Value of the unique key | |
| Score | Number | The relevancy score that has been calculated by the Hawksearch engine. | |
| Document | Contains properties | Contains the fields assigned to each item. This is driven by the fields defined in Hawksearch Workbench. Each field is an object with 2 properties: 1. value - may differ depend on field type 2. compare - boolean flag, set to true if field is meant to be used for comparison |
Examples
Example 20.1 - The values in the Document object will vary. This is dependent on the fields that are configured in your Hawksearch engine workbench, and the fields that are flagged to be included in the 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
}
}
}
PageContent Object
This may be contained in the response from the Search method. This is returned as part of Content Landing Pages. Landing pages are configured in Workbench > Merchandising > Landing Pages.
| Name | Data Type | Description |
|---|---|---|
| ZoneName | String | The name of the zone in which the content should be placed. The zone names are configured in the Hawksearch Workbench > Merchandising > Landing Pages > Layouts. Within Layouts, zone and their names are configured. Unlike Merchandising Object, the PageContent Object can contain multiple pieces of content to be placed in a single zone. |
| Items | Array of objects | |
| > Title | String | If ContentType=featured, this i the title to display with the featured items. |
| > Name | String | Name of content item. Not intended to display to the user. |
| > Content Type | String | Value can be “image,” “custom,” "featured," or “widget.” (Further custom programming required to use the “widget” type.) |
| > ImageUrl | String | If ContentType=image, this holds the url where the image is located. |
| > AltTag | String | If ContentType=image, this may be included with the value to be used as the Alt Tag value. |
| > ForwardUrl | String | If ContentType=image, this may be included. If present, the image should be linkable to the URL provided in the ForwardUrl object. |
| > Output | String | If ContentType=custom, this may be included. If present, it will contain HTML that should be used for display. |
| > WidgetArgs | String | Reserved for the ContentType=widget. (Further custom programming required to use the “widget” type.) |
| > IsMobile | String | Indicates of this content piece was flagged for mobile in the Workbench > Merchandising > Content Items |
| > IsTrackingEnabled | String | Indicates of this content piece was flagged to have tracking enabled in the Workbench > Merchandising > Content Items |
| > FeaturedItems | Array of objects | See FeaturedItems Object section. |
Examples
"PageContent": [
{
"ZoneName": "Sub Content 1",
"Items": [
{
"Name": "persona",
"ContentType": "image",
"ImageUrl": "//local.hawksearch.com/assets/1168/2banner_persona3.png",
"AltTag": "persona",
"ForwardUrl": "",
"Output": "",
"WidgetArgs": "",
"IsMobile": false,
"IsTrackingEnabled": false,
"MobileWidth": 0,
"MobileHeight": 0,
"BannerId": 0,
"CampaignId": 0
}
]
},
{
"ZoneName": "Sub Content 2",
"Items": [
{
"Name": "persona",
"ContentType": "image",
"ImageUrl": "//local.hawksearch.com/assets/1168/jackets_persona4.png",
"AltTag": "persona",
"ForwardUrl": "",
"Output": "",
"WidgetArgs": "",
"IsMobile": false,
"IsTrackingEnabled": false,
"MobileWidth": 0,
"MobileHeight": 0,
"BannerId": 0,
"CampaignId": 0
}
]
}
]
VisitorTargets Object
This object may be contained in the response from the Search method.
| Name | Data Type | Description |
|---|---|---|
| Id | String | When this object is populated, the string will hold the unique identifier for the Visitor Target. This is generated by Hawksearch when a Visitor Target is created. |
| Name | String | This holds the name of the Visitor Target. This can be configured in the Visitor Targets section of the Workbench. |
Examples
"VisitorTargets": [
{
"Id": 9346,
"Name": "Illinois"
}
]
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.
What's the difference between Query Parameter and Queryable Field flag?
Queryable field (Query-this-field flag)
If a field needs to be searched upon for all keyword search requests, turn on the "Query this Field?" flag in the field settings
If the field should not be searched against for all requests, instead only for selected requests, use the query parameter as per below example. For details, see Field-specific Search <Link to MISSING Field-Specific Search page>
curl --location '<https://searchapi-dev.hawksearch.net/api/v2/search'>
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data '{
"keyword": "ABC123", //this will search for "ABC123" against all fields marked as Queryable
"ClientGuid": "YOUR_CLIENT_GUID",
"ClientData": {
"VisitorId": "e8056d14-5f85-4935-8f6b-cc2e0ef0b135",
"VisitId": "69729384-3818-4ec2-b91b-350dbdcb5312",
"UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36 Edg/115.0.1901.203"
},
"Query": "(somefield.keyword: \"value\" OR anotherfield.text: \"foo bar\")"
}'
curl --location '<https://searchapi-dev.hawksearch.net/api/v2/search'>
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data '{
"query": "myfield.keyword:ABC123",
"ClientGuid": "YOUR_CLIENT_GUID",
"ClientData": {
"VisitorId": "e8056d14-5f85-4935-8f6b-cc2e0ef0b135",
"VisitId": "69729384-3818-4ec2-b91b-350dbdcb5312",
"UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36 Edg/115.0.1901.203"
}
}'
Updated about 1 month ago