Hierarchy API Examples

Use this API to create and maintain Hierarchical facets on search and landing pages.

Following operations are provided by Hawksearch hierarchy API:

Upsert to add new or update existing hierarchies

RebuildMapping to initiate hierarchy mapping

DeleteHierarchyItems to remove a specific list of hierarchies

DeleteAllHierarchyItems to remove all hierarchies

General Notes:

Ensure that the header contains the Hawksearch Key for all the operations:
Request headers must contain the Hawksearch API Key as follows:
Format: X-HawkSearch-ApiKey : <your engine API key>
Example: X-HawkSearch-ApiKey : 12345678-9ABC-DEF0-1234-56789ABCDEF0
Hierarchy addition is a 3-step process with hierarchy upsert, hierarchy rebuild and index items operations.

A. Following steps are required to successfully add hierarchies to the engine

Some highly important notes to know before you add the hierarchies

If you intend to perform a full hierarchy update, please delete the existing hierarchies as mentioned in the section C below before inserting new hierarchies.
The name of the topmost hierarchy must be lower case and have no spaces or special symbols except for underscores. All other Hierarchy names under this do not have any naming restrictions. Usually, the topmost hierarchy name (without spaces) is category. The field name in the below example is category so there needs to be a field created by this name in the dashboard, other hierarchies do not need fields.
The difference in naming is that the names of other hierarchies are common names example Outdoor Kitchens or As Seen On TV, but the name of the topmost hierarchy must be the fieldname example products, category, department_name etc - please see Field Configuration: Naming Convention
The parent hierarchy id for the topmost hierarchy must be 0
The field created for category must be marked as hierarchical on the dashboard:
A facet must be created for this field which is either a nested checkbox or nested list:

Step 1: Upsert the hierarchies in a POST request

POST /api/hierarchy/upsert
{
    "IndexName": "demo.20200101.123456",
    "Hierarchies": [
        {
            "HierarchyId": "1234",
            "Name": "category",
            "ParentHierarchyId": "0",
            "IsActive": true,
            "SortOrder": 0,
            "Custom": ""
        },
        {
            "HierarchyId": "1111",
            "Name": "Clothing",
            "ParentHierarchyId": "1234",
            "IsActive": true,
            "SortOrder": 0,
            "Custom": ""
        },
        {
            "HierarchyId": "2222",
            "Name": "Accessories",
            "ParentHierarchyId": "1234",
            "IsActive": true,
            "SortOrder": 1,
            "Custom": ""
        },
        {
            "HierarchyId": "3333",
            "Name": "Footwear",
            "ParentHierarchyId": "1234",
            "IsActive": true,
            "SortOrder": 1,
            "Custom": ""
        },
        {
            "HierarchyId": "1212",
            "Name": "Jackets",
            "ParentHierarchyId": "1111",
            "IsActive": true,
            "SortOrder": 1,
            "Custom": ""
        },
        {
            "HierarchyId": "3434",
            "Name": "Shirts",
            "ParentHierarchyId": "1111",
            "IsActive": true,
            "SortOrder": 1,
            "Custom": ""
        }
    ]
}

Step 2: Map and configure the hierarchies added in step1

POST /api/hierarchy/rebuild
{
	"IndexName": "demo.20200101.123456"
}

B. Below API request lists the hierarchies

POST /api/hierarchy/
{
	"IndexName": "demo.20200101.123456"
}

C. Following are the options to remove hierarchies from the engine:

(Please rebuild hierarchy before and after deleting hierarchies)

Option 1: Delete certain hierarchies

Note that deleting a parent hierarchy will delete all other hierarchies under it

Option 2: Delete all hierarchies

D. Associate Items with one or more hierarchies

Since the hierarchies and the actual data items are indexed separately, we need to associate the items with the hierarchies. This can be established through normal indexing API.

Important notes before indexing items:

The index-items request must contain the hierarchy ids as the value of the topmost category and must not be the name.
The hierarchies need to be split into multiple requests if they exceed the limit of 125 hierarchies in a request, splitting will not be necessary for hierarchies within this limit.
Please upsert the hierarchies, rebuild the hierarchies and then index all the items to ensure a seamless indexing activity.

For details on the indexing API visit - Hawksearch - v4.0 - Indexing API