📘

API Docs

Detailed technical documentation is available here - Indexing API Documentation

🚧

Important

Depending on the version of HawkSearch used, method of integration, and the presence of data feed files for indexing, you may need to perform indexing as per this article or Using Dashboard API to Rebuild Indexes. Please contact HawkSearch for any clarifications.

Process Overview

(click to enlarge image)

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.index-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.index-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.index-na.hawksearch.com

Configurations for an engine in this location are maintained in the Hawksearch Workbench at dashboard-na.hawksearch.com.

Indexing API Methods

Create

This method creates a new index in Hawksearch. The new index will be empty. Other methods must be used to populate the index. The methods, IndexItems and DeleteIndexItems are used to add, update and delete items in an index. The index will not be set to be active until the Set-Current method is called, passing the name of the index. Each client engine can have multiple indexes, but only 1 current index at a time.

Request

Parameters

Examples

Create index with a suffix

{
    "Suffix": "test-addingcolorfamily"
}

Response

Examples

With a suffix

{
    "IndexName": "myengine.20200123.153931.test-addingcolorfamily"
}

Without a suffix

{
    "IndexName": "myengine.20200123.153932"
}

Delete Index Item

This method delete the single item from existing index in Hawksearch.

Request

Parameters

Examples

Delete single item from index

{
    "IndexName": "myengine.20200123.153931",

         "Id": "Item_DocId"
}

Response

Examples

{
    "Message": "Unable to retrieve item: 'Item_160373'."
}

Delete Index Items

This method deletes multiple items from existing index in Hawksearch.

Request

Parameters

Examples

Delete single item from index

{
    "IndexName": "myengine.20200123.153931",

         "Ids": ["Item_DocId", "Item_Doc2Id"]
}

Response

None or Message with Error

Examples

{
    "Message": "Unable to retrieve item: 'Item_160373'."

}

Delete Index

This method delete an existing index in Hawksearch.

Parameters

Examples

{
    "IndexName": "myengine.20200123.153931"

}

Response

None or Message with Error

Get All Indexes

This method will return all of the indexes that exist for the engine.

Parameters

None

Response

The response returns name of the current index. This Index Name can then be used as a parameter for other method calls.

Examples

{

    "IndexNames": [

        "myengine.20200123.081421",

        "myengine.20200123.074248",

        "myengine.20200123.145534",

        "myengine.20200123.114936",

        "myengine.20200123.114657",

        "myengine.20200123.114151"

    ]

}

Get Current Index Name

This method will return the name of the index that is currently being used for search. If there is no “current index,” an error will be returned.

Request

Parameters

None

Response

The response returns name of the current index. This Index Name can then be used as a parameter for other method calls.

Examples

{
    "IndexName": "myengine.20200123.153932"
}

Index Items

This method adds and updates items and their attributes to a specified index. Attributes must be defined in the Hawksearch Workbench Fields list in order for the attributes to be stored for an object. Once an item is indexed with this method, it will immediately be available in search results, if the modified index is queried.

If an item is sent with a key that matches an existing item, that item will be updated with the attributes being sent. If an item is sent with a new key, that item will be added to the index.

📘

NOTE

To index hierarchical data, please build the hierarchy using the Hierarchy API and then call the index-items API.

Request

Parameters

Examples:

{

       "IndexName": "demo.20200221.090452",

       "Items": [

       {

              "id": ["123"],

              "Sku": ["987654"],

              "title": ["Rain Jacket"],

              "price": ["39.99"],

              "saleprice": ["32.99"], "image":["https://www.mysite.com/images/Thumbnail/987654.jpg"],

              "url_detail":["https://www.mysite.com/jackets/mens/987654"],

              "brand" : ["Acme"],

              "color" : ["Orange"]

       },

       {

              "idx": ["987"],

              "Sku": ["123456"],

              "title": ["Down Jacket"],

              "price": ["89.99"],

              "saleprice": ["74.99"], "image":["https://www.mysite.com/images/Thumbnail/123456.jpg"],

              "url_detail":["https://www.mysite.com/jackets/mens/123456"],

              "brand" : ["Acme"],

              "color" : ["Black"]

       }]

}

Response

Update Items

This method updates items and their attributes to a specified index. Attributes must be defined in the Hawksearch Workbench Fields list in order for the attributes to be stored for an object. Once an item is updated with this method, it will immediately be available in search results, if the modified index is queried.

