XML Reference Guide

Now that we know how to use Perl to create a SOAP client, let's talk about the data we ultimately want to retrieve. Amazon Web Services underwent some major changes when it became Amazon Electronic Commerce Services (ECS) 4.0. Multiple search types have been combined, and new capabilities, such as a slew of operations involving shopping carts, have been added, but the ultimate goal is the same: to provide a web services interface to all (or at least most) of the information you would normally find using the traditional Amazon interface.

In general, Amazon provides two types of requests: searches and lookups. Searches enable you to find items based on specific criteria. For example, you may do a search for books on Perl or customer reviews written by people named "Neilson". Amazon provides 4 searches:

CustomerContentSearch
ItemSearch
ListSearch
SellerListingSearch

Once you know what object you're looking for, you can get the appropriate information about it using a lookup. You pass the object's ID into the lookup operation, and the response contains the information about the object. Amazon provides 7 lookups:

BrowseNodeLookup
CustomerContentLookup
ItemLookup
SellerListingLookup
SellerLookup
SimilarityLookup
TransactionLookup

In previous incarnations of Amazon Web Services, you could choose how much data to return by choosing "Heavy" or "Lite" data. Now you can (and, in fact, must) be specific in the information you want returned by specifying the ResponseGroup. Available ResponseGroups include ItemIds, SalesRank and EditorialReview, as well as general groups such as Small, Medium and Large.

In our case, the goal is to pull information from a specific WishList, so the first thing we need to do is get the ListId. To do that, we could go ahead and do a ListSearch, but in the interest of space, we'll find it the easy way.

Go to Amazon.com and look up the WishList you want to display. The ListId is part of the URL. For example, my wish list is at

http://www.amazon.com/gp/registry/registry.html/102-9881941-7928904?%5Fencoding=UTF8&id=4M6WEGGRFLZO

Once we have the ListId, we're ready to look up the list itself. As part of the request, we'll need to pass the following parameters:

• Service: In this case, always AWSECommerceService. (Amazon provides other services, such as a reporting service for developers, but this is the main service.)
• SubscriptionID: This is your "developer taken" that authorizes you to make requests. If you don't already have one, you can get one at https://aws-portal.amazon.com/gp/aws/developer/registration/index.html/102-9881941-7928904.
• Operation: What it is you want to do. In this case, the operation is ListLookup.
• ListType: In our case, WishList. Other possible values are Listmania and WeddingRegistry.
• ListId: This is the ID we pulled out of the URL for our target WishList.
• ResponseGroup: The data we want returned. In this case, we're going to choose the Medium group, because it includes the URL for the item detail page and a link to the thumbnail image so we can display it on the page. (See the resources for more information on available ResponseGroup values.)
• AssociateTag: This is your id for the Amazon Associates program, which enables you to earn commisions on items your visitors buy. You can sign up for your own ID at http://associates.amazon.com. (Or if you don't want to, you're welcome to use mine, thevanguardsc-20. :-) )

Now, before we go ahead and build the SOAP request, we can check to make sure our parameters are going to give us what we want. Amazon ECS provides both a SOAP version and a REST version of their services. SOAP is what we've been using so far in this section and what we ultimately will use to get our results, but REST is a simple alternative we can use to check the query results before we get heavily into coding.

REST requests are simple GET requests, with all of the parameters encoded in the URL, as follows:

http://webservices.amazon.com/onca/xml?Service=AWSECommerceService&SubscriptionId=0NQJY4BXVZP3SFWWPZG2&Operation=ListLookup&ListType=WishList&ListId=4M6WEGGRFLZO&ResponseGroup=Medium&AssociateTag=thevanguardsc-20

If we call this URL from the browser, we can see the results:

<?xml version="1.0" encoding="UTF-8"?>
<ListLookupResponse xmlns="http://webservices.amazon.com/AWSECommerceService/2005-07-26">

  <OperationRequest>
    <HTTPHeaders>
      <Header Name="UserAgent" Value="Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.7.8) Gecko/20050511 Firefox/1.0.4"></Header>
    </HTTPHeaders>
    <RequestId>1S8ARRY1FF9NFE0PW3XY</RequestId>

    <Arguments>
      <Argument Name="Service" Value="AWSECommerceService"></Argument>
      <Argument Name="AssociateTag" Value="thevanguardsc-20"></Argument>
      <Argument Name="ListId" Value="4M6WEGGRFLZO"></Argument>
      <Argument Name="SubscriptionId" Value="0NQJY4BXVZP3SFWWPZG2"></Argument>

      <Argument Name="ResponseGroup" Value="Medium"></Argument>
      <Argument Name="ListType" Value="WishList"></Argument>
      <Argument Name="Operation" Value="ListLookup"></Argument>
    </Arguments>
    <RequestProcessingTime>0.486002922058105</RequestProcessingTime>

  </OperationRequest>
  <Lists>
    <Request>
      <IsValid>True</IsValid>
      <ListLookupRequest>

        <ListId>4M6WEGGRFLZO</ListId>
        <ListType>WishList</ListType>
        <ResponseGroup>Medium</ResponseGroup>
      </ListLookupRequest>

    </Request>
    <List>
      <ListItem>
        <Item>
          <ASIN>B000002ORP</ASIN>

          <DetailPageURL>http://www.amazon.com/exec/obidos/redirect?tag=thevanguardsc-20%26link_code=xm2%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=B000002ORP%2526tag=thevanguardsc-20%2526lcode=xm2%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B000002ORP%25253FSubscriptionId=0NQJY4BXVZP3SFWWPZG2%252526coliid=I2KFNPNVJ3FGZ2%252526colid=4M6WEGGRFLZO</DetailPageURL>
          <SalesRank>2742</SalesRank>
          <SmallImage>
            <URL>http://images.amazon.com/images/P/B000002ORP.01._SCTHUMBZZZ_.jpg</URL>

            <Height Units="pixels">74</Height>
            <Width Units="pixels">75</Width>
          </SmallImage>
          <MediumImage>
            <URL>http://images.amazon.com/images/P/B000002ORP.01._SCMZZZZZZZ_.jpg</URL>

            <Height Units="pixels">158</Height>
            <Width Units="pixels">160</Width>
          </MediumImage>
          <LargeImage>
            <URL>http://images.amazon.com/images/P/B000002ORP.01._SCLZZZZZZZ_.jpg</URL>

            <Height Units="pixels">300</Height>
            <Width Units="pixels">303</Width>
          </LargeImage>
          <ImageSets>
            <ImageSet Category="primary">

              <SmallImage>
                <URL>http://images.amazon.com/images/P/B000002ORP.01._SCTHUMBZZZ_.jpg</URL>
                <Height Units="pixels">74</Height>
                <Width Units="pixels">75</Width>

              </SmallImage>
              <MediumImage>
                 <URL>http://images.amazon.com/images/P/B000002ORP.01._SCMZZZZZZZ_.jpg</URL>
                 <Height Units="pixels">158</Height>
                 <Width Units="pixels">160</Width>

              </MediumImage>
              <LargeImage>
                 <URL>http://images.amazon.com/images/P/B000002ORP.01._SCLZZZZZZZ_.jpg</URL>
                 <Height Units="pixels">300</Height>
                 <Width Units="pixels">303</Width>

              </LargeImage>
            </ImageSet>
          </ImageSets>
          <ItemAttributes>
            <Artist>Andrew Lloyd Webber</Artist>

            <Artist>Tim Rice</Artist>
            <Artist>Patti LuPone</Artist>
            <Artist>Mandy Patinkin</Artist>
            <Binding>Audio CD</Binding>

            <EAN>0076731010724</EAN>
            <Format>Cast Recording</Format>
            <Label>Decca U.S.</Label>
            <ListPrice>

              <Amount>3598</Amount>
              <CurrencyCode>USD</CurrencyCode>
              <FormattedPrice>$35.98</FormattedPrice>
            </ListPrice>

            <NumberOfDiscs>2</NumberOfDiscs>
            <ProductGroup>Music</ProductGroup>
            <ReleaseDate>1990-10-25</ReleaseDate>
            <Title>Evita (1978 Original Broadway Cast)</Title>

            <UPC>076731010724</UPC>
          </ItemAttributes>
          <OfferSummary>
            <LowestNewPrice>
              <Amount>2529</Amount>

              <CurrencyCode>USD</CurrencyCode>
              <FormattedPrice>$25.29</FormattedPrice>
            </LowestNewPrice>
            <LowestUsedPrice>
              <Amount>899</Amount>

              <CurrencyCode>USD</CurrencyCode>
              <FormattedPrice>$8.99</FormattedPrice>
            </LowestUsedPrice>
            <LowestCollectiblePrice>
              <Amount>9999</Amount>

              <CurrencyCode>USD</CurrencyCode>
              <FormattedPrice>$99.99</FormattedPrice>
            </LowestCollectiblePrice>
            <TotalNew>25</TotalNew>

            <TotalUsed>18</TotalUsed>
            <TotalCollectible>1</TotalCollectible>
            <TotalRefurbished>0</TotalRefurbished>
          </OfferSummary>

          <EditorialReviews>
            <EditorialReview>
              <Source>Amazon.com essential recording</Source>
              <Content>&lt;I&gt;Evita&lt;/I&gt; was Andrew Lloyd Webber's last show with Tim Rice before he went on to projects with less interesting collaborators, so it's no surprise that it remains his most consistently involving and rewarding work. Loosely based on the life of Eva Peron, the charismatic wife of post-World War II Argentine president Juan Peron, Rice's compelling story of one woman's rise from poverty to power is complemented by Lloyd Webber's colorful music as propelled by vigorous Latin rhythms. The showstopper, of course, is "Don't Cry for Me, Argentina," but the score is full of gems, including "On This Night of a Thousand Stars," "Oh, What a Circus," and "Another Suitcase in Another Hall." Headlining the 1978 Broadway cast, Patti LuPone is fabulous in the title role, showcasing her big voice and brash egotism in the role she was born to play. Mandy Patinkin is Che, the Greek-chorus character commenting on and criticizing the Perons, and his tenor is sweet on the ballads and powerful on the driving numbers. LuPone and Patinkin made their names with &lt;I&gt;Evita&lt;/I&gt; (and took home well-deserved Tonys), but it's the third principal, Bob Gunton, who elevates this cast to the stratosphere. As Peron--a role often filled by a nonsinger--Gunton inflects his strong voice with both menace and sensitivity. Forget the movie; this is the definitive version of this score, and an essential cast recording. &lt;I&gt;--David Horiuchi&lt;/I&gt;</Content>

            </EditorialReview>
          </EditorialReviews>
        </Item>
      </ListItem>
      <ListItem>
        ...
      </ListItem>

    </List>
  </Lists>
