Requests

Topics

The Amazon Associates Web Service web service supports REST requests for remotely calling Amazon Associates Web Service operations hosted by Amazon servers. REST requests are simple HTTP requests, using either the GET method with parameters in the URL, or the POST method with parameters in the POST body. The response is an XML document that conforms to a schema.

You might use REST requests because they are more intuitive than their SOAP counterpart or because a SOAP toolkit is not available for your platform. The example requests used throughout this guide are in REST.

Amazon Associates Web Service REST requests are URLs, for example,

http://ecs.amazonaws.com/onca/xml?Service=AWSECommerceService&Operation=ItemSearch&AWSAccessKeyId=[Access Key D]&
AssociateTag=[ID]&SearchIndex=Apparel&Keywords=Shirt

If you substituted real IDs in this request and put the entire example in a browser, you would be sending Amazon Associates Web Service a request.

Although the preceding example is in the form you'd enter the request into a browser, it is difficult to read. For that reason, this guide would present the same request as follows:

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
Operation=ItemSearch&
AWSAccessKeyId=[Access Key ID]&
AssociateTag=[ID]&
SearchIndex=Apparel&
Keywords=Shirt

Part of every Amazon Associates Web Service request is the same, the other part of the request changes according to the parameters used in the request, as shown in the following figure.

The first two lines in the preceding example contain the endpoint, http://ecs.amazonaws.com/onca/xml, and the service name, AWSECommerceService.

Amazon hosts many web services in addition to Amazon Associates Web Service, including Mechanical Turk and S3. The service name in the request specifies that the request should be sent by the web servers to Amazon Associates Web Service. This line is always the same in every Amazon Associates Web Service request, regardless of locale:

Service=AWSECommerceService&

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 to use in Amazon Associates Web Service requests.

LocaleEndpoint
CA

http://ecs.amazonaws.ca/onca/xml

https://aws.amazonaws.ca/onca/xml

DE

http://ecs.amazonaws.de/onca/xml

https://aws.amazonaws.de/onca/xml

FR

http://ecs.amazonaws.fr/onca/xml

https://aws.amazonaws.fr/onca/xml

JP

http://ecs.amazonaws.jp/onca/xml

https://aws.amazonaws.jp/onca/xml

UK

http://ecs.amazonaws.co.uk/onca/xml

https://aws.amazonaws.co.uk/onca/xml

US

http://ecs.amazonaws.com/onca/xml

https://aws.amazonaws.com/onca/xml

The endpoint remains the same for all Amazon Associates Web Service requests, for example:

http://ecs.amazonaws.com/onca/xml

The third and fourth lines identify the request submitter. The AWSAcessKey Id is required; it helps identify the request submitter. You receive an AWS Access Key ID when you sign up with Amazon Associates Web Service.

Also included in every request is a signature. This is an SHA-1 encrypted value created using the developer's Secret Access Key, which given to every developer once they sign up to become an Associate. Because the AWS Access Key ID is sent in the clear, it cannot be used as the sole identity for authenticating the request. Instead, the AWS Access Key ID is used by the Amazon Associates Web Service to look up the Secret Access Key associated with it. If that value matches the one encrypted in the request's signature parameter, the request is processed.

The other identifier, AssociateTag, is optional. It is an ID for an Associate. If you are an Associate, you must include your Associate tag in each request to receive a referral fee for a customer's purchase.

The remaining terms in the request vary significantly according to the operation chosen. The terms, however, follow a pattern, as shown in the next figure.

The Operation parameter is required. Its value is one of the Amazon Associates Web Service operations. These operations are described throughout this guide and in the Amazon Associates Web Service API Reference Guide.

The last lines, operation parameters, are representative of parameters that the operation requires, and optional parameters that the operation can use. Requests can contain zero or more operation (up to ten) parameters. These parameters are described in the discussion of each operation in the Amazon Associates Web Service API Reference Guide.

A special parameter that is optional for all Amazon Associates Web Service operations is ResponseGroup. Response groups control the kind 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.

Besides these generic response groups, there are very specific ones. For example, if you want to return images of the items included in a response, you would include the Image response group in the request. If you wanted pricing information, you would include the Offer response group in the request. To get browsenode information, you'd include the BrowseNode response group. The specificity of the response groups enables you to return only the information you want.

