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.
Returns a list of products and their attributes, based on a search query.
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.
This operation is available in all marketplaces.
Maximum request quota | Restore rate | Hourly request quota |
---|---|---|
20 requests | One request every five seconds | 720 requests per hour |
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. |
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.
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:
|
For information about standard request requirements, see Required request parameters.
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
For information about standard response formatting, see Response format.
<?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>