</ListLookupResponse>

So now that we know our parameters are right, we can start building the request.

According to the WSDL file, available online at http://webservices.amazon.com/AWSECommerceService/AWSECommerceService.wsdl -- or see http://www.amazon.com/gp/aws/sdk/main.html/102-9881941-7928904?s=AWSEcommerceService&v=2005-07-26&p=ApiReference/ServiceVersioningArticle for WSDL files for non-US Amazon sites -- our request should look like this:

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/12/soap-envelope"> 
 <env:Header></env:Header>
<env:Body>
    <ListLookup xmlns="http://webservices.amazon.com/AWSECommerceService/2005-07-26">   
        <SubscriptionId>0NQJY4BXVZP3SFWWPZG2</SubscriptionId>

        <AssociateTag>thevanguardsc-20</AssociateTag>
        <Request>
            <ListId>4M6WEGGRFLZO</ListId>
            <ListType>Wishlist</ListType>

            <ResponseGroup>Medium</ResponseGroup>
        </Request>
    </ListLookup>
</env:Body>
</env:Envelope>

That means we need to build our client as follows:

#!/usr/local/bin/perl
use lib qw(/home/nicholaschase/www/cgi-bin/lib/5.6.1/i386-linux
/home/nicholaschase/www/cgi-bin/lib/site_perl/5.6.1);

use SOAP::Lite;

my $lookup = SOAP::Lite->uri('http://webservices.amazon.com/AWSECommerceService/2005-07-26')
                       ->proxy('http://soap.amazon.com/onca/soap?Service=AWSECommerceService');

my $SubscriptionIdElement = SOAP::Data->name('SubscriptionId')
                                      ->value('0NQJY4BXVZP3SFWWPZG2');
my $AssociateTagElement = SOAP::Data->name('AssociateTag')
                                    ->value('thevanguardsc-20');

my $ListIdElement = SOAP::Data->name('ListId')
                              ->value('4M6WEGGRFLZO');
my $ListTypeElement = SOAP::Data->name('ListType')
                                ->value('WishList');
my $ResponseGroupElement = SOAP::Data->name('ResponseGroup')
                                     ->value('Medium');

my $RequestElementType = SOAP::Data->value($ListIdElement, 
                                           $ListTypeElement, 
                                           $ResponseGroupElement);

my $RequestElement = SOAP::Data->name('Request')
                               ->value($RequestElementType);