Each Amazon Associates Web Service operation can only work with a subset of all Amazon Associates Web Service response groups. The valid response groups that each Amazon Associates Web Service operation can use is listed in the Amazon Associates Web Service API Reference Guide.

All Amazon Associates Web Service operations use some response group by default. So, specifying additional response groups is optional. Every Amazon Associates Web Service operation uses the Request response group, which echoes operation name and the input parameters sent in the request. The other response groups used by default vary by the operation. For example, CartCreate, CartAdd, and CartModify use, by default, the Cart response group, which provides detailed information about the items in a cart. The API Reference Guide lists the default response groups used by each operation.

Now, when you read requests in this guide, your eye should jump to the Operation parameter and all of the required and optional parameters associated with the specified Amazon Associates Web Service operation.

Some Amazon Associates Web Service operations have many parameters and, as you will learn in a future section, you can combine multiple single requests in one, longer batch request. The upper limit is bounded by the maximum number of characters that can be in a request. The maximum number differs by browser. For example, the limit for a URL in Microsoft's Internet Explorer is a little more than 2000 characters. It would be unusual to have a request that approached this upper boundary.

One of the values of using REST is that its syntax is simple, which makes REST requests easy to read. This section summarizes all of the REST syntax rules that you must keep in mind when creating a REST request.

Request parameter values are set using the format:

ParameterName=value

The following example is a parameter/value pair.

Operation=ItemSearch

Parameter values must be URL-encoded. There are some characters, such as an asterisk or space, that cannot go into a URL. There are equivalents of these characters that you use in requests instead. For example, the URL encoded equivalent of a space is %20. So, instead of writing Name=John Smith you would write Name=John%20Smith

The requests presented so far contain only one operation. Amazon Associates Web Services enables you to improve performance by submitting more than one request at the same time. There are three ways to do this:

  • Batch request—A request that uses one operation with up to two sets of parameters.

  • Multiple operations request—A request contains more than one operation. This kind of request can combine simple and batch requests.

  • Multiple ItemIds—In an ItemLookup request, you can include up to ten comma-separated values for ItemId.

There might be times when you want to use the same operation in two requests, each one using different input parameters. For example, you might want to run an ItemLookup request several times, each time looking up a different item. To accomplish this task, you can submit two requests or one batch request.

The following figure shows how two simple requests can be combined into one batch request.

The new syntax introduced in the batch request centers on the ways in which the operation parameters are defined. Either the parameter values are different or they are shared between the simple requests in the batch request.

Batch requests can contain up to two sets of parameters.

[Note]Note

The Amazon Associates Web Service supports ItemLookup batch requests only when the ItemType is an EAN (European Article Number), ISBN (International Standard Book Number), or ASIN (Amazon Standard Item Number ).

Amazon Associates Web Service operations use a variety of required and optional parameters. The API Reference Guide describes the parameters that each operation can use.

There are, however, a number of parameters that all operations can use. These parameters can be grouped into types.

The following sections describe these parameter types.

The parameters in the following table are required in every request.

ParameterValueDescription
Service AWSECommerceService Specifies the Amazon Associates Web Service service
AWSAccessKeyId Your Amazon-assigned Access Key ID To register for an Access Key ID from the Amazon Web site, go to http://aws.amazon.com. Every Amazon Associates Web Service 4.0 request must contain either an Access Key ID or a Subscription ID but not both.
SubscriptionId Your Amazon-assigned subscription ID Every Amazon Associates Web Service 4.0 request must contain either an Access Key ID or a Subscription ID but not both. Starting with version 2005-10-05, Amazon Associates Web Service stopped distributing Subscription IDs. If you already have one, it will continue to work.
OperationOperation you wish to perform, for example, ItemLookup One of the Amazon Associates Web Service operation types.

The parameters in the following table can be used optionally in any Amazon Associates Web Service request.

