SearchItems

Description

The SearchItems operation searches for items on Amazon based on a search query. The Amazon Product Advertising 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:

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 Product Advertising API.

Request Parameters

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

Name Description Required
Actor Actor name associated with the item. You can enter all or part of the name.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"Actor": "Tom Cruise"}
No
Artist Artist name associated with the item. You can enter all or part of the name.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"Artist":"Coldplay"}
No
Author Author name associated with the item. You can enter all or part of the name.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"Author":"Enid Blyton"}
No
Availability Filters available items on Amazon. By default, all requests returns available items only. For more information and valid values, refer Availability Parameter.
  • Type: String
  • Default Value: Available
  • Usage: {"Availability":"IncludeOutOfStock"}
No
Brand Brand name associated with the item. You can enter all or part of the name.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"Brand":"Apple"}
No
BrowseNodeId A unique ID assigned by Amazon that identifies a product category/sub-category. The BrowseNodeId is a positive Long having max value upto Long.MAX_VALUE i.e. 9223372036854775807 (inclusive).
  • Type: String (Positive integers only)
  • Default Value: None
  • Usage: {"BrowseNodeId": "290060"}
No
Condition The condition parameter filters offers by condition type. For example, Condition:Used will return items having atleast one offer of Used condition type. By default, condition equals Any. For more information and valid values, refer Condition Parameter.
  • Type: String
  • Default Value: Any
  • Usage: {"Condition":"Used"}
No
CurrencyOfPreference Currency of preference in which the prices information should be returned in response. By default the prices are returned in the default currency of the marketplace. Expected currency code format is the ISO 4217 currency code (i.e. USD, EUR etc.). For information on default currency and valid currencies for a marketplace, refer Locale Reference.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"CurrencyOfPreference":"USD"}
No
DeliveryFlags The delivery flag filters items which satisfy a certain delivery program promoted by the specific Amazon Marketplace. For example, Prime DeliveryFlag will return items having at least one offer which is Prime Eligible. For more information and valid values, refer DeliveryFlags Parameter.
  • Type: List of Strings
  • Default Value: None
  • Usage: {"DeliveryFlags":["Prime"]}
No
ItemCount The number of items desired in SearchItems response.
  • Type: Integer (Between 1 to 10)
  • Default Value: 10
  • Usage: {"ItemCount":5}
No
ItemPage The ItemPage parameter can be used to fetch the specific set/page of items to be returned from the available Search Results. The number of items returned in a page is determined by the ItemCount parameter. For e.g. if the third set of 5 items (i.e. items numbered 11 to 15) are desired for a search request, you may specify ItemPage as 3 and ItemCount as 5.
  • Type: Integer (Between 1 to 10)
  • Default Value: 1
  • Usage: {"ItemPage":3}
No
Keywords A word or phrase that describes an item i.e. the search query.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"Keywords":"Harry Potter"}
No
LanguagesOfPreference Languages in order of preference in which the item information should be returned in response. By default the item information is returned in the default language of the marketplace. Expected locale format is the ISO 639 language code followed by underscore followed by the ISO 3166 country code (i.e. en_US, fr_CA etc.). For information on default language and valid languages for a marketplace, refer Locale Reference.
  • Type: List of Strings (Non-Empty)
  • Default Value: None
  • Usage: {"LanguagesOfPreference":["en_US", "en_GB"]}
No
Marketplace Target Amazon Locale. For more information, refer Common Request Parameters.
  • Type: String
  • Default Value: None
  • Usage: {"Marketplace":"www.amazon.com"}
No
MaxPrice Filters search results to items with at least one offer price below the specified value. Prices appear in lowest currency denomination. For example, in US marketplace, 3241 is $31.41.
  • Type: Positive Integer
  • Default Value: None
  • Usage: {"MaxPrice":3241}
No
Merchant Filters search results to return items having at least one offer sold by target merchant. By default the value "All" is passed. For more information, refer Merchant Parameter.
  • Type: String
  • Default Value: All
  • Usage: {"Merchant":"Amazon"}
No
MinPrice Filters search results to items with at least one offer price above the specified value. Prices appear in lowest currency denomination. For example, in US marketplace, 3241 is $32.41.
  • Type: Positive Integer
  • Default Value: None
  • Usage: {"MinPrice":3241}
No
MinReviewsRating Filters search results to items with customer review ratings above specified value.
  • Type: Positive Integer less than 5
  • Default Value: None
  • Usage: {"MinReviewsRating":2}
No
MinSavingPercent Filters search results to items with at least one offer having saving percentage above the specified value.
  • Type: Positive Integer less than 100
  • Default Value: None
  • Usage: {"MinSavingPercent":50}
No
OfferCount The number of offers desired for each item in the search results. Offers are returned if any of Offers Resources are requested.
  • Type: Positive Integer
  • Default Value: 1
  • Usage: {"OfferCount":1}
No
PartnerTag Unique ID for a partner. For more information, refer Common Request Parameters.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"PartnerTag":"xyz-20"}
Yes
PartnerType The type of Amazon program. For more information and valid values, refer Common Request Parameters.
  • Type: String
  • Default Value: None
  • Usage: {"PartnerType":"Associates"}