my $ListLookupRequest = SOAP::Data->value($SubscriptionIdElement, 
                                          $RequestElement);

my $response =  $lookup->ListLookup($ListLookupRequest);

Just as we did before with our sample client, we first create the proxy, and then the the payload, or the actual data of the request. We can then feed that data to the ListLookup method to get a response.

Now, before we move on to analyize the response, I want to make it clear that you can use this algorithm to request any data from Amazon ECS. The only difference between this and a search for books on polar bears or a list of items in the user's cart is the parameters you feed to the request.

OK, so we've made the request, and (theoretically, at least) we've gotten back an XML document that includes a list of items in the specified WishList. We can extract the title, URL, and image information as follows:

...
my $ListLookupRequest = SOAP::Data->value($SubscriptionIdElement, $RequestElement);

my $response =  $lookup->ListLookup($ListLookupRequest);

print "RequestProcessingTime = ";
print $response->dataof('//RequestProcessingTime')->value;
print "\n";

    for my $item ($response->valueof('//Item')) {
      print "Title is ". $item->{ItemAttributes}->{Title} . "\n";
      print "Details at ". $item->{DetailPageURL} . "\n";
      print "Thumbnail at ". $item->{SmallImage}->{URL} . "\n";
      print "\n";
   }

First, to make things simple, we're using a simple XPath-like expression to get a reference to a particular element in the response, the RequestProcessingTime. (See the REST result for the entire document, minus the SOAP envelope.) We're feeding it to the dataof() method, which returns a SOAP::Data object. We can then request the value. We also have the option of using the valueof() method.

But it's next that things get interesting. There's only one RequestProcessingTime element, but there are multiple Item elements, and we want child elements of each one. First we create a for loop, assigning each of them to the $item variable. For each one, we can then choose a child object. For the DetailPageURL, we only have to go down one level, but for the Title and the image URL we have to get the child of the child object.

If we run the client from the command line, we should see a response something like this:

RequestProcessingTime = 0.53298807144165
Title is Evita (1978 Original Broadway Cast)
Details at http://www.amazon.com/exec/obidos/redirect?tag=ws%26link_code=sp1%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=B000002ORP%2526tag=ws%2526lcode=sp1%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B000002ORP%25253FSubscriptionId=0NQJY4BXVZP3SFWWPZG2%252526coliid=I2KFNPNVJ3FGZ2%252526colid=4M6WEGGRFLZO
Thumbnail at http://images.amazon.com/images/P/B000002ORP.01._SCTHUMBZZZ_.jpg

Title is Evita: The Complete Motion Picture Music Soundtrack
Details at http://www.amazon.com/exec/obidos/redirect?tag=ws%26link_code=sp1%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=B000002NAK%2526tag=ws%2526lcode=sp1%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B000002NAK%25253FSubscriptionId=0NQJY4BXVZP3SFWWPZG2%252526coliid=I257XFPXXVVTNY%252526colid=4M6WEGGRFLZO
Thumbnail at http://images.amazon.com/images/P/B000002NAK.01._SCTHUMBZZZ_.jpg

Title is Live From the Middle East
Details at http://www.amazon.com/exec/obidos/redirect?tag=ws%26link_code=sp1%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=B00000AFDX%2526tag=ws%2526lcode=sp1%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B00000AFDX%25253FSubscriptionId=0NQJY4BXVZP3SFWWPZG2%252526coliid=I1YDL10XU8078Y%252526colid=4M6WEGGRFLZO
Thumbnail at http://images.amazon.com/images/P/B00000AFDX.01._SCTHUMBZZZ_.jpg

Title is The Big Bing : Black Holes of Time Management, Gaseous Executive Bodies, Exploding Careers, and Other Theories on the Origins of the Business Universe
Details at http://www.amazon.com/exec/obidos/redirect?tag=ws%26link_code=sp1%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=0060529555%2526tag=ws%2526lcode=sp1%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/0060529555%25253FSubscriptionId=0NQJY4BXVZP3SFWWPZG2%252526coliid=IYQW0YERYWS0B%252526colid=4M6WEGGRFLZO
Thumbnail at http://images.amazon.com/images/P/0060529555.01._SCTHUMBZZZ_.jpg
...

Note that Amazon, like most services of this type, limits requests to 10 items. If we wanted, we could use the ProductPage parameter to request the next set of 10. We can specify a value from 1 to 30, giving us access to the first 300 items on the list. And in fact we'll do exactly that, when we modify the code to choose a single random item from the list, next.