Working with the XML Data Output from Amazon E-Commerce Service (ECS)

Data returned by ECS is structured as an XML-formatted data stream. This portion of the documentation describes the XML tags that are used to implement the conceptual data structures.

Throughout this documentation, we will be using XPath notation to specify XML elements and structures.

The data returned by ECS depends on what has been input into the Amazon catalog. As with any database, the contents vary depending on what was available when the data was created and by locale. Rare fields are not documented but may appear and occasionally some expected elements may be missing from the returned data.

The Common Structure for all Returned XML

Every XML response block generated by ECS looks something like this:

<?xml version="1.0" encoding="UTF-8">
<ItemLookupResponse xmlns="http://webservices.amazon.com/AWSECommerceService/2004-03-19">
  <OperationRequest>
    ... XML header and HTTP request information
  </OperationRequest>
  <Items>
    ... XML data here
  </Items>
</ItemLookupResponse>

where the root tag corresponds to the ECS operation requested, the OperationRequest tag is standard to all operations, and the Items tag is a block of XML which varies for each operation, and contains the requested data.

The OperationRequest block contains the following:

			Description
OperationRequest/
	HTTPHeaders/
		Header	HTTP header information (usually not used by the developer).
	RequestId		Unique ID for this operation request. Sometimes requested by ECS support staff for help with debugging.
	RequestProcessingTime		An indicator of the time (in seconds) it took the Web service to process the request. This does not include the time it took the message to travel through the Internet, so long response times may be due to increased Internet traffic.
	Arguments/
		Argument	One instance for each argument on the HTTP command line.

In the example above, an ItemLookup request has returned an ItemLookupResponse which contains an Items block containing the requested data. Each type of operation returns different data, so the Items block is replaced by a block of XML appropriate to the requested operation. The table below lists the root tags and the tag for the block of data returned with the XML operation.

The root tag contains an <OperationRequest> block PLUS one of the second level content elements listed in the table below. (Note that for batch requests, there may be more instances of the second level block up to the number of requests, currently a maximum of two.)

ECS Operation	Root tag of the XML Output	Content Element
ItemSearch	<ItemSearchResponse>	<Items>
ItemLookup	<ItemLookupResponse>	<Items>
SellerLookup	<SellerLookupResponse>	<Sellers>
Help	<HelpResponse>	<Information>
CustomerContentSearch	<CustomerContentSearchResponse>	<Customers>
CustomerContentLookup	<CustomerContentLookupResponse>	<Customers>
SimilarityLookup	<SimilarityLookupResponse>	<Items>
ListLookup	<ListLookupResponse>	<Lists>
ListSearch	<ListSearchResponse>	<Lists>
CartCreate	<CartCreateResponse>	<Cart>
CartAdd	<CartAddResponse>	<Cart>
CartModify	<CartModifyResponse>	<Cart>
CartClear	<CartClearResponse>	<Cart>
CartGet	<CartGetResponse>	<Cart>
SellerListingSearch	<SellerListingSearchResponse>	<SellerListings>
SellerListingLookup	<SellerListingLookupResponse>	<SellerListings>
TransactionLookup	<TransactionLookupResponse>	<Transactions>
MultiOperation	<MultiOperationResponse>	Series of what would normally be request root blocks, one per request, nested within the <MultiOperationResponse>; e.g. <ItemSearchResponse>, <CartCreateResponse>, etc. In this situation, the operation response blocks do not contain an additional <OperationRequest>.

XML Tags for ECS Data

Within the root element, the child data elements available through ECS consists of:

• Product data - includes descriptive information (attributes), product variations and pricing information (offer listings and offers)

• Other data - includes customer information like lists and seller information such as zShops listings and seller feedback

The ECS documentation describes most comprehensive XML structure that may be returned. However the returned data is limited and controlled in a variety of ways by your requests.

Errors

Errors generate an <Errors> block in the output XML. Its format is:

Structure of an <Errors> XML BLock