Using Amazon Web Services With PHP And SOAP (part 1) - Anatomy Class
( Page 4 of 9 )

Amazon has made a number of important method calls available in the AWS API - here's a brief list:

BrowseNodeSearchRequest() - retrieve a list of catalog items attached to a particular node in the Amazon database;

ASINSearchRequest() - retrieve detailed information for a given product code;

KeywordSearchRequest() - perform a keyword search on the Amazon database;

SellerSearchRequest() - perform a search for products listed by third-party sellers;

PowerSearchRequest() - perform an advanced search on the Amazon database;

SimilaritySearchRequest() - perform a search for similar items, given a specific product code.

Additionally, AWS includes methods to search for authors, actors, directors, artists, manufacturers, wish lists and user lists.

This might not seem like much to start with - but, as you'll see, looks are deceptive. Consider the following simple example, which provides a gentle introduction to the power of AWS:

<?php

// include class
include("nusoap.php");

// create a instance of the SOAP client object
// remember that this script is the client,
// accessing the web service provided by Amazon.com
$soapclient = new
soapclient("http://soap.amazon.com/schemas2/AmazonWebServices.wsdl",
true);

// uncomment the next line to see debug messages
// $soapclient->debug_flag = 1;

// create a proxy so that WSDL methods can be accessed directly
$proxy = $soapclient->getProxy();

// set up an array containing input parameters to be
// passed to the remote procedure
$params = array(
		    'browse_node' => 18,
		    'page'        => 1,
		    'mode'        => 'books',
		    'tag'         => 'melonfire-20',
		    'type'        => 'lite',
		    'devtag'      => 'YOUR-TOKEN-HERE'
);


// invoke the method 
$result = $proxy->BrowseNodeSearchRequest($params);

// print the results of the search
print_r($result);
?>

The first order of business is to include the SOAP class which contains all the methods needed to access SOAP services.

Now, in this SOAP universe, Amazon provides the SOAP server, and this PHP script works as the client. So, the next step is to instantiate this client, using the class constructs provided by NuSOAP.

<?php
// create a instance of the SOAP client object
// remember that this script is the client,
// accessing the web service provided by Amazon.com
$soapclient = new
soapclient("http://soap.amazon.com/schemas2/AmazonWebServices.wsdl",
true); ?>

The class constructor accepts a single parameter, which is the URL of the SOAP service to be accessed (this is sometimes referred to by geeks as the "endpoint"). In case you're wondering where I got this URL from - it's listed in the AWS documentation. So there!

In order to simplify usage of the AWS API, I've created a "proxy client", one which lets me directly invoke AWS methods, rather than passing them to the NuSOAP class' call() method.

<?php
// create a proxy so that WSDL methods can be accessed directly
$proxy = $soapclient->getProxy(); ?>

All that remains is to send a request to the SOAP server via this proxy,

<?php
// invoke the method 
$result = $proxy->BrowseNodeSearchRequest($params);
?>

and print the resulting output.

<?php
// print the results of the search
print_r($result);
?>

In this case, I'm calling the BrowseNodeSearchRequest() method on the AWS SOAP server, and passing it a list of arguments (this argument list is also documented in the AWS API). This argument list is stored in the $params array, which looks like this:

<?php
// set up an array containing input parameters to be
// passed to the remote procedure
$params = array(
		    'browse_node' => 18,
		    'page'        => 1,
		    'mode'        => 'books',
		    'tag'         => 'melonfire-20',
		    'type'        => 'lite',
		    'devtag'      => 'YOUR-TOKEN-HERE'
);
?>

Here's what those arguments mean:

1. The "browse_node" argument specifies the node to begin with in the catalog. This node ID can be obtained by visiting the Amazon.com Web site and looking at the URL for the section you're interested in browsing. For example, the URL

http://www.amazon.com/exec/obidos/tg/browse/-/18

points to the Mystery category in Amazon's bookstore and has node ID 18.

In case this seems like too much work, a list of the most popular node IDs is available in the AWS documentation.

2. The "page" argument specifies the page offset to display. AWS is currently hard-wired to display 10 items per page, so if you wanted to display items 11-20, you would need to set

'page' => 2

and so on.

3. The "mode" argument specifies the particular store to browse. As of this writing, AWS defines 16 stores, each with a unique "mode" identifier - here's a list of the ones I visit most often:

Books: 
'mode' => 'books'

Again, a complete list of stores is available in the AWS documentation.

