6.7 The RESTful Way: XML/HTTP

Amazon refers to its REST implementation as the XML/HTTP method. XML data using this method is simply a matter of hacking variables in a URL. The base URL always starts like this:

http://xml.amazon.com/onca/xml3?t=your associates ID

The URL points at a server specifically for serving up XML (xml.amazon.com), lets Amazon know which Web Services version you're requesting (xml3), and passes along your Amazon Associates ID Section 5.2 as a variable (t=yourassociatesID). There are also several other variables that can be (or must be) appended to this request as described in the following sections.

6.7.1 Required Variables

Each request requires these four variables:

t

As mentioned above, this is always set to your associates ID. It lets Amazon track purchases made through your applications and enables you to earn affiliate fees.

dev-t

This is set to your developer's token.

type

The only possible values for type are lite and heavy. It describes which XML format to return.

f

This is the format the data should be returned in, usually xml. It can also be set to the URL of an XSL stylesheet to return formatted HTML.

6.7.2 Search Variables

Beyond the four required variables, you can also choose variables from the list below to get the exact data you're looking for.

6.7.2.1 Product Searches

KeywordSearch

Searches for products by subject.

BrowseNodeSearch

Browses product area by code.

AsinSearch (+ offer, + offerpage)

Returns a specific product detail.

UpcSearch

Searches for UPC numbers. Music only. mode must be set to music.

AuthorSearch

Searches for authors and returns book product details.

ArtistSearch

Searches for musicians and returns CD product details.

ActorSearch

Searches for actors and returns DVD product details.

DirectorSearch

Searches for directors and returns DVD product details.

ManufacturerSearch

Searches for manufacturers.

6.7.2.2 Amazon Features Searches

ListManiaSearch

Finds lists by List IDs.

WishlistSearch

Finds wish lists by Wish List IDs.

SimilaritySearch

Finds similar products given an ASIN.

ExchangeSearch

Finds a given exchange.

SellerSearch (+ offerstatus)

Finds products given a Seller ID.

SellerProfile

Finds a seller's profile given a Seller ID.

6.7.2.3 Special Searches

PowerSearch

Searches using Amazon's Power Search syntax.

BlendedSearch

Searches product listings across all categories.

6.7.3 Support Variables

mode

Defines a specific area for different types of requests.

locale

Tells Amazon which international store to query. United Kingdom (uk), Japan (jp), and Germany (de) are the locales available at this time. You can also explicitly specify the default United States (us).

ct

Specifies an alternate content-type HTTP header.

6.7.4 Putting the URLs Together

Assembling a query URL is just a matter of filling in the proper values after the variables. If you're searching for all books associated with penguins, the following URL would do the trick:

http://xml.amazon.com/onca/xml3?t=insert associate tags [RETURN]
&dev-t=insert developer token &type=lite&f=xml&mode=books [RETURN]
&KeywordSearch=Penguin 

If, on the other hand, you're wondering about DVDs featuring Clint Eastwood, something like this would work:

http://xml.amazon.com/onca/xml3?t=insert associate tag [RETURN]
&dev-t=insert developer token &type=lite&f=xml&mode=dvd [RETURN]
&ActorSearch=Clint%20Eastwood 

To represent spaces in a URL, as in our query here for "Clint Eastwood", the spaces need to be encoded. The URL encoding for a space is %20. Many scripting environments offer built-in functions for URL encoding [Hack #92]. Other special characters like periods, exclamation points, or dollar signs also need to be encoded.