SearchRefinements

The SearchRefinements resource can be requested to get dynamic SearchIndexes, BrowseNodes and Refinements for a search request. The resource is relevant for only SearchItems operation.

Availability

All locales. However, the various refinements returned differ by locale.

Features

The relevant search categories/sub-categories and dynamic refinements returned as part of SearchRefinements resource can be used to refine the search request. The SearchRefinements resource, if requested, returns:

• Relevant SearchIndices when the search request is inside "All" SearchIndex. Use the relevant SearchIndices returned to fire subsequent search request in a particular SearchIndex. Note that search requests under a targeted category (i.e. other than "All") returns more relevant products. The SearchRefinement resource helps you find the most relevant search index for your search request. For list of SearchIndices, refer Locale Reference.
• Relevant BrowseNodeIds when the search request is inside any category other than "All". Use the relevant BrowseNodeId to fire subsequent search request in a particular sub-category to further refine your search scope and get better results.
• Dynamic refinements (if applicable) are returned for each search request. For example, if the search request is in Books SearchIndex and the target Amazon marketplace supports Author refinements, you'll get relevant author names as dynamic refinements.

Response Elements

Each of the response element is encapsulated inside a Refinement container which contains details about the refinement ID, display name and the refinement value. For more information, refer Refinement Container.

Refinement Container

This is a generic container for all the types of refinements vended out by SearchRefinements Resource. A refinement container inside SearchRefinements resource looks like this:

{
  "SearchRefinements": {
    "RefinementType": {
      "Id": "SearchItems Parameter Name",
      "DisplayName": "Display Name of the Parameter",
      "Bins": [
         /* Refinement values for the RefinementType */
        {
           "Id": "The Actual Refinement Value",
           "DisplayName": "Display Name of the Refinement Value"
        }
      ]
    }
  }
}

The following table briefly describes various attributes inside the Refinement Container:

SearchIndexes Response Element

The structure of SearchIndexes element inside SearchRefinements resource looks like:

{
  "SearchRefinements": {
    "SearchIndex": {
      "Id": "SearchIndex",
      "DisplayName": "Department",
      "Bins": [
        {
          "Id": "AppsAndGames",
          "DisplayName": "Apps and Games"
        },
        {
          "Id": "DigitalMusic",
          "DisplayName": "Digital Music"
        }
        /* More relevant SearchIndexes */
      ]
    }
  }
}

The SearchIndexes are returned for every search request inside "All" SearchIndex. Use the relevant SearchIndex to narrow down the search request inside a particular category. From the example above, if Digital Music seems to be the relevant category for your search request, then fire a subsequent request with DigitalMusic as the SearchIndex.

BrowseNodes Response Element

The structure of BrowseNodes element inside SearchRefinements resource looks like:

{
  "SearchRefinements": {
    "BrowseNode": {
      "Id": "BrowseNodeId",
      "DisplayName": "Department",
      "Bins": [
        {
          "Id": "344520001",
          "DisplayName": "Women Clothing"
        },
        {
          "Id": "2233000134",
          "DisplayName": "Men Clothing"
        }
        /* More relevant BrowseNodeIds */
      ]
    }
  }
}

The BrowseNodes are returned for every search request which are in a specific search index i.e. any search index other than "All". Use the relevant BrowseNodeId to narrow down the search request inside a particular sub-category. From the example above, if Women Clothing seems to be the relevant sub-category for your search request, then fire a subsequent request with 344520001 as the BrowseNodeId.

OtherRefinements Response Element

The structure of OtherRefinements element inside SearchRefinements resource looks like:

{
 "SearchRefinements": {
  "OtherRefinements": [
    {
     "Id": "Brand",
     "DisplayName": "Brand",
     "Bins": [
        {
         "Id": "Sony",
         "DisplayName": "Sony"
        },
        {
         "Id": "Sony",
         "DisplayName": "Sony"
        }
      ]
    },
    {
      /* More Dynamic Refinements (if available) */
    }
  ]
 }
}

OtherRefinements are returned for every search request which are inside a particular search index and if the particular search index, marketplace combination supports a particular refinement. Use the Bin Id to fire subsequent request refining your search results. As of now, SearchRefinements resource returns dynamic values for following (if available in a particular SearchIndex and Marketplace):

• Actor
• Artist
• Author
• Brand

Example Requests and Responses

The following examples demonstrate the SearchRefinements use cases

Example 1

The example demonstrates the SearchRefinements resource behavior when a search request in US marketplace is inside "All" category.

Request:

{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "ItemCount": 1,
   "Keyword": "Harry Potter",
   "Resources" : [ "SearchRefinements" ]
}

Response:

{
  "SearchResult": {
    "Items": [
      {
        "ASIN": "0545162076",
        "DetailPageURL": "https://www.amazon.com/dp/0545162076?tag=dgfd&linkCode=osi&th=1&psc=1"
      }
    ],
    "SearchRefinements": {
      "SearchIndex": {
        "Id": "SearchIndex",
        "DisplayName": "Department",
        "Bins": [
          {
            "Id": "Books",
            "DisplayName": "Books"
          },
          {
            "Id": "MoviesAndTV",
            "DisplayName": "Movies & TV"
          },
          {
            "Id": "Fashion",
            "DisplayName": "Clothing, Shoes & Jewelry"
          },
          {
            "Id": "HomeAndKitchen",
            "DisplayName": "Home & Kitchen"
          },
          {
            "Id": "Beauty",
            "DisplayName": "Beauty & Personal Care"
          }
          / * More relevant Search Indexes */
        ]
      }
    },
    "SearchURL": "https://www.amazon.com/s/?field-keywords=Harry+Potter&search-alias=aps&tag=xyz-20&linkCode=osi",
    "TotalResultCount": 146
  }
}

Note that the most relevant search indexes are at top. That is, here, in this example, the Books search index is the most relevant one.

Example 2

The example demonstrates the SearchRefinements resource behavior when a search request for "Mystery Novels" keyword in US marketplace is inside "Books" category.

Request:

{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "ItemCount": 1,
   "Keyword": "Mystery Novels",
   "SearchIndex": "Books",
   "Resources" : [ "SearchRefinements" ]
}

Response:

{
  "SearchResult": {
    "Items": [
      {
        "ASIN": "1683993039",
        "DetailPageURL": "https://www.amazon.com/dp/1683993039?tag=dgfd&linkCode=osi&th=1&psc=1"
      }
    ],
    "SearchRefinements": {
      "BrowseNode": {
        "Id": "BrowseNodeId",
        "DisplayName": "Department",
        "Bins": [
          {
            "Id": "17",
            "DisplayName": "Literature & Fiction"
          },
          {
            "Id": "18",
            "DisplayName": "Mystery, Thriller & Suspense"
          },
          {
            "Id": "23",
            "DisplayName": "Romance"
          }
          /* More relevant BrowseNodes */
        ]
      },
      "OtherRefinements": [
        {
          "DisplayName": "Author",
          "Id": "Author",
          "Bins": [
            {
              "Id": "Agatha Christie",
              "DisplayName": "Agatha Christie"
            },
            {
              "Id": "Arthur Conan Doyle",
              "DisplayName": "Arthur Conan Doyle"
            },
            {
              "Id": "Wilkie Collins",
              "DisplayName": "Wilkie Collins"
            }
            /* More relevant Authors */
          ]
        }
      ]
    },
    "SearchURL": "https://www.amazon.com/s/?field-keywords=Mystery+Novels&search-alias=stripbooks&tag=xyz-20&linkCode=osi",
    "TotalResultCount": 1200
  }
}