Yes
Properties Reserved Parameter.
  • Type: Map (String, String)
  • Default Value: None
  • Usage: {"Properties": {"Key": "Value"} }
No
Resources Specifies the types of values to return. You can specify multiple resources in one request. For list of valid Resources for SearchItems operation, refer Resources Parameter.
  • Type: List of String
  • Default Value: ItemInfo.Title
  • Usage: {"Resources":["Images.Primary.Medium", "ItemInfo.Title"]}
No
SearchIndex Indicates the product category to search. SearchIndex values differ by marketplace. For list of search index values, refer Locale Reference.
  • Type: String (Non-Empty)
  • Default Value: All
  • Usage: {"SearchIndex":"Electronics"}
No
SortBy The way in which items in the response are sorted. For more information on valid values, refer SortBy Parameter.
  • Type: String
  • Default Value: None
  • Usage: {"SortBy":"Relevance"}
No
Title Title associated with the item. Title searches are subset of Keywords searches. Use a Keywords search if a Title search does not return desired items.
  • Type: String (Non-Empty)
  • Default Value: None
  • Usage: {"Title":"And Then There Were None"}
No

Availability Parameter

Availability Value Description
Available Only available items
IncludeOutOfStock Include Out of Stock items

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.

Condition Value Description
Any Offer Listings for items across any condition
New Offer Listings for New items.
Used Offer Listings for Used items
Collectible Offer Listings for Collectible items
Refurbished Offer Listings for Certified Refurbished items

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.

DeliveryFlag Value Description
AmazonGlobal A delivery program featuring international shipping to certain Exportable Countries
FreeShipping A delivery program featuring free shipping of an item
FulfilledByAmazon Fulfilled by Amazon indicates that products are stored, packed and dispatched by Amazon
Prime An offer for an item which is eligible for Prime Program

Merchant Parameter

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

Merchant Value Description
All List Offers from all Merchants
Amazon List Offers only from Amazon

Resources Parameter

Resource Value Description
BrowseNodeInfo.BrowseNodes Get the browse nodes associated with the item. Using this resource only will return Id, DisplayName, ContextFreeName and IsRoot information associated with each browse node. For more information, refer BrowseNodeInfo Resources.
BrowseNodeInfo.BrowseNodes.Ancestor Get the Ancestry ladder associated with each of the browse nodes the item falls under. Using this resource will return ancestry ladder along with Id, DisplayName, ContextFreeName and IsRoot information associated with each browse node. For more information, refer BrowseNodeInfo Resources.
BrowseNodeInfo.BrowseNodes.SalesRank Get the SalesRank information with each of the browse nodes the item falls under. Using this resource will return sales rank along with Id, DisplayName, ContextFreeName and IsRoot information associated with each browse node. For more information, refer BrowseNodeInfo Resources.
BrowseNodeInfo.WebsiteSalesRank Get WebsiteSalesRank information associated with the item. For more information, refer BrowseNodeInfo Resources.
Images.Primary.Small Returns small-sized primary image for each item. For more information, refer Images Resources
Images.Primary.Medium Returns medium-sized primary image for each item. For more information, refer Images Resources
Images.Primary.Large Returns large-sized primary image for each item. For more information, refer Images Resources
Images.Variants.Small Returns small-sized variant images for each item. For more information, refer Images Resources
Images.Variants.Medium Returns medium-sized variant images for each item. For more information, refer Images Resources
Images.Variants.Large Returns large-sized variant images for each item. For more information, refer Images Resources
ItemInfo.ByLineInfo Returns set of attributes that specifies basic information of the item. For more information, refer ItemInfo Resources
ItemInfo.Classifications Returns set of attributes that are used to classify an item into a particular category. For more information, refer ItemInfo Resources
ItemInfo.ContentInfo Returns set of attributes that are specific to the content like Books, Movies, etc. For more information, refer ItemInfo Resources
ItemInfo.ContentRating Returns set of attributes that specifies what age group is suitable to view said media. For more information, refer ItemInfo Resources
ItemInfo.ExternalIds Returns set of identifiers that is used globally to identify a particular product. For more information, refer ItemInfo Resources
ItemInfo.Features Returns set of attributes that specifies an item's key features and benefits. For more information, refer ItemInfo Resources
ItemInfo.ManufactureInfo Returns set of attributes that specifies manufacturing related information of an item. For more information, refer ItemInfo Resources
ItemInfo.ProductInfo Returns set of attributes that describe non-technical aspects of an item. For more information, refer ItemInfo Resources
ItemInfo.TechnicalInfo Returns set of attributes that describes the technical aspects of the item. For more information, refer ItemInfo Resources
ItemInfo.Title Returns the title of the product. For more information, refer ItemInfo Resources
ItemInfo.TradeInInfo Returns set of attributes that specifies trade-in information of an item. For more information, refer ItemInfo Resources
Offers.Listings.Availability.MaxOrderQuantity Returns maximum number of quantity that can be purchased for a product. For more information, refer Offers Resources
Offers.Listings.Availability.Message Returns Availability message of the product. For more information, refer Offers Resources
Offers.Listings.Availability.MinOrderQuantity Returns minimum number of quantity needed to make the purchase of the product. For more information, refer Offers Resources
Offers.Listings.Availability.Type Returns availability type of the product. For more information, refer Offers Resources
Offers.Listings.Condition Returns condition of the product. For more information, refer Offers Resources
Offers.Listings.Condition.SubCondition Returns subcondition of the product. For more information, refer Offers Resources
Offers.Listings.DeliveryInfo.IsAmazonFulfilled Returns whether an offer for the product is fulfilled by Amazon. For more information, refer Offers Resources
Offers.Listings.DeliveryInfo.IsFreeShippingEligible Returns whether an offer for the product is eligible for free shipping. For more information, refer Offers Resources
Offers.Listings.DeliveryInfo.IsPrimeEligible Returns whether an offer for the product is prime eligible. For more information, refer Offers Resources
Offers.Listings.IsBuyBoxWinner Returns whether the given offer for the product is buy box winner on the detail page of the product. For more information, refer Offers Resources
Offers.Listings.LoyaltyPoints.Points Returns loyalty points related information for an offer (Currently only supported in Japan marketplace). For more information, refer Offers Resources
Offers.Listings.MerchantInfo Returns seller information for the offer of the product. For more information, refer Offers Resources
Offers.Listings.Price Returns offer buying price of a product. For more information, refer Offers Resources
Offers.Listings.ProgramEligibility.IsPrimeExclusive Returns whether a product is associated with prime exclusive members. For more information, refer Offers Resources
Offers.Listings.ProgramEligibility.IsPrimePantry Returns whether a product is associated with prime pantry program. For more information, refer Offers Resources
Offers.Listings.Promotions Returns various promotions for a product. For more information, refer Offers Resources
Offers.Listings.SavingBasis Returns strike-though price for a particular offer of the product. For more information, refer Offers Resources
Offers.Summaries.HighestPrice Returns highest buying price among all offers for a given item for a particular condition. For more information, refer Offers Resources
Offers.Summaries.LowestPrice Returns lowest buying price among all offers for a given item for a particular condition. For more information, refer Offers Resources
Offers.Summaries.OfferCount Returns total number of offers for a given item for a particular condition. For more information, refer Offers Resources
ParentASIN Returns the parent ASIN for a given item. For more information, refer ParentASIN Resource
SearchRefinements Returns dynamic search refinements for each search request. For more information, refer SearchRefinements Resource

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.

