Using API to Create Facets

This API allows you to create a facet in Hawksearch dashboard and manage the facet configurations.

Example use case: Create a Brand facet that can be used as a facet filter.

Request: POST request to the API below:

POST /api/v9/facet HTTP/1.1
Host: dashboard-na.hawksearch.com
X-HawkSearch-ApiKey: USE_YOUR_API_KEY
Cache-Control: no-cache
Postman-Token: cd457184-4c00-a650-62f2-530f22a9a384
    
    {
        "SyncGuid": "00000000-0000-0000-0000-000000000000",
        "FacetId": 0,
        "Name": "Brand",
        "FacetType": "checkbox",
        "FieldType": "string",
        "MaxCount": 0,
        "MinHitCount": 0,
        "Field": "brand",
        "Param": null,
        "DisplayType": "default",
        "ScrollHeight": 0,
        "ScrollThreshold": 0,
        "TruncateThreshold": 0,
        "SearchThreshold": 0,
        "SortOrder": 0,
        "ExpandSelection": false,
        "IsCurrency": false,
        "IsNumeric": false,
        "IsSearch": false,
        "IsVisible": true,
        "UBound": null,
        "LBound": null,
        "Increment": "0",
        "NofVisible": 0,
        "Height": 0,
        "DisplayRuleXML": null,
        "SortBy": "ScoreAndAlphaAndAlpha",
        "ParentId": 0,
        "IsCollapsible": true,
        "IsCollapsedDefault": false,
        "SwatchData": null,
        "FacetRangeDisplayType": 0,
        "PreloadChildren": false,
        "Tooltip": null,
        "ShowSliderInputs": false,
        "ShowFacetImageCount": false,
        "FacetRanges": [],
        "Tags": null,
        "CreateDate": "02-04-2020",
        "ModifyDate": "02-04-2020",
        "BoostBury": {
            "BoostValues": [],
            "BuryValues": []
        },
        "ListName": "Brand Facet",
        "NumericPrecision": 0,
        "CurrencySymbol": null
    }

Response: The response is an array of facet objects, every facet object being a series of key-value pairs. Description of the data is as follows:

No	Key	Description	Value Type