ParameterValueDescription
AssociateTagAn Amazon-assigned Associate ID The AssociateTag enables product URLs returned by Amazon Associates Web Service to be tagged as originating from your Associates Web site. To receive a referral credit for a sale, you must include an AssociateTag value in a CartCreate request. Be sure to specify the value correctly; no error is generated for incorrect values.
MerchantIdAn alphanumeric token assigned by Amazon to a merchant. MerchantId can have three settings: All, in which all merchants are included in the response, an alphanumeric identity that specifies a single merchant, or "FeaturedBuyBoxMerchant," which returns the merchant identified as the “Buy Box Winner” on a specific detail page. The "Buy Box Winner" is the merchant associated with the sale of the item listed in the Buy Box, which is the box on an item's detail page that enables you to add an item to a shopping cart. The default value for MerchantId is “Amazon.”
ResponseGroup VariousSpecifies what subset of data to return. The API Reference Guide specifies the response groups that can be used with each operation..
Version VariousVersion of the Amazon Associates Web Service 4.0 WSDL. The default is 2005-10-05. If you want another version, including the latest, you must specify it in your request.

If you are using an XSL stylesheet to specify the output returned by Amazon Associates Web Service, you may need to include some or all of the following (optional) parameters:

ParameterValueDescription
Style "XML", the default, or the URL of an XSL stylesheet The Style parameter applies to REST requests only. Use the Style parameter to control the format of the data returned by Amazon Associates Web Service. Set this parameter to "XML" to generate a pure XML response. Set this parameter to the URL of an XSL stylesheet to have Amazon Associates Web Service transform the XML response to another format you specify.
ContentType "text/xml", the default, or "text/html"The ContentType parameter is valid for REST requests only. The ContentType set in your request is returned as the content type in the HTTP headers of the response that Amazon Associates Web Service returns. Generally ContentType should only be changed when it is being used in conjunction with an XSLT stylesheet specified with the Style parameter. When you use a stylesheet to transform your Amazon Associates Web Service response to HTML, set this parameter to text/html.

For more information, go to Transforming Amazon Associates Web Service Responses into HTML Using XSLT

The only drawback of having so many items at your fingertips is the possibility of receiving too many in a response. Amazon Associates Web Service handles this problem in several ways:

  • Results are returned on page, generally, up to ten results per page

  • The Sort parameter orders results

It is possible to create a request that returns many thousands of items in a response. This is problematic for several reasons. Returning all of the item attributes for those items would dramatically impact the performance of Amazon Associates Web Service in a negative way. Also, posting a thousand responses on a web page is impractical.

For that reason, Amazon Associates Web Service developed the strategy of returning results a little at a time. The good news is that you can return any page of results. For example, the first request can return the last page of results. To do that, you have to specify the desired page of results using one of the parameters that enable you to return result pages.

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Keywords=Potter&
SearchIndex=Books&
ItemPage=4

The following snippet of the response shows that the fourth page of results has been returned.

<ItemSearchRequest>
  <ItemPage>4</ItemPage> 
  <Keywords>Potter</Keywords> 
  <SearchIndex>Books</SearchIndex> 
</ItemSearchRequest>
</Request>
<TotalResults>9729</TotalResults> <TotalPages>973</TotalPages> 

This example shows that 9729 items matched the search criteria. Also, it shows that those results are on 973 (~9729/10) pages. You might try putting in an ItemPage value over 400. If you do, Amazon Associates Web Service returns the following error:

<Error>
  <Code>AWS.ParameterOutOfRange</Code> 
  <Message>The value you specified for ItemPage is invalid. Valid values must be between 1 and 400.</Message> 
</Error>

So, how do you get that 973rd page? You cannot. A better approach is to submit a new request that is more targeted and yields fewer items in the response.

The following Amazon Associates Web Service operations have a Sort parameter that arranges results:

For example, the following request returns books with "Harry Potter" in their title or description in alphabetical order.

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=1MMR0DKBKVGCHE7TZBG2&
Operation=ItemSearch&
Keywords=Harry%20Potter&
SearchIndex=Books&
Sort=titlerank&
ItemPage=29&
Version=2006-09-13

A small snippet of the response shows that the book titles are returned in alphabetical order.

<Title>Aventuras de Harry Potter, Las</Title> 
...
<Title>Beacham's Sourcebook For Teaching Young Adult Fiction: Exploring Harry Potter</Title> 
...
<Title>Beatrix Potter to Harry Potter: Portraits of Children's Writers</Title> 

Amazon Associates Web Service provides many different sorting criteria, for example, price (high to low, or low to high), salesrank (best to worst selling, or worst to best selling), publication date, review rank, and release date. Valid sort parameters vary by search index, for example, the DigitalMusic search index can be sorted by UploadedDate. That value for Sort would not make sense in the Automotive search index, for example. Sort parameters also differ by locale.

