Product Advertising API
Developer Guide (API Version 2013-08-01)

Anatomy of a REST Request

Product Advertising API REST requests are URLs, as shown in the following example.
AWSAccessKeyId=[Access Key ID]&AssociateTag=[ID]&SearchIndex=Apparel&
Keywords=Shirt&Timestamp=[YYYY-MM-DDThh:mm:ssZ]&Signature=[Request Signature]

If you substituted real IDs in this request and put the entire example in a browser, you are sending Product Advertising API a request.

Although the previous example is the form you enter in a browser, it is difficult to read. For this reason, this guide presents the same request as follows:
AWSAccessKeyId=[Access Key ID]&
&Signature=[Request Signature]

For more information about Timestamp and Signature, see Authentication Parameters.

For information about signing a request using example AWS access identifiers, see Example REST Requests.

General Request Format

Part of every Product Advertising API request is always the same. The other part of the request varies according to the parameters used in the request, as shown in the following figure.

Request Terms that Remain the Same

The first two lines in the preceding example have the following:

  • The endpoint,

  • The service name, AWSECommerceService.

The service name in the request specifies that the request should be sent by the web servers to Product Advertising API. This line is always the same in every Product Advertising API request, regardless of locale.


The endpoint value varies by locale, but there are only two endpoints per locale. One endpoint in a locale is the secure version of the other endpoint. The following table lists the endpoints for Product Advertising API requests.













The endpoint remains the same for all Product Advertising API requests, as shown in the following example.

The third and fourth lines identify the request submitter. The AWS access key ID is required. It identifies the request submitter. You receive an AWS access key ID when you register for Product Advertising API.

The identifier AssociateTag is required. This is the ID for your Associate account. If you are an Associate, you must include your Associate tag in each request to be eligible to receive a referral fee for a customer's purchase.

Request Terms that Change

The remaining terms in the request vary for each operation. The terms, however, follow a pattern, as shown in the next figure.

The Operation parameter is required. Its value is one of the Product Advertising API operations. These operations are described throughout this guide.

The last lines, operation parameters, are representative of required and optional parameters. Requests can contain zero or more operation (up to ten) parameters.

Response Groups

An optional parameter for all Product Advertising API operations is ResponseGroup. Response groups control the type of information returned by the request. For example, the Large response group returns a great deal of information about the items included in a response, whereas the Medium and Small response groups return less.

There are response groups that return specific item information. For example, if you want to return images of the items, include the Image response group in the request. If you want price information, include the Offer response group in the request. To get browse node information, include the BrowseNode response group.

Each Product Advertising API operation can work with only a subset of all Product Advertising API response groups. The valid response groups that each Product Advertising API operation can use are listed in the API Reference.

All Product Advertising API operations use some response group by default. So specifying additional response groups is optional. Every Product Advertising API operation uses the Request response group, which echoes the operation name and the input parameters sent in the request. The other response groups used by default vary by operation.

For example, CartCreate, CartAdd, and CartModify use, by default, the Cart response group, which provides detailed information about the items in a cart.

When you see request examples in this guide, note the Operation parameter and all of the required and optional parameters.