Making a "lite" request, an example of an ISBN search

About lite requests

Currently there are two ways to query Amazon Web Services:

• a lite request;
• and a heavy request.

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

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

• Artists of a CD or casset
• ASIN of a product
• Authors of a book
• Current Availability of a product
• Catalog of a product
• URLs of a Product's image
• List Price of a product
• Manufacturer of a product
• Amazon's Price for a product
• Product's name
• Release Date of a product to the market
• URL of the product's details page on Amazon
• Lowest Used Price at Amazon Marketplace. Note, however, that Third Party searches are not yet supported by amazOOP
• Merchant ID of a Third Party Seller

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

If you need more feel that you need more information on a product, you would have to make a heavy request, which is covered in the next document, but we suggest you read this document first.

About ISBNs

ISBN stands for International Standard Book Number. It is a unique ten digit number assigned to every printed book.

Amazon lets you search for books in its catalog using their ISBN, and returns information such as the name of the book, its author(s), a short description and other information such as price, etc.

In order to search for a book using its ISBN, you first need to find it. This can be done in several ways.

If you own a printed copy

If you own a printed copy of the book, all you have to do is turn it over. You will usually find a barcode like the one below with the book's ISBN written right above it.

If for some reason there was no barcode on the back of the book, you can always find the ISBN inside the book, within the first couple of pages, among the fine print that details copyright, etc.

If you DON'T own a printed copy

If you don't own a printed you copy, there are still several ways in which you can find a book's ISBN.

1. You can look for the book in a library or bookshop and follow the instructions above.
2. You can find the ISBN in Amazon's detail page under product details:
   
3. 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 ISBN, or ASIN, number is the 10-digit string that appears directly after "ASIN".
   As an example, the above books’s ISBN was 043935806X, so the address of its detail page would be:

   http://www.amazon.com/exec/obidos/ASIN/043935806X

Search for an ISBN at Amazon.com

Now that you have your ISBN, you can use Amazon Web Services to look for information about the book.

We will be using the ISBN from the example above, 043935806X, to illustrate a lite request to AWS. We will fetch the book's name, the name of its author and the book's price. We will also display a button to add the book to an Amazon.com cart.

Include amazOOP

The first thing to do when using amazOOP is to include the script into your file.

You do this by writing line below at the beginning of your document.

You’ll probably have to change this to a path in your directory structure.

<?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');

Query AWS

Next, in order to query AWS, you have to create a new AmazonQuery object:

setAmazoopConfig('address', 'cvswork', 'test');
 
// 2. Create new AmazonQuery
$aq = new AmazonQuery();

And now, we will use the liteQuery() function to query AWS. The signature of liteQuery() is:

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

As $keywords we will be using the book's ISBN, i.e. "043935806X", as $serachType we will be using "ISBN". 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 ISBN search, or an ASIN search.

// 3. Query Amazon for data:

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

Check for errors

Although amazOOP is capable of handling errors and tries to return a valid response in most cases, there are some cases where the error cannot be avoided, for example if you submitted an incorrect ISBN, or if the search you made did not return results.

Error checking is as easy as calling getErrorMessage(). If it returns false, no error was returned, otherwise it will return the error. The following will diplay an error if it is detected:

$queryResult = $aq->liteQuery("043935806X", "ISBN");
 
// 4. Check for errors
if( $error = $queryResult->getErrorMessage() )

Display information

Assuming no errors were detected on the last step, we will now display the information we received from Amazon.

We have chosen to use the product's small image as a link to the product details page at Amazon. For this we are using function getURL(), with parameters that specify what we want the link to look like:

As first parameter we specify we want the 'small' image to be used as link.

Next, specify additional arguments to be added to the <a> tag. In this case we want the link to open in a new window, therefore we add 'target="_blank"'.

Finally, we would like to align the image to the left, as well as to give it a border to indicate that it is a link. For this we add 'border="1" align="left"' to the <img> tag.

Note that we are surrounding our strings with single quotes (') because we use double quotes (") inside the string. If you wish to surround your strings with double quotes, you can either use single quotes for your HTML, or escape your double quotes, e.g.

$product->getURL("small", "target='_blank'", "border=\"1\" align=\"left\"")

Next we will display the product's name, which shouldn't pose any problem. However, note that when displaying the author's name, we have added a parameter, in order to show the name of only one author, instead of the author and illustrator that are returned by Amazon.

Finally we display the price offered by Amazon, the list price and the difference between them, as well as a button to add the product to your Amazon cart.

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 $product->getURL('small', 'target="_blank"', 'border="1" align="left"') . "<br>\n";
    echo $product->getProductName() . "<br>\n";
    echo "by " . $product->getAuthors(1) . "<br clear=\"left\">\n";
    echo "Our price: " . $product->getOurPrice() . "<br>\n";
    echo "List price: " . $product->getListPrice() . "<br>\n";
    echo "Savings: " . $product->getSavings() . "<br>\n";
    echo $product->buyNow() . "<br>\n";

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 book with ISBN 043935806X at Amazon.com
 
$queryResult = $aq->liteQuery("043935806X", "ISBN");
 
// 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 $product->getURL('small', 'target="_blank"', 'border="1" align="left"') . "<br>\n";
    echo $product->getProductName() . "<br>\n";
    echo "by " . $product->getAuthors(1) . "<br clear=\"left\">\n";
    echo "Our price: " . $product->getOurPrice() . "<br>\n";
    echo "List price: " . $product->getListPrice() . "<br>\n";
    echo "Savings: " . $product->getSavings() . "<br>\n";
    echo $product->buyNow() . "<br>\n";
}
 
?>

The interpreted result

And this is the interpreted result: