Combining Operations into a Single Request

Amazon E-Commerce Service (ECS) requires that you make only one request per second. To assist you with maximizing your results in a minimum number of requests, ECS provides two ways to combine requests:

1. Batch requests - multiple requests (currently limited to two) for the same operation can be combined in one request; for example, you might combine a search for books and a search for DVDs into a single request.

2. Multi-Operation requests - multiple different operations (currently limited to two) can be combined into a single request; for example, you might do a product lookup and search for products in a single request.

Note that errors in batch or multi-operation requests require special handling, as described below.

Batch Requests - Combining Two Sets of Parameters for One Operation

A batch request allows you to combine two requests (or sub-requests) for the same operation into one single request to ECS. Batch requests allow you to share parameters across each of the sub-requests, so that you do not have to include redundant parameters values in your sub-requests. For example, if you want to search for books and DVDs with titles containing "dog", you may include the Title parameter with the value of "dog" in the request's shared parameters and avoid repeating the parameter in both sub-requests.

To create a batch request:

1. Assemble the standard operation parameters: Service, Operation, SubscriptionId, AssociateTag (optional). For batch operations, these parameters are the same for both sub-operation requests.

2. Assemble the shared parameters. For example, if both requests were to search for books, then both might require the SearchIndex parameter to be set to Books.

3. Assemble the parameters specific to the first request. For example, building on the books search example, you could include the Author parameter and set it to "Larson".

4. Assemble the parameters specific to the second request. For example, you could include the Title parameter and set it to "Horton Hears".

Here's a REST request for the example described above:

US	http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[your subscription ID here] &Operation=ItemSearch &ItemSearch.Shared.SearchIndex=Books &ItemSearch.1.Author=Larson &ItemSearch.2.Title=Horton%20Hears
DE	http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[your subscription ID here] &Operation=ItemSearch &ItemSearch.Shared.SearchIndex=Books &ItemSearch.1.Author=Larson &ItemSearch.2.Title=Horton%20Hears
UK	http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[your subscription ID here] &Operation=ItemSearch &ItemSearch.Shared.SearchIndex=Books &ItemSearch.1.Author=Larson &ItemSearch.2.Title=Horton%20Hears
JP	http://webservices.amazon.jp/onca/xml?Service=AWSECommerceService &SubscriptionId=[your subscription ID here] &Operation=ItemSearch &ItemSearch.Shared.SearchIndex=Books &ItemSearch.1.Author=Larson &ItemSearch.2.Title=Horton%20Hears

See the following sections for more information about how to structure REST and SOAP requests.

Batch Requests in REST

For batch requests, REST parameter definitions have been extended as shown in the table below to permit the specification of the parameters for both operations.

Operation parameters for batch requests (REST)

For example, if you wanted to do two ItemLookup operations, one for an ASIN and another for a SKU, with the results formatted via the same XSL stylesheet, you might use the following parameters in a REST request:

Example of parameters for a batched request for ItemLookup

Batch Requests in SOAP

For SOAP batch operations are implemented by including a Request element for parameters that are specific to the first and second requests.

Shared parameters are contained inside a Shared element.

Multi-Operation Requests - Combining Two Different Operations in a Single Request

Multi-operation requests allow you to specify two different operations in a single request. It's important to note that the requests are accepted and executed in parallel and are not chained. More specifically, if the first request is a search, the results of the search cannot be fed into the second request.

Multi-Operation Requests in REST

For multi-operation requests, as for batch requests, REST parameter definitions have been extended to permit the specification of the parameters for both operations.

The types of operation required are specified as a comma-separated list to the Operation parameter:

Operation=Operation1,Operation2

For example,

Operation=ItemLookup,ListSearch 

would specify that the first operation was an ItemLookup and the second was a ListSearch.

You must specify the parameters for the first request in the form Operation1.1.parameter and for the second request in the form Operation2.1.parameter. For example, if the operations are

Operation=ItemLookup,ItemSearch 

then the parameters are specified as ItemLookup.1.parameter and ItemSearch.1.parameter.

For example, if you wanted to do an ItemLookup and a ListSearch operation, you might use the following parameters in a REST request:

Example of parameters for a multi-operation request for an ItemLookup and a ListSearch operations (REST)

Errors in Combined Requests

When two requests are combined in a single request, there can be two kinds of error:

Type of error	Result
Syntax error in the request (e.g., an invalid response group or a mis-spelled parameter)	The request will be rejected and neither operation will be completed.
Validly formed request that returns no data (e.g., a keyword is mis-spelled)	The return data will show the error block for the operation with the error and the return data for the other operation.