Blended searches, searching in all Amazon catalogs

About heavy requests

Currently there are two ways to query Amazon Web Services:

• a lite request;
• and a heavy request.

This document will focus on heavy requests, you should read the previous document for information on lite requests.

As of version 0.3RC1, this is a list of the information returned by a heavy request to AWS that is supported by amazOOP, additional to the information returned by a lite request:

• A list of ASINs for Accessories that go with the current product
• The appropriate Age Level (for toys)
• A List of Browse Nodes in which the current product is contained. Read the documentation of getBrowseNode() for more information on the format of browse nodes.
• A list of Directors for the DVD or video
• The Distributor of a film
• The Encoding of a DVD or video
• The ESRB Rating for a computer or video game. Read the documentation of getEsrbRating() for more information on ESRB ratings.
• A list of Features for the current product
• The book's ISBN.
• A list of Listmania! lists that contain the current product. Note, however, that Listmania! searches are not yet supported by amazOOP.
• The product's Medium (i.e. paperback, audio-CD, etc.)
• The MPAA Rating for a DVD or video. Read the documentation for getMpaaRating() for more information on MPAA ratings.
• The Manufacturer Product Number
• The products Medium in numerical form
• Computer of video game Platforms that support the product
• Amazon's editorial Review of the product
• The Publisher of a book
• Children books Reading Level
• Customer Reviews and ratings. Read the documentation of getCustomerReview() for more information about the format of customer reviews.
• Product sales ranking at Amazon
• List of ASINs for Similar products
• List of Actors and Actresses starring in a DVD or video
• Date on which a DVD or video was or will be realeased in the theatres
• Price of the same item, sold new by a Third Party seller. Note, however, that Third Party searches are not yet supported by amazOOP.
• Price of the same item, sold refurbished by a Third Party seller. Note, however, that Third Party searches are not yet supported by amazOOP.
• Price of the same item, sold as collectible by a Third Party seller. Note, however, that Third Party searches are not yet supported by amazOOP.
• List of Tracks of a CD
• UPC code of the product. Read the documentaion of getUPC() to learn which items return a UPC code.

We will use some of this information to illustrate a heavy request in this document, however, you should read the documentation for the HeavyDetails object to learn exactly what information is available and how it can be used.

About ASINs

Every unique product in Amazon.com's catalog has an "ASIN", which is short for "Amazon Standard Item Number". (For books, their ASIN is the same as their "International Standard Book Number", or "ISBN"). You can find a product's ASIN in one of two ways:

1. It should be listed in the fine print on a product's detail page.
2. Alternatively, you can look in the URL of that same detail page. In most cases, the format of the URL should start like this: http://www.amazon.com/exec/obidos/ASIN/nnnnnnnnnn/. The ASIN number is the 10-digit string that appears directly after "ASIN".
   As an example, the following product’s ASIN would be B00005JKZY:

   http://www.amazon.com/exec/obidos/ASIN/B00005JKZY

Search for an ASIN at Amazon.com

Now we will search for a DVD using its ASIN at Amazon.com. We will display information from the ASIN above, B00005JKZY.

As explained above, an ASIN and an ISBN are technically the same thing. Therfore, ASIN searches and ISBN searches are basically the same, except that ISBN searches only apply to books. That is why the example from the previous document is practically identical to the one in this document, so we explain the lines that concern the changes introduced by a heavy search in detail.

Querying AWS

This time, to query AWS, we will use the heavyQuery() function. The signature of heavyQuery() is:

ProductInfo|BlendedSearch heavyQuery( string $keywords, string $searchType, [string $mode = "books"], [string $locale = "us"], [integer $page = 1], [string $sort = "Bestselling"])

As $keywords we will be using the DVD's ASIN, i.e. "B00005JKZY", as $serachType we will be using "ASIN". We are querying Amazon.com for only one product, so we won't be needing the optional $locale paramter which is "us" by default, nor $page or $sort because we only expect one product to be returned. Also notice that the $mode parameter is not necessary when doing an ASIN search, as was said in the last document.

// 3. Query Amazon for data:

Note: heavyQuery() is only available as of version 0.3RC1 of amazOOP, before this, you should use the lower-level function query() to query AWS.

Once you have queried AWS you should, as in the previous example, check for errors before displaying the information obtained.

Displaying information

Having made a heavy request to AWS, we have a lot more information available now that in the previous example. We will choose some of the available methods to illustrate what can be done with this information.

First, we will display the director's name. We do this by using method getDirectors(), which shouldn't pose any problems. Nor should getMpaaRating(), which is used to display the MPAA's rating for this movie.

