chrismacpherson.com

September 04 2010

Problem

I really wanted to display some books that I've been reading and liked the idea of learning more about using web services. The Amazon generated links to their items include some nasty images and the formatting isn't that great so I decided to write a wrapper for the Associate Web Service to enable me to pull whichever bits and pieces I wanted for each item, be it the image or the price, description or size.

Design

To access the web services offered by Amazon you need to create an associate account which will provide you with an:

Associate Tag

This is a unique user-name you are assigned by amazon base upon your name. This is needed to identify you for commission on any sales made through your links.

Access Key Id

This is a 20 character long string used to identify your associate account.(I think is a public key which can be used along with a private version for other web service features not mentioned in this article).

These two bits of data need to be used in every request to the web service and so we'll need a backend control panel for storing them.

On the front-end, in the templates, the aim was to provide a simple EE tag pair which could be used to request individual items from the Amazon service. Inside the pair, each attribute of the Amazon item would be available as a variable. All items in the Amazon database have a unique Amazon Standard Identification Number which is used for the request, sometimes a specific Locale is also required in instances where the product is only available in a certain region, like a U.K format television for example. I decided it might also be useful to be able to set a default Locale for use in all item requests. These were the main components that would make up the tag along with 'Response Groups' below.

UPDATE: The new v1.1.0 version of this module allows you to enter multiple associate tags, one for each locale. This is needed because each different amazon associate scheme (one for each locale) is separate to the others and you will only get paid if you use the locale specific associate tag in the referrer link.

Response Groups

There is a large amount of data stored for each item in Amazon's database, but they have put in place a useful structure which allows the data to be reduced in to various sized groups to suit different needs. These groups are termed 'Response Groups'. For example if I only wanted to display a product image I could make a request for the Images response group, which would return (in an XML response) URI values for the various images related to the item in question. There are many response groups to choose from and writing code to parse them all seemed a bit too much for the moment so I chose to offer only the Small and Medium options. These are Parent groups which provide general info about products and each consist of multiple child response groups.

Example Code

Here is a simple example fetching the title of a book.

{exp:cjm_amazon:item asin="1857231384"}
    <p>{Title}</p>
{/exp:cjm_amazon:item}

In this example we want to display the product image as well so we need the Medium response group.

{exp:cjm_amazon:item asin="1857231384" response_group="Medium"}
    <p>{Title}</p>
    <img src="{SmallImageURL}" title="{Title}" />
{/exp:cjm_amazon:item}

If this book was only available in the UK then I'd also add the Locale.

UPDATE: You can also use the short name for each domain instead, i.e. 'uk' instead of '.co.uk' or 'us' for '.com'

{exp:cjm_amazon:item asin="1857231384" response_group="Medium" locale=".co.uk"}
    <p>{Title}</p>
    <img src="{SmallImageURL}" title="{Title}" />
{/exp:cjm_amazon:item}

Requirements

I thought about adding support for PHP4 but everyone should really be on PHP5 now, or ther hosting needs upgraded.

So you need PHP5 and for the remote connections PHP must have either "allow_url_fopen" switched on in the php.ini file or have Curl installed.

Download

CJM_amazon_1.1.0.zip

Download the code here and use it for yourself. Don't be afraid to make a small donation if you find this useful

This work is licenced under a Creative Commons Licence.