A Conceptual Overview of the Amazon E-Commerce Service (ECS) Data Model

There are two types of data available through ECS:

  1. Amazon product data. The bulk of the Amazon catalog of products is available through ECS. There are three ways to consider the Amazon product data as returned by ECS.

    1. The Offers Model. Amazon's Web sites carry products from many vendors. A given product may be available through more than one vendor, on different terms and conditions, at a different price and in a different condition (new, used, etc.). If you are interested in offering Amazon products for sale, you must work with these product offers to get current price and availability.

      Image: ECS offers data model

    2. The Variations Model. Some products such as apparel and sporting goods are not available in a single version. For these products, you must specify other variation values such as size and color before purchasing the product. If you wish to work with multi-version products, you must be able to extract variation information from ECS.

      ASINs can be related in parent-child associations. For example, "Shoe" can be the parent ASIN of "Men's Shoes" and "Women's Shoes." In general, parent ASINs are abstractions, such as Shoe, Car, Shirt, and Book. Child ASINs are specific instances of the parent ASINs, for example, a blue shirt, size Large, sold by Eddy Bauer. Because parent ASINs are abstractions, the do not contain offers and often are not associated with images. It is therefore possible to do an ItemSearch and get zero TotalItems yet also have in the response a list of items. Zero is returned because the ASIN happened to be a parent ASIN that does not include offers. The items included in the response are, instead, associated with its child ASINs.

      Image: ECS variations data model

    3. Item Images and Attributes. Every product in ECS consists of images of the product as well as a set of attributes, which varies by product type. ECS has over 200 different attribute fields to completely describe items in each product line.

  2. Other data. ECS provides access to other data that is adjunct to the product catalog. Through ECS, you can retrieve individual wish lists and listmania lists as well as basic public information about customers. You can also access seller product listings and customer feedback about individual sellers.

Browse Nodes

Amazon uses a hierarchy of nodes to organize its items for sale. Each node can be either a parent or leaf node. A parent node has one or more child nodes; a leaf node does not.

The nodes progress from general to specific, for example, a top level browse node might be "Shoes." It's child browse nodes might be "Men's Shoes," "Women's Shoes," and "Children's Shoes." The Women's Shoes node might have the following children: "Boots," "Sneakers," "Heels," and "Slippers." As you can see from this example, the different levels of the hierarchical tree of nodes provides an organizational principle that can be used to catalog and find items. Navigating down the tree refines the search for items from the general to the specific. Navigating up the tree searches for the root browse node, or product category, of a browse node.

Browse Node Properties

Browse nodes have the following prooperties:

For example, the following XML response shows a browse node whose ID is 163357 and name is "Comedy."

<BrowseNode>
  <BrowseNodeId>163357</BrowseNodeId>
  <Name>Comedy</Name>
  <Children>
    <BrowseNode>
      <BrowseNodeId>599826</BrowseNodeId>
      <Name>Boxed Sets</Name>
    </BrowseNode>
    <BrowseNode>
      <BrowseNodeId>538712</BrowseNodeId>
      <Name>African American Comedy</Name>
    </BrowseNode>
  </Children>
  <Item>
    <Ancestors>
      <BrowseNode>
        <BrowseNodeId>549726</BrowseNodeId>
        <Name>Performing Arts</Name>
      </BrowseNode>
    </Ancestors>
  </Item>

In this example, the Comedy browse node has two child browse nodes, "Boxed Sets" and "African American Comedy," and one parent node, "Performing Arts."

Browse Nodes and Items

Browse nodes are categories into which items for sale are organized. A single node might have many items associated with it. In the above example, the child node, "Boxed Sets," might have the items "Abott and Costell Collection," and "Laurel and Hardy Collection" associated with it.

The number of items associated with a browse node can change radically over time as items are added for sale, or as items go out of stock and are no longer sold. For example, for the browse node, TopSellers, items are attached and unattached according to their sales.

Even browse nodes themselves are created and delted as items demand. When, for example, a new toy starts selling briskly, there may not be a node that appropriately categorizes the toy. In that case, a node would be created and the toy would be associated with the node. Then, if the sale of the toy died out, the node might be deleted. Other nodes are much longer lived. Top level nodes, for example, "Books" and "Apparel," have remained unchanged for years. So are the browse nodes associated with cities:

City Browse Node
Boston 917982
Chicago 917984
New York 917976
San Francisco 917980
Seattle 917978
Washington, D.C. 917986

Some nodes, however, are volitile by nature. For example, the items associated with the browse node, "Top Sellers," change frequently according to sales figures.

