Indexing API
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.
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/create | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
Suffix | String | No | Optional suffix that will be applied to the name of the index to be created. This may be useful to track the purpose of creating this specific index (i.e. testing a new field). The string should have no spaces in it. |
Examples
Create index with a suffix
{
"Suffix": "test-addingcolorfamily"
}
Response
Object | Data Type | Always | Description |
---|---|---|---|
IndexName | String | Yes | Contains the name of the newly created index. If the Suffix parameter was populated in the request, it will be the value after the last period. |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/delete | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes | The name of the index from which item should be deleted | |
Id | String | Yes | The document id of corresponding item that suppose to be delete |
Examples
Delete single item from index
{
"IndexName": "myengine.20200123.153931",
"Id": "Item_DocId"
}
Response
Object | Data Type | Description |
---|---|---|
IndexNames | Array of strings | Each string contains the names of the indexes that exist in the engine. The most recently created will be listed first. |
IndexName | String | Contains the name of the index that is currently active. |
Message | String | Will return error message in case if occurs |
Examples
{
"Message": "Unable to retrieve item: 'Item_160373'."
}
Delete Index Items
This method deletes multiple items from existing index in Hawksearch.
Request
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/delete-items | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes | The name of the index from which item should be deleted | |
Ids | Array of Strings | Yes | Each string contains the document id of an item that suppose to be delete |
Examples
Delete single item from index
{
"IndexName": "myengine.20200123.153931",
"Ids": ["Item_DocId", "Item_Doc2Id"]
}
Response
None or Message with Error
Object | Data Type | Description |
---|---|---|
None or Message with Error |
Examples
{
"Message": "Unable to retrieve item: 'Item_160373'."
}
Delete Index
This method delete an existing index in Hawksearch.
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/delete-index | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes | The name of the index that should be deleted |
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.
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/ | GET | X-HawkSearch-ApiKey |
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.
Object | Data Type | Description |
---|---|---|
IndexNames | Array of strings | Each string contains the names of the indexes that exist in the engine. The most recently created will be listed first. |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/current | GET | X-HawkSearch-ApiKey |
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.
Object | Data Type | Required | Description |
---|---|---|---|
IndexName | String | Yes | Contains the name of the index that is currently active. |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/index-items | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
Index name | String | Yes | The name of the index to which the item(s) should be added. | When the index was created, the IndexName was returned in the response from the Create method or the GetCurrentIndex method. |
Items | Array of Objects | Yes | The Items object will contain all of the attributes that are to be stored for each object. For any object that will be used to supply a facet, the values provided will be the values displayed in the facet on the front-end. Each item must contain a primary key that matches the primary key defined in the Hawksearch Workbench. Missing primary key property or passing value that doesn't match the Hawksearch Workbench settings will cause returning error for Item in a Response. The response will return the item in with Status: "Failed" and following error message: "'Primary Key' doesn't exist in the field definition." Missing correct fields configuration in the Hawksearch Workbench will also cause returning an error for an Item. The response will return the item in with Status: "Failed" and following error message: "There is no fields definition. After adding fields configuration" |
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
Object | Data Type | Required | Description |
---|---|---|---|
Status | String | Yes | |
Summary | Array of Objects | Yes | |
> Total | Numeric | Yes | |
> Succeeded | Numeric | Yes | |
> Failed | Numeric | Yes | |
> Warnings | Numeric | Yes | |
Items | Array of Objects | No | |
> Item | |||
> Status | String | ||
> IgnoredFields | Array | List of fields that were ignored during indexing due to incompatibility with fields configuration |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/update-items | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes | The name of the index to which the item(s) should be added. | When the index was created, the IndexName was returned in the response from the Create method or the GetCurrentIndex method. |
Items | Array of Objects | Yes | The Items object will contain all of the attributes that you need to update for the existing item. For any object that will be used to supply a facet, the values provided will be the values displayed in the facet on the front-end. Each item must contain a primary key that matches the primary key defined in the Hawksearch Workbench. Missing primary key property or passing value that doesn't match the Hawksearch Workbench settings will cause returning error for Item in a Response. The response will return the item in with Status: "Failed" and following error message: "'Primary Key' doesn't exist in the field definition." Missing correct fields configuration in the Hawksearch Workbench will also cause returning an error for an Item. The response will return the item in with Status: "Failed" and following error message: "There is no fields definition. After adding fields configuration" |
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
Object | Data Type | Required | Description |
---|---|---|---|
Status | String | Yes | |
Summary | Array of Objects | Yes | |
> Total | Numeric | Yes | |
> Succeeded | Numeric | Yes | |
> Failed | Numeric | Yes | |
> Warnings | Numeric | Yes | |
Items | Array of Objects | No | |
> Item | |||
> Status | String | ||
> IgnoredFields | Array |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/set-current | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes | Name of an existing, populated index to be set to the current index. It will immediately be active in the engine for searching against. |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/rebuild-all | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/rebuild-autocomplete | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/rebuild-percolator | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/rebuild-learning | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes |
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
Endpoint | Method | Header Key |
---|---|---|
api/v2/indexing/rebuild-related | POST | X-HawkSearch-ApiKey |
Parameters
Name | Data Type | Required | Description | Source or Admin Section |
---|---|---|---|---|
IndexName | String | Yes |
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
- 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.
- 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
- 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.
- 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.
- Facets can be created from the Hawksearch workbench, or through the REST API.
(Optional) Remove old index
- If applicable, delete inactive index using the delete API call
Create Index
- Use the 'Create' call documented above to create the empty index.
- 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
- Use the upsert call to add/update new hierarchies (ref Hierarchy API) to add your hierarchical data for nested facets.
- Build the hierarchical data model using the build call.
Index Items
- Use the Index-Items call to import data into the Index.
(Optional) Set Current Index
- 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
- This final step rebuilds several Hawksearch functions - the autocomplete, percolator, learning search and related searches.
Method Calls Overview
- Delete (for older index)
- Create (the new index)
- Upsert and Rebuild (the hierarchy)
- Index-Items (your products)
- Set-Current (the latest index)
- 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.
Updated 5 months ago