No	Key	Description	Value Type
1	FacetId	The unique identifier of the facet (unique across the whole system)	Number
2	SyncGuid	Internal field	GUID
3	Name	This is the name of the facet displayed to the user on the search results page. This property corresponds to the display name of the facet in the workbench.	Alphanumeric string
4	FacetType	Indicates the mode in which the facet is displayed and configurable from the workbench. Possible values for this are: checkbox (Checkbox List) link (Link List) nestedcheckbox (Nested Checkbox) nestedlinklist (Nested Link List) size (Size) swatch (Swatch) rating (Rating) slider (Slider) related (Related Searches) recentsearches (Recent Searches) search (Search Within)	One of the possible values - checkbox (String, Numeric, Range, Tabs) link (String, Numeric, Range, Tabs) nestedcheckbox (String, Numeric, Tabs) nestedlinklist (String, Numeric, Tabs) size (String, Numeric, Tabs) swatch (String, Numeric, Tabs) rating (String, Numeric, Tabs) slider (Numeric, Range) related (Search) recentsearches (Search) search (Search)
5	FieldType	Datatype of the field	One of the 3 possible values - Single Numeric String Search
6	MaxCount	The integer value which indicates the maximum number of facet values which can be displayed inside the facet.	Numeric
7	MinHitCount	The integer value which indicates the minimum number of facet values the minimum count of filters the facet must possess in order to be displayed as an option.	Numeric
8	Field	The name of the field for the facet.	lowercase alphanumeric string with underscores allowed
9	Param	This is the parameter to be used if you need to apply filter using this facet. Example, if you need to filter by the brand "The North Face" then in send the parameter "brand=The North Face" in addition to the other filters.	Alphanumeric
10	DisplayType	This is the property which provides options to fine-tune the way the list of facet values will be displayed. In the JSON output, the three different choices that will determine what fields will need to be defined in lowercase: scrolling default truncating	String
11	ScrollHeight	This is used when the facet's DisplayType is set to scroll. It sets the height of the facet in pixels.	Numeric
12	ScrollThreshold	This is used when the facet's DisplayType is set to scroll. It sets the minimum limit for the number of filters to be present in the facet for it to be displayed in a scrolling manner.	Numeric
13	TruncateThreshold	This is used when the facet's DisplayType is set to Truncating.The truncated facet shows only the first N values where N is the number set in the workbench, to load more values, user needs to click the "show more" link.	Numeric
14	SearchThreshold	It specifies the minimum number of filters to be present in the facet to make it search-able. The facet needs to have "Is Search Enabled?" set to on, in other words IsSearch property needs to be true.	Numeric
15	IsCurrency	Indicates if the facet needs to display the currency symbol. If the facet's FieldType is set as either numeric or range, and the display type is slider, then this option is displayed.	Boolean
16	IsNumeric	Indicator for range type of facets to show the slider. This property is hidden for all other facet types.	Boolean
17	IsSearch	This makes the facet searchable for its filters. This is useful for facets containing more than 15 values in general.	Boolean
18	IsVisible	Boolean switch to toggle the visibility of the facet	Boolean
19	UBound	Indicates the upper bound of the range facet.	Numeric
20	LBound	Indicates the lower bound of the range facet.	Numeric
21	Increment	Setting up the range facet slider value	Numeric
22	NofVisible	Number of Visible Facet values	Numeric
23	Height	Height of the scrollable facet values	Numeric
24	DisplayRuleXML	Display rule details of the facet in XML format	XML
25	SortBy	Indicates the default sort order of the facet.	Numeric
26	ParentId	ParentId of the facet for Hierarchial facets.	Numeric
27	IsCollapsible	Boolean value indicating whether the facet can be completely collapsed into a header	Boolean
28	IsCollapsedDefault	Boolean value indicating collapsible display	Boolean
29	SwatchData	A special type of facet is a swatch which displays images instead of the facet filters. The JSON output consists of the list of images. This is most useful for colors.	Alphanumeric
30	FacetRangeDisplayType	Numeric value to indicate the sub type of the facet when it is a range.	Numeric
31	PreloadChildren	Nested facets can load children filters either upon click event of the parent filter or automatically. This choice can be opted based on the value of this property.	Boolean
32	Tooltip	Quick help for the user available when hovered over the question mark next to the facet name	Alphanumeric
33	ShowSliderInputs	For slider facet, the user-entered inputs can be made visible using this property.	Boolean
34	ShowFacetImageCount	Boolean value to show or hide facet image count	Boolean
35	FacetRanges	It consistes of FacetRangeModel object.	FacetRangeModel Object
36	Tags	Tags assocaited with a facet	Alphanumeric
37	CreateDate	Facet Creation Date	Date string in MM-DD-YYYY format
38	ModifyDate	Facet Modification Date	Date string in MM-DD-YYYY format
39	BoostValues	Boost value of a facet	Numeric
40	BuryValues	Bury value of a facet	Numeric
41	ListName	Name of the facet which is not displayed to front end users.	Alphanumeric
42	NumericPrecision	Numeric	Numeric
43	CurrencySymbol	If facet type uses Currency	Alphanumeric
44	ExpandSelection	This field controls whether or not you will allow your customer to see additional filters after making their initial selection. All relevant sub departments will still be returned, but other filters not related to the initial selection will be hidden if this option is set to NO. If the option is set to YES, then the top level filters, and each layer of additional sub-departments, will be displayed. This is helpful if you have a department that has hundreds of sub-departments, for example. You can limit the number of filters that your customers can view so as not to overwhelm them.	Boolean

{
    "SyncGuid": "c050f99e-5cfd-433e-9bee-219a3d437061",
    "FacetId": 171214,
    "Name": "Brand",
    "FacetType": "checkbox",
    "FieldType": "string",
    "MaxCount": 0,
    "MinHitCount": 0,
    "Field": "brand",
    "Param": null,
    "DisplayType": "default",
    "ScrollHeight": 0,
    "ScrollThreshold": 0,
    "TruncateThreshold": 0,
    "SearchThreshold": 0,
    "SortOrder": 0,
    "ExpandSelection": false,
    "IsCurrency": false,
    "IsNumeric": false,
    "IsSearch": false,
    "IsVisible": true,
    "UBound": null,
    "LBound": null,
    "Increment": "0",
    "NofVisible": 0,
    "Height": 0,
    "DisplayRuleXML": null,
    "SortBy": "ScoreAndAlphaAndAlpha",
    "ParentId": 0,
    "IsCollapsible": true,
    "IsCollapsedDefault": false,
    "SwatchData": null,
    "FacetRangeDisplayType": 0,
    "PreloadChildren": false,
    "Tooltip": null,
    "ShowSliderInputs": false,
    "ShowFacetImageCount": false,
    "FacetRanges": [],
    "Tags": null,
    "CreateDate": "02-04-2020",
    "ModifyDate": "02-04-2020",
    "BoostBury": {
        "BoostValues": [],
        "BuryValues": []
    },
    "ListName": "Brand Facet",
    "NumericPrecision": 0,
    "CurrencySymbol": null
}

Special facets considerations:

Swatch facets : facets defined as swatch need to have their swatches defined in the below json format:

"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}]"

Display Rule: this is defined by XML as below, it is advised to create a facet with a display rule on the dashboard to better understand the format:

Boost and Bury: these are defined as arrays of objects with these properties

Facet Ranges: Facets defined as ranges can have minimum and maximum values defined by the LBound and UBound attributes under FacetRanges object