4. The "tag" argument specifies your Amazon.com Associates ID, if you have one. In case you don't, and if you're serious about building an online store with AWS, I suggest you get one post-haste from http://associates.amazon.com/, since it entitles you to a commission on every purchase made via your site.

5. The "type" argument specifies the type of result set you would like. AWS gives you two choices - "lite", which contains basic product information, and "heavy", which contains detailed product information. I'll show you both in this article.

6. Finally, remember that developer token you got when you first registered for AWS? You need to specify it via the "devtag" argument in order to use AWS; if it isn't included in the argument list, AWS will deny you access.

If you take a look at the internals of the SOAP class, you'll see that the proxy uses the class' call() method and the arguments passed to it to generate a SOAP request, which looks something like this:

POST /onca/soap2 HTTP/1.0
User-Agent: NuSOAP/0.6.3
Host: soap.amazon.com
Content-Type: text/xml
Content-Length: 942
SOAPAction: "urn:PI/DevCentral/SoapService"

<?xml version="1.0" encoding="ISO-8859-1"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:si="http://soapinterop.org/xsd"
xmlns:typens="urn:PI/DevCentral/SoapService">
<SOAP-ENV:Body><typens:BrowseNodeSearchRequest>
<BrowseNodeSearchRequest xsi:type="typens:BrowseNodeRequest">
<browse_node xsi:type="xsd:string">18</browse_node><page
xsi:type="xsd:string">1</page><mode
xsi:type="xsd:string">books</mode><tag
xsi:type="xsd:string">melonfire-20</tag><type
xsi:type="xsd:string">lite</type><devtag
xsi:type="xsd:string">YOUR-TOKEN-HERE</devtag><sort
xsi:type="xsd:string">18</sort></BrowseNodeSearchRequest></typens:Browse>

</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This request packet is transmitted to the SOAP server using the POST method, and a server response packet is transmitted back to the client. Here's what one such packet might look like:

HTTP/1.1 200 OK
Date: Tue, 05 Nov 2002 15:38:54 GMT
Server: Stronghold/2.4.2 Apache/1.3.6 C2NetEU/2412 (Unix)
mod_fastcgi/2.2.10
Connection: close
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:amazon="urn:PI/DevCentral/SoapService">

<SOAP-ENV:Body>
<namesp44:BrowseNodeSearchRequestResponse
xmlns:namesp44="urn:PI/DevCentral/SoapService">

<return xsi:type="amazon:ProductInfo">
<TotalResults xsi:type="xsd:string">55656</TotalResults>
<Details SOAP-ENC:arrayType="amazon:Details[10]"
xsi:type="SOAP-ENC:Array"> <Details xsi:type="amazon:Details"><Url
xsi:type="xsd:string">http://www.amazon.com/exec/obidos/redirect?tag=mel
onfi
re-20%26creative=YOUR-TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN
/006
0092572</Url><Asin xsi:type="xsd:string">0060092572</Asin><ProductName
xsi:type="xsd:string">The Terminal Man</ProductName><Catalog
xsi:type="xsd:string">Book</Catalog><Authors
SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><Author
xsi:type="xsd:string">Michael Crichton</Author></Authors><ReleaseDate
xsi:type="xsd:string">05 November, 2002</ReleaseDate><Manufacturer
xsi:type="xsd:string">Avon</Manufacturer><ImageUrlSmall
xsi:type="xsd:string">http://images.amazon.com/images/P/0060092572.01.TH
UMBZ
ZZ.jpg</ImageUrlSmall><ImageUrlMedium
xsi:type="xsd:string">http://images.amazon.com/images/P/0060092572.01.MZ
ZZZZ
ZZ.jpg</ImageUrlMedium><ImageUrlLarge
xsi:type="xsd:string">http://images.amazon.com/images/P/0060092572.01.LZ
ZZZZ
ZZ.jpg</ImageUrlLarge><ListPrice
xsi:type="xsd:string">$7.99</ListPrice><OurPrice
xsi:type="xsd:string">$7.99</OurPrice><UsedPrice
xsi:type="xsd:string">$4.00</UsedPrice>