else{
 
    // 5. Display the data you got from Amazon. No need for a loop here
//    we know only one result will be returned.
    
    $product = $queryResult->getDetails();
    echo "<p>" . $product->getURL('small') . "<br>\n";
    echo $product->getProductName() . "<br>\n";
    echo "directed by " . $product->getDirectors() . "</p>\n";
    echo "<p><b>Our price: </b>" . $product->getOurPrice() . "<br>\n";
    echo "<b>List price: </b>" . $product->getListPrice() . "<br>\n";

Looping through information

Heavy queries introduce a couple of more advanced methods, such as getFeatures() or getCustomerReview(), which allow access to items stored in lists. You can either access this items manually, by specifying explicitly which item of the list you want, or, what you probably want to do, you can iterate through the list to display the information in it.

Displaying all results

First we will explain how we are showing the features returned for this DVD by AWS. We did this by using method getFeatures() and a for loop, as shown below:

echo "<p><b>Rated: </b>" . $product->getMpaaRating() . "</p>\n";
    echo "<p><b>Features:</b><br>\n";

As you can see, we start the iteration at $i = 1, because calling getFeatures(0) returns a random feature and not the first feature in the list. Next, we know that getFeatures() will return false if the requested feature does not exist. Therefore, we will use that as a condition to stop. Finally, we increment $i and display the feature (which was assigned to $feature in the for loop).

If an assignment inside the for loop confuses you, you can also use the following syntax:

for($i = 1; $product->getFeatures($i); $i++)
    echo " - " . $product->getFeatures($i) . "<br>\n";

Displaying partial results

Now we will display Amazon's Editorial Review for this item using method getProductDescription():

echo " - " . $feature . "<br>\n";
    echo "</p>\n";

But there is nothing special to this. What is interesting is how we are going to display Customer Reviews of this product.

Because displaying all three available reviews completely, would make this document extremely long, we will first limit the number of review to two, and then we will limit these reviews to 100 words.

echo $product->getProductDescription(100, "... (continues...)") . "</p>\n";
    echo "<p><b>Customer Reviews</b><br>\n";
    for($i = 1; ($review = $product->getCustomerReview($i)) && $i <= 2; $i++){
        echo "<p>" . $review->getRating() . " stars. <b>" . $review->getSummary() . "</b><br>\n";

As you can see, we can limit the number of results by adding a stopping condition to the for loop. Here, we are limiting results by adding && $i <= 2

echo $product->getProductDescription(100, "... (continues...)") . "</p>\n";

We assign each review to variable $review, which is then used to retrieve the customer's rating (with getRating()), a summary of the review (with getSummary()), and finally, the first 100 words of the review calling getReview() with certain parameters. You should read the documentation of getReview() to understand which parameters were used.

The complete example

This is the source for the complete example, which should run if you modify line 5 to point to the actual path of aq.php:

<?php
 
// 1. Include AmazOOP in your page
// You may need to change this to the actual physical path to the file
 
require_once('../aq.php');
 
setAmazoopConfig('address', 'cvswork', 'test');
 
// 2. Create new AmazonQuery
$aq = new AmazonQuery();
 
 
// 3. Query Amazon for data:
// We will request the item with ASIN B00005JKZY at Amazon.com
 
$queryResult = $aq->heavyQuery("B00005JKZY", "ASIN");
 
// 4. Check for errors
if( $error = $queryResult->getErrorMessage() )
  echo "It looks like there's an error: " . $error;
 
// If everything's alright
else{
 
    // 5. Display the data you got from Amazon. No need for a loop here
//    we know only one result will be returned.
    
    $product = $queryResult->getDetails();
    echo "<p>" . $product->getURL('small') . "<br>\n";
    echo $product->getProductName() . "<br>\n";
    echo "directed by " . $product->getDirectors() . "</p>\n";
    echo "<p><b>Our price: </b>" . $product->getOurPrice() . "<br>\n";
    echo "<b>List price: </b>" . $product->getListPrice() . "<br>\n";
    echo "<b>Savings: </b>" . $product->getSavings() . "</p>\n";
    echo "<p><b>Rated: </b>" . $product->getMpaaRating() . "</p>\n";
    echo "<p><b>Features:</b><br>\n";
    for($i = 1; $feature = $product->getFeatures($i); $i++)
        echo " - " . $feature . "<br>\n";
    echo "</p>\n";
    echo "<p><b>Editorial review</b><br>\n";
    echo $product->getProductDescription(100, "... (continues...)") . "</p>\n";
    echo "<p><b>Customer Reviews</b><br>\n";
    for($i = 1; ($review = $product->getCustomerReview($i)) && $i <= 2; $i++){
        echo "<p>" . $review->getRating() . " stars. <b>" . $review->getSummary() . "</b><br>\n";
        echo $review->getReview(100, "... (continues...)") . "</p>\n";
    }
    echo $product->buyNow() . "<br>\n";
}
 
?>

The interpreted result

And this is the interpreted result:

The Lord of the Rings - The Return of the King (Widescreen Edition)
directed by Peter Jackson

Our price: $17.97
List price: $29.95
Savings: $11.98

Rated: PG-13 (Parental Guidance Suggested)

Features:
- Color
- Closed-captioned
- Widescreen

Editorial review
With The Return of the King, the greatest fantasy epic in film history draws to a grand and glorious conclusion. Director Peter Jackson's awe-inspiring adaptation of the Tolkien classic The Lord of the Rings could never fully satisfy those who remain exclusively loyal to Tolkien's expansive literature, but as a showcase for physical and technical craftsmanship it is unsurpassed in pure scale and ambition, setting milestone after cinematic milestone as the brave yet charmingly innocent Hobbit Frodo (Elijah Wood) continues his mission to Mordor, where he is destined to destroy the soul-corrupting One Ring of Power in the molten lava... (continues...)

Customer Reviews

5 stars. A Masterpiece
...wow. That's all I can really say for this film. It was inspirational, beautiful, heartrenching, and captivating, making this film amazing. Jackson truly outdid himself for Return of the King. The hopelessness and pain Sam and Frodo are experiencing as they struggle to destroy the Ring is so wonderfully done that you truly feel as if you are with Sam and Frodo as they struggle to climb up the mountain. The love and friendship between the two is so moving that it seriously brought tears to my eyes, and I *rarely* cry.

The acting was simply superb in this film,... (continues...)

5 stars. The best of them all!
I was crying when the movie ended and for so many reasons. This movie is easily the greatest and most powerful of the three movies in Peter Jackson's future classic legacy "Lord Of The Rings" and will go down into the same category as "Wizard Of Oz", "The Godfather" and "Citizen Kane" as one of the greatest movies that has ever been made.

Perfectly picking up where "The Two Towers" left off, Frodo, Sam and Gollum are approaching ever closer to Mt. Doom in Mordor but Frodo is falling further and further into despair as the power of the... (continues...)