Finding Relevant Category

The SearchItems operations returns most relevant results for a search request that are targeted inside a category/sub-category. Amazon uses a hierarchy of nodes to organize its items for sale. Each node represents a collection of items for sale. Product Advertising API calls the nodes, browse nodes, because customers can browse through the nodes to find the collection of items that interests them. These browse nodes are sub-categories inside a root category (also called SearchIndex). For example, customers might be interested in the browse nodes inside Books category like Literature or Fiction, Medicine, Mystery or Thrillers, Non Fiction or Outdoors or Nature.

Though you can find most of the products you're searching for within the "All" category, however, search results are faster and more relevant when targeted inside a category. The SearchRefinements resource helps you find the most relevant category and sub-category for your search request. This tutorial is about how you can find the relevant category for your search request using SearchRefinements resource in your SearchItems request.

For the tutorial, let's assume we're searching for action video games for Sony PSP platform.

Step 1: Initial Search Request

• Let's start our search for "action games" without any SearchIndex using the following payload. Note that we've requested the SearchRefinement resource here.

{
 "Keywords": "action games",
 "Resources": ["SearchRefinements"],
 "PartnerTag": "xyz-20",
 "PartnerType": "Associates",
 "Marketplace": "www.amazon.com",
 "Operation": "SearchItems"
}

• The search result returns contains combination of App Games as well as Video Games. Lookout for the SearchRefinements response in the API output. It contains relevant SearchIndex for the search request which looks like this:

"SearchRefinements": {
   "SearchIndex": {
    "DisplayName": "Department",
    "Id": "SearchIndex",
    "Bins": [
     {
      "DisplayName": "Apps & Games",
      "Id": "MobileApps"
     },
     {
      "DisplayName": "Video Games",
      "Id": "VideoGames"
     },
     {
      "DisplayName": "Toys & Games",
      "Id": "ToysAndGames"
     }
     /* More relevant SearchIndexes */
    ]
   }
  }

• From the response, we see that and VideoGames SearchIndex is one of the most relevant department for the search request. Let's use this to fire a subsequent request as we are looking for video games.

Step 2: Search Inside a Root Category (SearchIndex)

• The subsequent search request now targets the VideoGames SearchIndex.

{
 "Keywords": "action games",
 "Resources": ["SearchRefinements"],
 "SearchIndex": "VideoGames",
 "PartnerTag": "xyz-20",
 "PartnerType": "Associates",
 "Marketplace": "www.amazon.com",
 "Operation": "SearchItems"
}

• We see that the search results have now improved as they are now returning action video games. However, the results are from various platforms like PS3, XBox, etc. Lookout for SearchRefinements resource response again as they now contain relevant browse nodes for the search request:

"SearchRefinements": {
   "BrowseNode": {
    "Id": "BrowseNodeId",
    "DisplayName": "Department",
    "Bins": [
     {
      "DisplayName": "Nintendo 3DS",
      "Id": "2622269011"
     },
     {
      "DisplayName": "PlayStation 3",
      "Id": "14210751"
     },
     {
      "DisplayName": "Xbox One",
      "Id": "6469269011"
     },
     {
      "DisplayName": "PC",
      "Id": "229575"
     },
     {
      "DisplayName": "Xbox 360",
      "Id": "14220161"
     },
     {
      "DisplayName": "Wii",
      "Id": "14218901"
     },
     {
      "DisplayName": "PlayStation 4",
      "Id": "6427814011"
     },
     {
      "DisplayName": "Sony PSP",
      "Id": "11075221"
     }
     /* More relevant Browse Nodes */
    ]
   }
 }

• From the relevant browse nodes list returned under SearchRefinements, we see that the BrowseNodeId for Sony PSP is 11075221. Let's use this in subsequent request to target our search request inside the Sony PSP sub-category.

Step 3: Search Inside a Sub-Category

• The subsequent search request now targets Sony PSP sub-category

{
 "Keywords": "action games",
 "Resources": ["SearchRefinements"],
 "SearchIndex": "VideoGames",
 "BrowseNodeId": "11075221",
 "PartnerTag": "xyz-20",
 "PartnerType": "Associates",
 "Marketplace": "www.amazon.com",
 "Operation": "SearchItems"
}

• We see that all the search results are now Sony PSP action games.