SortBy Value Description
AvgCustomerReviews Sorts results according to average customer reviews
Featured Sorts results with featured items having higher rank
NewestArrivals Sorts results with according to newest arrivals
Price:HighToLow Sorts results according to most expensive to least expensive
Price:LowToHigh Sorts results according to least expensive to most expensive
Relevance Sorts results with relevant items having higher rank

Response Elements

The following are common response elements returned:

Name Description
Errors List of errors.
SearchResult Container for search result. It contains Items container, TotalResultCount, SearchURL and SearchRefinements container.
Items Container for item information including ASIN, Title and other attributes depending on resources requested.
TotalResultCount The total number of items that match the search query.
SearchURL URL to link back to search results page on Amazon for the search request.
SearchRefinements Container for SearchRefinements resource if requested.

Example Requests

  • General keyword search request:
{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "Keywords": "harry potter"
}
  • General keyword search using ItemCount and Resources parameter:
{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "Keywords": "harry potter",
   "ItemCount": 1,
   "Resources": ["Images.Primary.Medium", "ItemInfo.Title", "Offers.Listings.Price"]
}
  • Search by Actor:
{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "Actor": "Tom Cruise",
   "Resources": ["Images.Primary.Medium", "ItemInfo.Title", "Offers.Listings.Price"]
}
  • Search inside a category with some filters applied:
{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "SearchIndex": "Electronics",
   "Keywords": "DSLR Camera",
   "Brand": "Sony",
   "MinReviewsRating": "4",
   "Resources": ["Images.Primary.Medium", "ItemInfo.Title", "Offers.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"
     }
    },
    "Offers": {
     "Listings": [
      {
       "Condition": {
          "DisplayValue": "nuevo",
          "Label": "Condición",
          "Locale": "es_US",
          "Value": "New"
        },
       "Id": "l2dKMJRrPVX3O7DAPQ6DWLXBjBeRYsruAnKVf1LNXyjFTUw%2FnNBn41CJV2489iPYMSGuynW8uuwMQ7GhGrcT9F%2F%2FgO5bdp%2B2l0HbPvvHy05ASCdqrOaxWA%3D%3D",
       "Price": {
        "Amount": 52.16,
        "Currency": "USD",
        "DisplayAmount": "$52.16",
        "Savings": {
         "Amount": 34.77,
         "Currency": "USD",
         "DisplayAmount": "$34.77 (40%)",
         "Percentage": 40
        }
       }
      }
     ]
    }
   }
  ],
  "SearchURL": "https://www.amazon.com/s/?field-keywords=Harry+Potter&search-alias=aps&tag=dgfd&linkCode=osi",
  "TotalResultCount": 146
 }
}

results matching ""

    No results matching ""