Many items can be associated with a single browse node. It is also the case that a single item can belong to many browse nodes. For example, a Harry Potter book might belong to the browse nodes "Children's Books," and "Top Sellers."

Browse Node Numbers

Amazon uses over 120,000 browse node IDs in the US locale alone. Browse node IDs are unique to their locale, that is, the same browse node ID might be used in two different locales but the names and purposes of those browse nodes might be unrelated. A list of some Amazon browse nodes are included in <ulink url="ApiReference/BrowseNodeValuesArticle">Browse Node Values by Locale</ulink>.

Browse node numbers are assigned internally by Amazon. There are no general rules for number assignments. You cannot assume, for example, that all IDs in the 2000's are related in any way.

If you have a browse node ID, you can see what group of items it represents by putting the ID into one of the following URLs:

Finding Browse Nodes

ECS offers several means of finding browse node numbers:

For example, the following response snippet was derived from the BrowseNodeInfo response group.

<BrowseNodes>
  <BrowseNode>
    <BrowseNodeId>4229</BrowseNodeId>
    <Name>Gastronomy</Name>
    <Children>
      <BrowseNode>
        <BrowseNodeId>4230</BrowseNodeId>
        <Name>Essays</Name>
      </BrowseNode>
      <BrowseNode>
        <BrowseNodeId>4231</BrowseNodeId>
        <Name>General</Name>
      </BrowseNode>
    </Children>
  </BrowseNode>
</BrowseNodes>

Finding Items Using Browse Nodes

To find items using the browsenode hierarchy, you start with a parent browse node and traverse down the hierarchical tree until you reach the layer of detail you need to find the items you want. For example, you might start at the browse node, "Shoes," and traverse down the tree to "Men's Shoes," and then to "Sneakers" to find men's sneakers for sale on Amazon.

Alternately, you might start with a browse node and traverse up the tree to find, for example, the general product category of the browse node.

You traverse the browse node tree using BrowseNodeLookup and the resonse group, BrowseNodeInfo. This response group returns both child and parents of the browse node specified in the request, as shown in the following snippet of the XML response to such a request.

Sample Response Snippet)

The following code is a snippet from the full resonse. 

<BrowseNode>
  <BrowseNodeId>9</BrowseNodeId> 
  <Name>History</Name> 
  <Children>
    <BrowseNode>
      <BrowseNodeId>4762</BrowseNodeId> 
      <Name>Africa</Name> 
      </BrowseNode>
    <BrowseNode>
    <BrowseNodeId>5032</BrowseNodeId> 
      <Name>Russia</Name> 
      </BrowseNode>
    <BrowseNode>
    <BrowseNodeId>4853</BrowseNodeId> 
      <Name>United States</Name> 
    </BrowseNode>
    <BrowseNode>
      <BrowseNodeId>5035</BrowseNodeId> 
      <Name>World</Name> 
    </BrowseNode>
  </Children>
  <Ancestors>
    <BrowseNode>
      <BrowseNodeId>1000</BrowseNodeId> 
      <Name>Subjects</Name> 
      <Ancestors>
       <BrowseNode>
        <BrowseNodeId>283155</BrowseNodeId> 
        <Name>Books</Name>
      </BrowseNode>
    </Ancestors>
  </BrowseNode>
</Ancestors>
</BrowseNode>
</BrowseNodes>

The response returns both the browse node's name and ID for each of the child and parent browse nodes. You can find the child or parent browse node of interest by looking through the browse node names and then use its browse node number in a new BrowseNodeLookup request.

Refining Searches Using Browse Nodes

ItemSearch bases its searches on a search index, such as Books, Apparel, or Automobile. The number of items within each search index, however, is typically very large. Even using other parameters, such as Keywords to filter out unwanted responses, the number of responses can still be quite high.

Another approach is to use browse nodes. Each search index is the root browse node for, often, hundreds or thousands of browse nodes. For example, under Books, there might be the following lineage of browse nodes: Books>Science Fiction and Fantasy>Novels By Isaac Asimov. As you can see, searching for items associated with the lowest browse node yields much more targeted responses than searching for all of the items associated with a root browse node.

To use browse nodes to yield more highly targeted responses, you use the BrowseNode parameter in ItemSearch. For example, 

http://webservices.amazon.com/onca/xml?     
Service=AWSECommerceService&  
AWSAccessKeyId=[Access Key ID]& 
Operation=ItemSearch& 
MerchantId=All& 
Condition=All& 
BrowseNode=3D502394& 
SearchIndex=Electronics& 
Keywords=Canon