# 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](en-us/api-reference/resources/browse-node-info)
* [Images](en-us/api-reference/resources/images)
* [ItemInfo](en-us/api-reference/resources/item-info)
* [OffersV2](en-us/api-reference/resources/offersV2)
* [searchRefinements](en-us/api-reference/resources/search-refinements)

## 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](en-us/api-reference/resources/search-refinements) 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](#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](en-us/locale-reference).

## Request Parameters {#ItemLookup-rp}

Check [Common Request Headers and Parameters](en-us/concepts/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](en-us/get-started/using-curl). 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. <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"actor": "Tom Cruise"}</code></li></ul> | No |
| artist | Artist name associated with the item. You can enter all or part of the name. <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"artist":"Coldplay"}</code></li></ul> | No |
| author | Author name associated with the item. You can enter all or part of the name. <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"author":"Enid Blyton"}</code></li></ul> | No |
| availability | Filters available items on Amazon. By default, all requests returns available items only. For more information and valid values, refer [Availability Parameter](#availability-parameter). <ul><li>Type: <i>String</i></li><li>Default Value: <code>Available</code></li><li>Usage: <code>{"availability":"IncludeOutOfStock"}</code></li></ul> | No |
| brand | Brand name associated with the item. You can enter all or part of the name. <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"brand":"Apple"}</code></li></ul> | 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). <ul><li>Type: <i>String (Positive integers only)</i></li><li>Default Value: None</li><li>Usage: <code>{"browseNodeId": "290060"}</code></li></ul> | No  |
| condition | The condition parameter filters offers by condition type. For example, Condition:New will return items having atleast one offer of New condition type. By default, condition equals Any. For more information and valid values, refer [Condition Parameter](#condition-parameter). <ul><li>Type: <i>String</i></li><li>Default Value: <code>Any</code></li><li>Usage: <code>{"condition":"New"}</code></li></ul> | 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](en-us/locale-reference). <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"currencyOfPreference":"USD"}</code></li></ul> | 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](#deliveryflags-parameter). <ul><li>Type: <i>List of Strings</i></li><li>Default Value: None</li><li>Usage: <code>{"deliveryFlags":["Prime"]}</code></li></ul> | No |
| itemCount | The number of items desired in SearchItems response. <ul><li>Type: <i>Integer (Between 1 to 10)</i></li><li>Default Value: <code>10</code></li><li>Usage: <code>{"itemCount":5}</code></li></ul> | 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`. <ul><li>Type: <i>Integer (Between 1 to 10)</i></li><li>Default Value: <code>1</code></li><li>Usage: <code>{"itemPage":3}</code></li></ul> | No |
| keywords | A word or phrase that describes an item i.e. the search query. <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"keywords":"Harry Potter"}</code></li></ul> | 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](en-us/locale-reference). Currently only single language of preference is supported. <ul><li>Type: <i>List of Strings (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"languagesOfPreference":["en_GB"]}</code></li></ul> | No |
| marketplace | Target Amazon Locale. For more information, refer [Common Request Headers and Parameters](en-us/concepts/common-request-headers-and-parameters). <ul><li>Type: <i>String</i></li><li>Default Value: None</li><li>Usage: <code>{"marketplace":"www.amazon.com"}</code></li></ul> | 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. <ul><li>Type: <i>Positive Integer</i></li><li>Default Value: None</li><li>Usage: <code>{"maxPrice":3241}</code></li></ul> | 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. <ul><li>Type: <i>Positive Integer</i></li><li>Default Value: None</li><li>Usage: <code>{"minPrice":3241}</code></li></ul> | No |
| minReviewsRating | Filters search results to items with customer review ratings above specified value. <ul><li>Type: <i>Positive Integer less than 5</i></li><li>Default Value: None</li><li>Usage: <code>{"minReviewsRating":2}</code></li></ul> | No |
| minSavingPercent | Filters search results to items with at least one offer having saving percentage above the specified value. <ul><li>Type: <i>Positive Integer less than 100</i></li><li>Default Value: None</li><li>Usage: <code>{"minSavingPercent":50}</code></li></ul> | No |
| partnerTag | Unique ID for a partner. For more information, refer [Common Request Headers and Parameters](en-us/concepts/common-request-headers-and-parameters). <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"partnerTag":"xyz-20"}</code></li></ul> | Yes |
| properties | Reserved Parameter. <ul><li>Type: <i>Map (String, String)</i></li><li>Default Value: None</li><li>Usage: <code>{"properties": {"Key": "Value"} }</code></li></ul> | 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](#resources-parameter). <ul><li>Type: <i>List of String</i></li><li>Default Value: <code>itemInfo.title</code></li><li>Usage: <code>{"resources":["images.primary.medium", "itemInfo.title"]}</code></li></ul> | No |
| searchIndex | Indicates the product category to search. SearchIndex values differ by marketplace. For list of search index values, refer [Locale Reference](en-us/locale-reference). <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: <code>All</code></li><li>Usage: <code>{"searchIndex":"Electronics"}</code></li></ul> | No |
| sortBy | The way in which items in the response are sorted. For more information on valid values, refer [SortBy Parameter](#sortby-parameter). <ul><li>Type: <i>String</i></li><li>Default Value: None</li><li>Usage: <code>{"sortBy":"Relevance"}</code></li></ul> | 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. <ul><li>Type: <i>String (Non-Empty)</i></li><li>Default Value: None</li><li>Usage: <code>{"title":"And Then There Were None"}</code></li></ul> | 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. Includes New and Used. |
| New | Offer Listings for New 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 |

#### 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](en-us/api-reference/resources/browse-node-info). |
| 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](en-us/api-reference/resources/browse-node-info). |
| 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](en-us/api-reference/resources/browse-node-info). |
| browseNodeInfo.websiteSalesRank | Get WebsiteSalesRank information associated with the item. For more information, refer [BrowseNodeInfo Resources](en-us/api-reference/resources/browse-node-info). |
| images.primary.small | Returns small-sized primary image for each item. For more information, refer [Images Resources](en-us/api-reference/resources/images) |
| images.primary.medium | Returns medium-sized primary image for each item. For more information, refer [Images Resources](en-us/api-reference/resources/images) |
| images.primary.large | Returns large-sized primary image for each item. For more information, refer [Images Resources](en-us/api-reference/resources/images) |
| images.variants.small | Returns small-sized variant images for each item. For more information, refer [Images Resources](en-us/api-reference/resources/images) |
| images.variants.medium | Returns medium-sized variant images for each item. For more information, refer [Images Resources](en-us/api-reference/resources/images) |
| images.variants.large | Returns large-sized variant images for each item. For more information, refer [Images Resources](en-us/api-reference/resources/images) |
| itemInfo.byLineInfo | Returns set of attributes that specifies basic information of the item. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.classifications | Returns set of attributes that are used to classify an item into a particular category. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.contentInfo | Returns set of attributes that are specific to the content like Books, Movies, etc. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.contentRating | Returns set of attributes that specifies what age group is suitable to view said media. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.externalIds | Returns set of identifiers that is used globally to identify a particular product. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.features | Returns set of attributes that specifies an item's key features and benefits. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.manufactureInfo | Returns set of attributes that specifies manufacturing related information of an item. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.productInfo | Returns set of attributes that describe non-technical aspects of an item. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.technicalInfo | Returns set of attributes that describes the technical aspects of the item. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.title | Returns the title of the product. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| itemInfo.tradeInInfo | Returns set of attributes that specifies trade-in information of an item. For more information, refer [ItemInfo Resources](en-us/api-reference/resources/item-info) |
| offersV2.listings.availability                      | Returns maximum number of quantity that can be purchased for a product. For more information, refer to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                                                               |                                                                                                                                                                          |
| offersV2.listings.condition                         | Returns condition of the product. For more information, refer to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                                                                                                     |
| offersV2.listings.dealDetails                       | Returns deal information. For more information, refer to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                                                                                                             |
| offersV2.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 to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                                  |
| offersV2.listings.loyaltyPoints                     | Returns loyalty points related information for an offer (Currently only supported in Japan marketplace). For more information, refer to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                              |
| offersV2.listings.merchantInfo                      | Returns seller information for the offer of the product. For more information, refer to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                                                                              |
| offersV2.listings.price                             | Returns offer buying price of a product. For more information, refer to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                                                                                              |
| offersV2.listings.type                              | Returns offer type. For more information, refer to [OffersV2 Resources](en-us/api-reference/resources/offersV2)                                                                                                                                                                                                                                   |
| ParentASIN | Returns the parent ASIN for a given item. For more information, refer [ParentASIN Resource](en-us/api-reference/resources/parent-asin) |
| searchRefinements | Returns dynamic search refinements for each search request. For more information, refer [searchRefinements Resource](en-us/api-reference/resources/search-refinements) |

#### 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 | Optional array of error objects for items or query parameters that encountered issues. Only present when partial failures occur. |
| 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:

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

* General keyword search using `ItemCount` and `Resources` parameter:

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

* Search by Actor:

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

* Search inside a category with some filters applied:

```json
{
   "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:

```json
{ 
 "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](#example-requests) section above:

```json
{
 "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
 }
}
```
