SearchItems

Description

The SearchItems operation searches for items on Amazon based on a search query. The Amazon Creators API returns up to ten items per search request.

A SearchItems request requires a search category, which, if not specified, defaults to "All" and value for at least one of Keywords, Actor, Artist, Author, Brand or Title for searching items on Amazon.

SearchItems supports the following high-level resources:

• BrowseNodeInfo

• Images

• ItemInfo

• OffersV2

• searchRefinements

Availability

All locales, however, the parameter support varies by locale.

API Features and Best Practices

You can refine SearchItems request to return the results you want. Try different parameter combinations to customize search results. Moreover, the API helps you refine search requests by giving out dynamic search refinements for every search request you make. These dynamic refinements are available as part of searchRefinements resource.

• You can search by Keywords, Actor, Artist, Author, Brand or Title in any category. However, note that it is mandatory to provide at least one of the above mentioned parameters.

• SearchItems API supports many request parameters, most of them help in refining search results. For example, use Brand to refine your search results to return products for a specific brand or use MinPrice to return results having at least one offer price greater than the minimum price specified. However, not all parameters are relevant to all search indices. For example, if you specify the Actor, you would not use the Automotive search index.

• Use the SortBy parameter to return results in a specific order. For example Price:HighToLow sorts the result from most expensive to least expensive.

• By default, the API searches for products in "All" SearchIndex if not specified. However, use a specific SearchIndex or BrowseNodeId to limit search results by a category or BrowseNode. For a complete list of SearchIndices for a locale, refer Local Reference for Creators API.

Request Parameters {#ItemLookup-rp}

Check Common Request Headers and Parameters for more information on common input parameters. For detailed information on how to create and send a request, refer Using cURL. All SearchItems input parameters are listed below:

Availability Parameter

Condition Parameter

Note that, a search request with a particular Condition parameter may return 0 results if there are no offers with the specified condition in the search results.

DeliveryFlags Parameter

Note that a search request with a particular DeliveryFlag may result into 0 items if any of the specified Delivery Program is not supported in the target Amazon marketplace.

Resources Parameter

SortBy Parameter

Note that, if no SortBy parameter is provided in the search request, the results are sorted in default sort option for the Marketplace and SearchIndex combination. A particular SortBy parameter provided in the search request will fall back to the default sort option for the category if it is not supported in that category.

Response Elements

The following are common response elements returned:

Example Requests

• General keyword search request:

{
   "partnerTag": "xyz-20",
   "keywords": "harry potter"
}

• General keyword search using ItemCount and Resources parameter:

{
   "partnerTag": "xyz-20",
   "keywords": "harry potter",
   "itemCount": 1,
   "resources": ["images.primary.medium", "itemInfo.title", "offersV2.listings.price"]
}

• Search by Actor:

{
   "partnerTag": "xyz-20",
   "actor": "Tom Cruise",
   "resources": ["images.primary.medium", "itemInfo.title", "offersV2.listings.price"]
}

• Search inside a category with some filters applied:

{
   "partnerTag": "xyz-20",
   "searchIndex": "Electronics",
   "keywords": "DSLR Camera",
   "brand": "Sony",
   "minReviewsRating": "4",
   "resources": ["images.primary.medium", "itemInfo.title", "offersV2.listings.price"]
}

Sample Response

• The following snippet is a sample response for any SearchItems request:

{ 
 "searchResult": {
  "items": [
   {
    "asin": "0545162076",
    "detailPageURL": "https://www.amazon.com/dp/0545162076?tag=dgfd&linkCode=osi",
    "images": {
       /* Container for Images Resources if requested*/
    },
    "itemInfo": {
       /* Container for ItemInfo Resources if requested */
    },
    "offers": {
       /* Container for Offers Resources if requested */
    },
    {
       /* More items */
    }
   }
  ],
  "searchRefinements": {
      /* Container for searchRefinements Resources if requested */
  }
  "searchURL": "https://www.amazon.com/s/?field-keywords=Harry+Potter&search-alias=aps&tag=dgfd&linkCode=osi",
  "totalResultCount": 146
 }
}

• The following snippet is a sample response for the second SearchItems request in the Example Requests section above:

{
 "searchResult": {
  "items": [
   {
    "asin": "0545162076",
    "detailPageURL": "https://www.amazon.com/dp/0545162076?tag=dgfd&linkCode=osi",
    "images": {
     "primary": {
      "medium": {
       "height": 134,
       "url": "https://m.media-amazon.com/images/I/51BBTJaU6QL._SL160_.jpg",
       "width": 160
      }
     }
    },
    "itemInfo": {
     "title": {
      "displayValue": "Harry Potter Paperback Box Set (Books 1-7)",
      "label": "title",
      "locale": "en_US"
     }
    },
     "offersV2": {
       "listings": [{
         "availability": {
           "maxOrderQuantity": 1,
           "minOrderQuantity": 1,
           "type": "IN_STOCK"
         },
         "condition": {
           "conditionNote": "",
           "subCondition": "Unknown",
           "value": "New"
         },
         "dealDetails": {
           "accessType": "PRIME_EXCLUSIVE",
           "endTime": "2024-11-06T05:35Z",
           "percentClaimed": 38,
           "startTime": "2024-11-05T18:05Z"
         },
         "isBuyBoxWinner": true,
         "merchantInfo": {
           "name": "Amazon.com"
         },
         "price": {
           "money": {
             "amount": 59.49,
             "currency": "USD",
             "displayAmount": "$59.49"
           },
           "pricePerUnit": {
             "amount": 29.75,
             "currency": "USD",
             "displayAmount": "$29.75 / Count"
           },
           "savingBasis": {
             "money": {
               "amount": 69.99,
               "currency": "USD",
               "displayAmount": "$69.99"
             },
             "savingBasisType": "LIST_PRICE",
             "savingBasisTypeLabel": "List Price"
           },
           "savings": {
             "money": {
               "amount": 10.5,
               "currency": "USD",
               "displayAmount": "$10.50"
             },
             "percentage": 15
           }
         },
         "type": "LIGHTNING_DEAL",
         "violatesMAP": false
       }]
     }
   }
  ],
  "searchURL": "https://www.amazon.com/s/?field-keywords=Harry+Potter&search-alias=aps&tag=dgfd&linkCode=osi",
  "totalResultCount": 146
 }
}