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

Paging and Sorting Through Responses

You can create a request that returns thousands of items in a response, but posting a large response on a web page is impractical. To avoid returning too many items in a response:

  • Results are returned per page, up to ten results per page. This limit cannot be increased.

  • The Sort parameter orders results.

Paging Through Results

To return specific page results at a time, specify the ItemPage parameter for ItemLookup or VariationPage for ItemLookup.

For example, the following ItemSearch request uses ItemPage to return the fourth page of results. Service=AWSECommerceService& AWSAccessKeyId=[AWS Access Key ID]& AssociateTag=[Associate ID]& Operation=ItemSearch& Keywords=Potter& SearchIndex=Books& ItemPage=4 &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]

The following response snippet shows the fourth page of results is returned.

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

You can return up to the maximum page results for each operation. See Maximum Number Of Returned Pages.

The previous example shows that 9729 items matched the search criteria and there are a total of 973 pages (~9729 / 10). If you enter a ItemPage value over 10, the Product Advertising API 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 10.</Message> </Error>

To avoid this error, submit a new request that is more targeted and returns fewer items in the response.

Maximum Number Of Returned Pages

The Product Advertising API has the following page result limits:

Operation Parameter Name Maximum Page Number
ItemLookup VariationPage 150
ItemSearch ItemPage 10

Sorting Results

The ItemSearch operation has a Sort parameter that arranges results.

To sort results

  1. Specify sort values for your locale. See Locale Reference for the Product Advertising API.

  2. Add the Sort parameter to a request that uses one of the previous operations.

For example, the following request returns books with "Harry Potter" in the title or description in alphabetical order. Service=AWSECommerceService& AWSAccessKeyId=[AWS Access Key ID]& AssociateTag=[Associate ID]& Operation=ItemSearch& Keywords=Harry%20Potter& SearchIndex=Books& Sort=titlerank& ItemPage=4& Version=2013-08-01 &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]

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>

Product Advertising API 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.

Available sort values vary by locale and search index. For example, the DigitalMusic search index can be sorted by UploadedDate. That same value will not make sense in the Automotive search index.

Default Sort Values

There are many sort values and the majority are not applied unless the Sort parameter is in the request. There are two sort values that are default.

  • For ItemSearch requests that do not use the BrowseNode parameter, results are sorted by Relevance.

  • For ItemSearch requests that do use the BrowseNode parameter, results are sorted by BestSeller ranking.