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:


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.


This is set to your developer's token.


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


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. Product Searches

Searches for products by subject.


Browses product area by code.

AsinSearch (+ offer, + offerpage)

Returns a specific product detail.


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


Searches for authors and returns book product details.


Searches for musicians and returns CD product details.


Searches for actors and returns DVD product details.


Searches for directors and returns DVD product details.


Searches for manufacturers. Amazon Features Searches

Finds lists by List IDs.


Finds wish lists by Wish List IDs.


Finds similar products given an ASIN.


Finds a given exchange.

SellerSearch (+ offerstatus)

Finds products given a Seller ID.


Finds a seller's profile given a Seller ID. Special Searches

Searches using Amazon's Power Search syntax.


Searches product listings across all categories.

6.7.3 Support Variables


Defines a specific area for different types of requests.


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).


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]

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]

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.