Product Advertising API
Getting Started Guide (API Version 2013-08-01)

Submitting Your First Request in Product Advertising API

To submit your first request to Product Advertising API

  1. Go to the Product Advertising API Scratchpad.

  2. Choose an operation, for example ItemSearch.

  3. Under Common parameters, choose your marketplace and type your credentials.

  4. Choose your request parameters. For example, for the Keywords parameter, type "Harry Potter" and then click Run request.

  5. Under Request URL, your unsigned and request URL appear.

  6. Under Response, locate your response examples.

Congratulations! You just made your first Product Advertising API request.

Example unsigned request Operation=ItemSearch& SubscriptionId=ExampleID& AssociateTag=ExampleTag& SearchIndex=Books& Keywords=Harry Potter& ResponseGroup=Images,ItemAttributes,Offers

Example signed request Operation=ItemSearch& AWSAccessKeyId=ExampleID& AssociateTag=ExampleTag& Keywords=Harry%20Potter& ResponseGroup=Images%2CItemAttributes%2COffers& SearchIndex=Books& Timestamp=2015-08-11T17%3A51%3A56.000Z& Signature=oC%2Bv7Q33hROJDi2X79dYn%2BMzm9bRxDqYXk9qHTx3yEo%3D

From this example, you can see that a REST request is a URL. Everything before the question mark (?) specifies the destination of the request. This destination is the same for every Product Advertising API request (sent to the same locale). Everything after the question mark is a parameter in the request. This request searches (Operation=ItemSearch) for all books (SearchIndex=Books) that have "Harry Potter" in the title (Title=Harry%20Potter).


Product Advertising API has a number of locales and each locale has a slightly different endpoint. Although you can send requests to any locale, you typically send them to the locale where your customers reside. For more information about locales and endpoints, see Anatomy of a REST Request in the Product Advertising API Developer Guide.

Product Advertising API responds to the request by returning an XML document. The following is a snippet of the response to the preceding example.

<TotalResults>2427</TotalResults> <TotalPages>243</TotalPages> <Item> <ASIN>0545139708</ASIN> <DetailPageURL> %3DAKIAIOSFODNN7EXAMPLE%26tag%3Dws%26linkCode%3Dxm2%26camp%3D2025%26creative %3D165953%26creativeASIN%3D0545139708</DetailPageURL> <ItemLinks> <ItemLink> <Description>Technical Details</Description> <URL> %3DAKIAIOSFODNN7EXAMPLE%26tag%3Dws%26linkCode%3Dxm2%26camp%3D2025%26creative %3D386001%26creativeASIN%3D0545139708</URL> </ItemLink> <ItemLink> <Description>Add To Baby Registry</Description> <URL> %3DAKIAIOSFODNN7EXAMPLE%26tag%3Dws%26linkCode%3Dxm2%26camp%3D2025%26creative %3D386001%26creativeASIN%3D0545139708</URL> </ItemLink> <ItemLink> <Description>Add To Wedding Registry</Description> <URL> %3DAKIAIOSFODNN7EXAMPLE%26tag%3Dws%26linkCode%3Dxm2%26camp%3D2025%26creative %3D386001%26creativeASIN%3D0545139708</URL> </ItemLink> <ItemLink> <Description>Add To Wishlist</Description> <URL> %3DAKIAIOSFODNN7EXAMPLE%26tag%3Dws%26linkCode%3Dxm2%26camp%3D2025%26creative %3D386001%26creativeASIN%3D0545139708</URL> </ItemLink> <ItemLink> <Description>Tell A Friend</Description> <URL> %26tag%3Dws%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN %3D0545139708</URL> </ItemLink> <ItemLink> <Description>All Customer Reviews</Description> <URL> %3DAKIAIOSFODNN7EXAMPLE%26tag%3Dws%26linkCode%3Dxm2%26camp%3D2025 %26creative%3D386001%26creativeASIN%3D0545139708</URL> </ItemLink> <ItemLink> <Description>All Offers</Description> <URL> %3DAKIAIOSFODNN7EXAMPLE%26tag%3Dws%26linkCode%3Dxm2%26camp %3D2025%26creative%3D386001%26creativeASIN%3D0545139708</URL> </ItemLink> </ItemLinks> <ItemAttributes> <Author>J.K. Rowling</Author> <Manufacturer>Arthur A. Levine Books</Manufacturer> <ProductGroup>Book</ProductGroup> <Title>Harry Potter And The Deathly Hallows</Title> </ItemAttributes>

This snippet shows that 2427 items match the search criteria. The first item returned is, "Harry Potter and the Deathly Hallows." Item details are returned, including the name of the author, illustrator, book manufacturer, and product identifier (ASIN). If you copy the DetailPageURL into a browser, the product detail page for that item is displayed.


An Amazon Standard Item Number (ASIN) is an alphanumeric token that uniquely identifies items for sale on Amazon.

Submitting URLs in a browser provides a good demonstration of how Product Advertising API requests and responses work, but this practice isn't appropriate for customer applications. The remainder of this section describes how to programmatically issue Product Advertising API requests and process responses.