For more information about sort values by locale and search index, see the appendix, ItemSearch Sort Values By Locale

Perhaps you want to use a different set of tags in Amazon Associates Web Service responses than those that are returned by default. For example, because you want to display responses on a web page, you want to turn the responses into HTML. You have two choices: you can receive the default Amazon Associates Web Service response and then transform it into HTML (or another set of XML tags) or you can tell Amazon Associates Web Service to do the transformation for you so that the result is ready for you to use. To make Amazon Associates Web Service do the work for you, you just need to reference an XSL stylesheet in your Amazon Associates Web Service request.

Amazon Associates Web Service provides an XSLT (Extensible Stylesheet Language Transformation) service to ensure that even novice developers can produce rich content without complex parsing or programming. XSL is an XML-based language for transforming XML tags into HTML or any other set of XML tags. To use the Amazon Associates Web Service XSLT service, the request must be in REST, and the XSL style sheet must be referenced using the Style input parameter.

To transform the response

  • Include the Style parameter in your request.

    The referenced stylesheet must be publically accessible.

For example, the following ItemSearch request specifies the XSLT stylesheet http://ecs.amazonaws.com/xsl/aws4/item-search.xsl.

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemLookup&
IdType=ASIN&
ItemId=B00008OE6I&
ResponseGroup=Large&
Style=http://ecs.amazonaws.com/xsl/aws4/item-search.xsl

It is beyond the scope of this book to explain in detail how to create an XSL style sheet. To see a sample style sheet, go to http://ecs.amazonaws.com/xsl/aws4/item-search.xsl .

You use "xmlns" to define a namespace prefix at the top of the style sheet. You may name the namespace prefix anything, however, the namespace URL must match the namespace URL that is returned in the Amazon Associates Web Service response. The preceding example uses "aws" as the namespace prefix, as follows:

xmlns:aws="http://xml.amazon.com/AWSECommerceService/2006-09-13">

Once you have created a namespace prefix, use it to match elements in the Amazon Associate Web Service response. For example, if you are trying to match an element called "ItemLookupResponse," and your prefix is "aws," the matching string would be aws:ItemLookupResponse.

The following example shows how and where the namespace prefix should be used.

<xsl:template match="/">
  <xsl:apply-templates select="aws:Items/aws:Item"/>
</xsl:template>
<xsl:template match="aws:Items/aws:Item">
  <tr>
    <td style="border-bottom:C0C0C0 dotted 1px;padding:10px">
      <table cellpadding="0" cellspacing="0" style="width: 90%;padding:5px">
        <tr>
          <xsl:if test="aws:SmallImage/aws:URL">
            <td valign="top" width="50">
              <img>
                <xsl:attribute name="src">
                  <xsl:value-of select="aws:SmallImage/aws:URL" />
                </xsl:attribute>
                <xsl:attribute name="border">0</xsl:attribute>
              </img>
            </td>
          </xsl:if>
          <td valign="top">
            <xsl:value-of select="aws:ItemAttributes/aws:Title" />
            <br />
            <span style="font-size:10px">
              <xsl:if test="aws:ItemAttributes/aws:Author">
                by <xsl:value-of select="aws:ItemAttributes/aws:Author" />
              </xsl:if>
              <xsl:if test="aws:ItemAttributes/aws:Artist">
                by <xsl:value-of select="aws:ItemAttributes/aws:Artist" />
              </xsl:if>
              <xsl:if test="aws:ItemAttributes/aws:Director">
                by <xsl:value-of select="aws:ItemAttributes/aws:Director" />
              </xsl:if>
              <xsl:if test="aws:ItemAttributes/aws:Composer">
                by <xsl:value-of select="aws:ItemAttributes/aws:Composer" />
              </xsl:if>
              <xsl:if test="aws:ItemAttributes/aws:Manufacturer">
                from <xsl:value-of select="aws:ItemAttributes/aws:Manufacturer" />
              </xsl:if>
            </span>
            <br />
            <br />
            <span style="font-size:11px;">
              List Price: <xsl:value-of
                select="aws:ItemAttributes/aws:ListPrice/aws:FormattedPrice" />
            </span>
          </td>
        </tr>
      </table>
    </td>
  </tr>
</xsl:template>