</Details>
<Details xsi:type="amazon:Details"><Url
xsi:type="xsd:string">http://www.amazon.com/exec/obidos/redirect?tag=mel
onfi
re-20%26creative=YOUR-TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN
/006
0505397</Url><Asin xsi:type="xsd:string">0060505397</Asin><ProductName
xsi:type="xsd:string">Bet Your Life</ProductName><Catalog
xsi:type="xsd:string">Book</Catalog><Authors
SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><Author
xsi:type="xsd:string">Richard Dooling</Author></Authors><ReleaseDate
xsi:type="xsd:string">05 November, 2002</ReleaseDate><Manufacturer
xsi:type="xsd:string">HarperCollins</Manufacturer><ImageUrlSmall
xsi:type="xsd:string">http://images.amazon.com/images/P/0060505397.01.TH
UMBZ
ZZ.jpg</ImageUrlSmall><ImageUrlMedium
xsi:type="xsd:string">http://images.amazon.com/images/P/0060505397.01.MZ
ZZZZ
ZZ.jpg</ImageUrlMedium><ImageUrlLarge
xsi:type="xsd:string">http://images.amazon.com/images/P/0060505397.01.LZ
ZZZZ
ZZ.jpg</ImageUrlLarge><ListPrice
xsi:type="xsd:string">$25.95</ListPrice><OurPrice
xsi:type="xsd:string">$18.17</OurPrice><UsedPrice
xsi:type="xsd:string">$12.98</UsedPrice>

</Details>

... and so on...

</Details>
</return>
</namesp44:BrowseNodeSearchRequestResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This response packet is decoded by the client into a native PHP structure, which can be used within the script. At the moment, all I'm doing is printing it - and here's what the output looks like:

Array
(
    [TotalResults] => 55656
    [Details] => Array
        (
            [0] => Array
                (
                    [Url] =>

http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=Y
OUR-
TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0060092572
                    [Asin] => 60092572
                    [ProductName] => The Terminal Man
                    [Catalog] => Book
                    [Authors] => Array
                        (
                            [0] => Michael Crichton
                        )

                    [ReleaseDate] => 05 November, 2002
                    [Manufacturer] => Avon
                    [ImageUrlSmall] =>
http://images.amazon.com/images/P/0060092572.01.THUMBZZZ.jpg
                    [ImageUrlMedium] =>

http://images.amazon.com/images/P/0060092572.01.MZZZZZZZ.jpg
                    [ImageUrlLarge] =>
http://images.amazon.com/images/P/0060092572.01.LZZZZZZZ.jpg
                    [ListPrice] => $7.99
                    [OurPrice] => $7.99
                    [UsedPrice] => $4.00
                )

            [1] => Array
                (
                    [Url] =>
http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=Y
OUR-
TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0060505397
                    [Asin] => 60505397
                    [ProductName] => Bet Your Life
                    [Catalog] => Book
                    [Authors] => Array
                        (
                            [0] => Richard Dooling
                        )

                    [ReleaseDate] => 05 November, 2002
                    [Manufacturer] => HarperCollins
                    [ImageUrlSmall] =>

http://images.amazon.com/images/P/0060505397.01.THUMBZZZ.jpg
                    [ImageUrlMedium] =>
http://images.amazon.com/images/P/0060505397.01.MZZZZZZZ.jpg
                    [ImageUrlLarge] =>
http://images.amazon.com/images/P/0060505397.01.LZZZZZZZ.jpg
                    [ListPrice] => $25.95
                    [OurPrice] => $18.17
                    [UsedPrice] => $12.98
                )

		... and so on ...

            [9] => Array
                (
                    [Url] =>
http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=Y
OUR-
TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0195122623
                    [Asin] => 195122623
                    [ProductName] => Arthur Conan Doyle: Beyond Baker
Street (Oxford Portraits Series)
                    [Catalog] => Book
                    [Authors] => Array
                        (
                            [0] => Janet B. Pascal
                        )

                    [ReleaseDate] => March, 2000
                    [Manufacturer] => Oxford Univ Pr Childrens Books
                    [ImageUrlSmall] =>

http://images.amazon.com/images/P/0195122623.01.THUMBZZZ.jpg
                    [ImageUrlMedium] =>
http://images.amazon.com/images/P/0195122623.01.MZZZZZZZ.jpg
                    [ImageUrlLarge] =>
http://images.amazon.com/images/P/0195122623.01.LZZZZZZZ.jpg
                    [ListPrice] => $24.00
                    [OurPrice] => $24.00
                    [UsedPrice] => $5.49
                )

        )

)

Obviously, this is not very useful - but we're just getting started. Flip the page, and I'll show you how to massage all this raw data into something a little less ugly.

>>> More PHP Articles          >>> More By icarus, (c) Melonfire