Amazon Services
Amazon Marketplace Web Service (Amazon MWS) Documentation

Deprecation Notice:

Amazon Marketplace Web Service (MWS) will no longer be available after March 31, 2024. All MWS developers must migrate to Selling Partner API (SP-API) to avoid service disruptions. Refer to the Migration Hub for more information.

Amazon MWS Documentation

ListMatchingProducts

Returns a list of products and their attributes, based on a search query.

Description

The ListMatchingProducts operation returns a list of products and their attributes, ordered by relevancy, based on a search query that you specify. Your search query can be a phrase that describes the product or it can be a product identifier such as a GCID, UPC, EAN, ISBN, or JAN. If you have the ASIN associated with your product, use the GetMatchingProduct operation. Note that the product identifier cannot be a SellerSKU. If your query does not return any matching products, the query will be broadened using spelling correction or the removal of keywords to find matches. This operation returns a maximum of ten products and does not return non-buyable products.

Availability

This operation is available in all marketplaces.

Throttling

Maximum request quota Restore rate Hourly request quota
20 requests One request every five seconds 720 requests per hour
Operations in the Products API section that send lists of items as input parameters have restore rates that are measured by item. For information on per-item throttling, see Throttling in the Products API. For definitions of throttling terminology and for a complete explanation of throttling, see Throttling: Limits to how often you can submit requests in the Amazon MWS Developer Guide.

Request parameters

For more information about the request parameters that are required for all Amazon MWS operations, see Required request parameters in the Amazon MWS Developer Guide.

Name Description Required Valid values
MarketplaceId A marketplace identifier. Specifies the marketplace from which products are returned.

Type: xs:string

Yes For a list of MarketplaceId values, see Amazon MWS endpoints and MarketplaceId values in the Amazon MWS Developer Guide.
Query A search string with the same support as that provided on Amazon marketplace websites.

Example: Query=harry potter dvd

Type: xs:string

Yes  
QueryContextId An identifier for the context within which the given search will be performed. A marketplace might provide mechanisms for constraining a search to a subset of potential items. For example, the Amazon retail marketplace allows queries to be constrained to a specific category. The QueryContextId parameter specifies such a sub-set. If it is omitted, the search will be performed using the default context for the marketplace, which will typically contain the largest set of items.

Type: xs:string

No See QueryContextId values for a complete list of QueryContextId values that can be used in the various Amazon retail marketplaces.

Response elements

The response elements that the ListMatchingProducts operation returns are described by the following publicly available XSDs:

The following table provides additional information about some of the key elements that are returned by the ListMatchingProducts operation.

Note: As Amazon updates the Amazon MWS Products API section to include new response elements, we may update the ProductsAPI_Response.xsd and default.xsd schemas. Keep this in mind if you choose to use these schemas for validation.
Name Description
Product Contains four of the sub-elements of the Product element from ProductsAPI_Response.xsd. These sub-elements are: Identifiers, AttributeSets, Relationships, and SalesRankings.
Identifiers Contains the MarketplaceASIN combination that uniquely identifies a product.
AttributeSets Contains product attributes, from the ItemAttributes element of default.xsd, if they are applicable to the product that is returned. Note that a Product response element will have multiple attribute sets if it has attributes in more than one language. All of the attributes, even ones that are not translated, are repeated in each attribute set. The language used by each attribute set is denoted by a lang attribute.
Note: If a single product has more than one image, then only the URL for the main image is returned.
Relationships Contains product variation information, if applicable. If your search criteria match a product that is identified by a variation parent ASIN, the related VariationChild elements are contained in the Relationships element. If your search criteria match a specific variation child ASIN, the related VariationParent element is contained in the Relationships element.
Note: Because this operation does not return all product attributes, it is possible to get VariationChild elements with different ASIN values but the same variation element values. These are distinct variation child ASINs even though product attributes that differentiate them from each other are not returned.

Variation attributes can be found in the VariationChild element of default.xsd.

Note: Variation attributes are not included in the VariationChild element if the input ASIN values have more than 2000 combined VariationChild elements.
SalesRankings Sales rank information for the product by product category.

Sub-elements are:

  • ProductCategoryId. Identifies the product category that the sales rank is taken from.
  • Rank. The sales rank of the product within the product category.

Examples

Example query request

For information about standard request requirements, see Required request parameters.

Show example code Hide example code

POST /Products/2011-10-01 HTTP/1.1
Content-Type: x-www-form-urlencoded
Host: mws.amazonservices.com
User-Agent: <Your User Agent Header>

AWSAccessKeyId=AKIAEXAMPLEFWR4TJ7ZQ
&Action=ListMatchingProducts
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&MarketplaceId=ATVPDKIKX0DER
&Query=0439708184
&SellerId=A1IMEXAMPLEWRC
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-12-12T22%3A23%3A50Z
&Version=2011-10-01
&Signature=V%2BEXAMPLERT%2Baj%2Fxwqo7y3PIifMFHeqFlNYW0EXAMPLEA%3D

↑ Top

Example response

For information about standard response formatting, see Response format.

Show example code Hide example code

<?xml version="1.0"?>
<ListMatchingProductsResponse
    xmlns="http://mws.amazonservices.com/schema/Products/2011-10-01">
    <ListMatchingProductsResult>
        <Products xmlns="http://mws.amazonservices.com/schema/Products/2011-10-01"
            xmlns:ns2="http://mws.amazonservices.com/schema/Products/2011-10-01/default.xsd">
            <Product>
                <Identifiers>
                    <MarketplaceASIN>
                        <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
                        <ASIN>059035342X</ASIN>
                    </MarketplaceASIN>
                </Identifiers>
                <AttributeSets>
                    <ns2:ItemAttributes xml:lang="en-US">
                        <ns2:Author>Rowling, J.K.</ns2:Author>
                        <ns2:Binding>Paperback</ns2:Binding>
                        <ns2:Brand>Scholastic Press</ns2:Brand>
                        <ns2:Creator Role="Illustrator">GrandPré, Mary</ns2:Creator>
                        <ns2:Edition>1st</ns2:Edition>
                        <ns2:Feature>Recommended Age: 9 years and up</ns2:Feature>
                        <ns2:ItemDimensions>
                            <ns2:Height Units="inches">0.80</ns2:Height>
                            <ns2:Length Units="inches">7.50</ns2:Length>
                            <ns2:Width Units="inches">5.20</ns2:Width>
                            <ns2:Weight Units="pounds">0.50</ns2:Weight>
                        </ns2:ItemDimensions>
                        <ns2:IsAutographed>false</ns2:IsAutographed>
                        <ns2:IsMemorabilia>false</ns2:IsMemorabilia>
                        <ns2:Label>Scholastic Paperbacks</ns2:Label>
                        <ns2:Languages>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Unknown</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Original Language</ns2:Type>
                            </ns2:Language>
                            <ns2:Language>
                                <ns2:Name>english</ns2:Name>
                                <ns2:Type>Published</ns2:Type>
                            </ns2:Language>
                        </ns2:Languages>
                        <ns2:ListPrice>
                            <ns2:Amount>10.99</ns2:Amount>
                            <ns2:CurrencyCode>USD</ns2:CurrencyCode>
                        </ns2:ListPrice>
                        <ns2:Manufacturer>Scholastic Paperbacks</ns2:Manufacturer>
                        <ns2:NumberOfItems>1</ns2:NumberOfItems>
                        <ns2:NumberOfPages>320</ns2:NumberOfPages>
                        <ns2:PackageDimensions>
                            <ns2:Height Units="inches">1.00</ns2:Height>
                            <ns2:Length Units="inches">7.50</ns2:Length>
                            <ns2:Width Units="inches">5.20</ns2:Width>
                            <ns2:Weight Units="pounds">0.50</ns2:Weight>
                        </ns2:PackageDimensions>
                        <ns2:PackageQuantity>1</ns2:PackageQuantity>
                        <ns2:PartNumber>9780590353427</ns2:PartNumber>
                        <ns2:ProductGroup>Book</ns2:ProductGroup>
                        <ns2:ProductTypeName>ABIS_BOOK</ns2:ProductTypeName>
                        <ns2:PublicationDate>1999-10-01</ns2:PublicationDate>
                        <ns2:Publisher>Scholastic Paperbacks</ns2:Publisher>
                        <ns2:ReleaseDate>1999-09-08</ns2:ReleaseDate>
                        <ns2:SmallImage>
                            <ns2:URL>
                                http://ecx.images-amazon.com/images/I/51MU5VilKpL._SL75_.jpg
                            </ns2:URL>
                            <ns2:Height Units="pixels">75</ns2:Height>
                            <ns2:Width Units="pixels">51</ns2:Width>
                        </ns2:SmallImage>
                        <ns2:Studio>Scholastic Paperbacks</ns2:Studio>
                        <ns2:Title>Harry Potter and the Sorcerer's Stone (Book 1)</ns2:Title>
                    </ns2:ItemAttributes>
                </AttributeSets>
                <Relationships/>
                <SalesRankings>
                    <SalesRank>
                        <ProductCategoryId>book_display_on_website</ProductCategoryId>
                        <Rank>401</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>15356791</ProductCategoryId>
                        <Rank>5</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>3153</ProductCategoryId>
                        <Rank>8</Rank>
                    </SalesRank>
                    <SalesRank>
                        <ProductCategoryId>17468</ProductCategoryId>
                        <Rank>16</Rank>
                    </SalesRank>
                </SalesRankings>
            </Product>
        </Products>
    </ListMatchingProductsResult>
    <ResponseMetadata>
        <RequestId>3b805a12-689a-4367-ba86-EXAMPLE91c0b</RequestId>
    </ResponseMetadata>
</ListMatchingProductsResponse>

↑ Top