If an item is sent with a key that matches an existing item, that item will be updated with the attributes being sent. If an item is sent with a new key, that item will be added to the index. The item will be updated with the attributes being sent. Note that in this method, you can send only those attributes in the request which are required to be updated along with the Primary key and skip the ones which do not require any changes.

Request

Parameters

Examples

{

       "IndexName": "demo.20200221.090452",

       "Items": [

       {

              "id": ["123"],

              "brand" : ["Acme"],

              "color" : ["Orange"]

       },

       {

              "idx": ["987"],

              "saleprice": ["74.99"], "image":["https://www.mysite.com/images/Thumbnail/123456.jpg"]

       }]

}

Response

Set Current Index

Sets a specified index as the current index. This will be the index that will be used when calling Hawksearch search methods (documented in a separate document).

Request

Parameters

Examples

{
    "IndexName": "myengine.20200123.091609"
}

Response

None

Rebuild All

Rebuilds autocomplete, percolator, learning search and related searches.

📘

NOTE

Please note that rebuild-all API does not rebuild the complete index. This is not to be mistaken with full index rebuild process.

Rebuild All only rebuilds the four secondary indices but not the primary index which has the items data. Hence, please follow the steps under FAQ section down below to perform a full index rebuild.

Request

Parameters

Examples

{
    "IndexName": "myengine.20200123.090452"
}

Response

None

Rebuild Autocomplete

Rebuilds Autocomplete Categories & Autocomplete Popular Items. This method is called as part of Rebuild-All. It is not required that this method be called separately.

Request

Parameters

Response

None

Rebuild Percolator

Rebuilds Percolator (boost rules & visitor target rules) for Hawksearch. This method is called as part of Rebuild-All. It is not required that this method be called separately.

Request

Parameters

Response

None

Rebuild Learning Search

Rebuilds Learning Search & Learning Search By Visitor. This method is called as part of Rebuild-All. It is not required that this method be called separately.

Request

Parameters

Response

None

Rebuild Related

Rebuilds Related Searches. This method is called as part of Rebuild-All. It is not required that this method be called separately.

Request

Parameters

Response

None

FAQs

📘

Note

This is the full index rebuild process. Please refer to this article for the details Full v/s Partial Indexing

Create Fields

1. Establish what fields/attributes need to be in Hawksearch. Consider what needs to be searched, what needs to be displayed on the search results page and what might be needed to use for merchandising. Some examples of fields that could be needed for merchandising: a rating field to sort by top rated; a sales margin to use for featured products.
2. Create fields in Hawksearch workbench for each field/attribute that will be sent to Hawksearch. Alternatively, these fields can be created using the REST API.

(Optional) Create Facets

1. Once the fields are created in Hawksearch, Facets can then be created. This step is optional in the sense that it is not required to be done at this time, and can be completed after the data has been initially indexed, but Facets should be created at some point to make for a richer search results page, that is also easier to navigate.
2. Consider the expectations of your users and what navigation choices they would expect to have available, and consider what fields of data are available for facet use.
3. Facets can be created from the Hawksearch workbench, or through the REST API.

(Optional) Remove old index

1. If applicable, delete inactive index using the delete API call

Create Index

1. Use the 'Create' call documented above to create the empty index.
2. NOTE: You are limited to a total of two indexes. If you already have two indexes created, you will need to first delete one before you can create a new index. Please see the 'Delete' call documented above for instructions on how to perform this action.

(Optional) Build Hierarchy

1. Use the upsert call to add/update new hierarchies (ref Hierarchy API) to add your hierarchical data for nested facets.
2. Build the hierarchical data model using the build call.

Index Items

1. Use the Index-Items call to import data into the Index.

(Optional) Set Current Index

1. You can choose to set the current index using the relevant call, but it is not required. You can submit the index you would like to search against as part of the search call. However, if you do set the current index - that information does not need to be included in the search call.

Rebuild All

1. This final step rebuilds several Hawksearch functions - the autocomplete, percolator, learning search and related searches.

Method Calls Overview

1. Delete (for older index)
2. Create (the new index)
3. Upsert and Rebuild (the hierarchy)
4. Index-Items (your products)
5. Set-Current (the latest index)
6. Rebuild-All (on the latest index)

Why do I have to send the index name in every request if I am sending the key?

You will have the flexibility to have multiple indexes stored in Hawksearch. The index name is required to indicate on which index the action should be taken.