Associate Engine : Script Parameters
Home > Associate Engine > Documentation > Script Parameters   Updated: 17-Apr-2008

Script Parameters

Before reading this section, we recommend that you start with the Quick Tutorial of Parameters.

GET & POST Methods

The Associate Engine script can be called either via a link or via a form. Specifically, parameters can be passed to the script via the GET method or the POST method.

---

GET Method (Links or Forms)

The GET method means that you can put the parameters into the URL of a clickable link, such as:

Associate Engine uses the internet's standard way of specifying parameters. That is, each parameter is a NAME=VALUE pair and pairs are separated by the & symbol.

Note: If the NAME is specified without a value (e.g.: /cgi-bin/ae.pl?script&type=best&mode=books), then the value defaults to 1 thus script=1 can be abbreviated to script

---

POST Method (Forms)

The POST method is used in forms (note: the GET method can also be used in forms).

Set the ACTION of your form to be the URL of ae.pl on your webserver, e.g.: <FORM ACTION="/cgi-bin/ae.pl" METHOD="POST">

Form fields are used to specify the parameters. Hidden form fields can be used to specify parameters that you don't want the user to be able to change. For example, the following form does a search of DVD's for the user-specified keywords:

<FORM ACTION="/cgi-bin/ae.pl" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="mode" VALUE="dvd"> <INPUT TYPE="TEXT" NAME="keyword"> <INPUT TYPE="SUBMIT" VALUE="Search"> </FORM>

Note:If you want the user to be able to bookmark the results page that appears when they submit the form, then change the <FORM> and use METHOD="GET" instead. Web browsers cannot properly bookmark any webpage that was reached from a form that has METHOD="POST" since the resulting URL in the web browser's Location box does not contain any parameters (i.e.: it has no ?PARAMETERS).

Search-Related Parameters

Several types of searches are supported. The type of search to perform is specified by what parameter is used (described below). There are also optional parameters can be used to modify the search, such as what page to start at, how to sort the results, and what price range to filter on.

---

amazon.com Sections

Most search types (not all) require you to specify what product section of amazon.com to search in, such as the Books section, the DVD section, the Toys section, etc. The mode parameter is used to specify the product section. Its possible values are:

Thus mode=books causes the Books section to be searched.

Some sections are combinations of other smaller sections so you can search multiple sections all at once. For example, video is a combation of the dvd and vhs sections. The combinations are:

Combined mode	Individual mode's
blended	Apparel, Automotive, Books, DVD, Electronics, GourmetFood, HealthPersonalCare, Kitchen, Music, PCHardware, PetSupplies, Shoes, Software, SoftwareVideoGames, SportingGoods, Tools, Toys, VHS, VideoGames Note: blended does not include all the possible store sections.
music	Classical, DigitalMusic, MusicTracks
video	dvd, vhs

Note: amazon.co.uk uses different mode values. See: Using Associate Engine with amazon.co.uk.

---

Search Types

The following table shows what parameters to use for the various search types. Text shown in green (e.g.: MODE) indicates a value that you need to specify. For example, mode=MODE means that you should replace MODE with one of the possible modes (see table above).

For more examples, see the "Overview" section and the "Sample HTML" section.

---

Search Parameters

---

Search Modifier Parameters

The following optional parameters modify the search.

---

Sorting the Results

The results can be sorted in various ways by using the sort parameter. The possible values of the Associate Engine sort parameter vary depending upon the type of search being performed.

The following tables are based on the AWS API Guide documentation (version 9-Feb-2004). The Associate Engine sort parameter is passed directly to Amazon Web Services (AWS) as is. The values of the sort parameter shown below were choosen by Amazon.com as part of AWS; comments about inconsistencies should be address to Amazon.com Associates management :)

NOTE: The order of results returned by AWS may not exactly match the order of results displayed on the amazon.com website. This is due to the sort algorithm used by AWS (Associate Engine does not do the sorting; AWS does the sorting); comments about differences in results between AWS and the amazon.com website should be addressed to Amazon.com Associates management :)

Sorting Books Results (US: mode=books) (UK: mode=books-uk)
Sort Type	sort Parameter
Featured Items	+pmrank
Bestselling	+salesrank
Average Customer Review	+reviewrank
Price (Low to High)	+pricerank
Price (High to Low)	+inverse-pricerank
Publication Date	+daterank
Alphabetical (A-Z)	+titlerank
Alphabetical (Z-A)	-titlerank

Sorting Camera and Photo Results (US: mode=photo)
Sort Type	sort Parameter
Featured Items	+pmrank
Bestselling	+salesrank
Alphabetical (A-Z)	+titlerank
Alphabetical (Z-A)	-titlerank

Sorting Computers Results (US: mode=pc-hardware)
Sort Type	sort Parameter
Featured Items	+psrank
Bestselling	+salesrank
Alphabetical (A-Z)	+titlerank
Alphabetical (Z-A)	-titlerank

Sorting DVDs Results (US: mode=dvd) (UK: mode=dvd-uk)
Sort Type	sort Parameter
Bestselling	+salesrank
Alphabetical	+titlerank

Sorting Electronics Results (US: mode=electronics) (UK: mode=electronics-uk)
Sort Type	sort Parameter
Featured Items	+pmrank
Bestselling	+salesrank
Alphabetical	+titlerank
Review	+reviewrank

Sorting Kitchen Results (US: mode=kitchen) (UK: mode=kitchen-uk)
Sort Type	sort Parameter
Featured Items	+pmrank
Bestselling	+salesrank
Alphabetical (A-Z)	+titlerank
Alphabetical (Z-A)	-titlerank
Manufacturer (A-Z)	+manufactrank
Manufacturer (Z-A)	-manufactrank
Price (Low to High)	+price
Price (High to Low)	-price

Sorting Music & Classical Music Results (US: mode=music or classical) (UK: mode=music or classical)
Sort Type	sort Parameter
Featured Items	+psrank
Bestselling	+salesrank
Artist Name	+artistrank
Original Release Date	+orig-rel-date
Alphabetical	+titlerank

Sorting Outdoor Living Results (US: mode=garden)
Sort Type	sort Parameter
Featured Items	+psrank
Bestselling	+salesrank
Alphabetical (A-Z)	+titlerank
Alphabetical (Z-A)	-titlerank
Manufacturer (A-Z)	+manufactrank
Manufacturer (Z-A)	-manufactrank
Price (Low to High)	+price
Price (High to Low)	-price

Sorting Software Results (US: mode=software) (UK: mode=sw-vg-uk)
Sort Type	sort Parameter
Featured items	+pmrank
Bestselling	+salesrank
Alphabetical	+titlerank
Price (High to Low)	+price
Price (Low to High)	-price

Sorting Tools Results (US: mode=tools)
Sort Type	sort Parameter
Featured Items	+psrank
Bestselling	+salesrank
Alphabetical (A-Z)	+titlerank
Alphabetical (Z-A)	-titlerank
Manufacturer (A-Z)	+manufactrank
Manufacturer (Z-A)	-manufactrank
Price (Low to High)	+price
Price (High to Low)	-price

Sorting Toys Results (US: mode=toys) (UK: mode=toys-uk)
Sort Type	sort Parameter
Featured Items	+pmrank
Bestselling	+salesrank
Price (Low to High)	+pricerank
Price (High to Low)	+inverse-pricerank
Alphabetical (A-Z)	+titlerank

Sorting Video Results (US: mode=vhs) (UK: mode=vhs-uk)
Sort Type	sort Parameter
Featured Items	+psrank
Bestselling	+salesrank
Alphabetical	+titlerank

Sorting Video Games Results (US: mode=videogames) (UK: mode=video-games-uk)
Sort Type	sort Parameter
Featured Items	+pmrank
Bestselling	+salesrank
Alphabetical	+titlerank
Price (Low to High)	+price
Price (High to Low)	-price

Output-Related Parameters

Run-Related Parameters

You can run the script in various ways. If you run it using a Server-Side-Include (SSI) statement, a PHP virtual() function call, a PHP file_get_contents() function call, or using a <SCRIPT> tag, or using an <IFRAME> tag, then one of the following parameters must be specified.

See Quick Tutorial for a tutorial on using <SCRIPT> tags and SSI statement.

Miscellaneous Parameters

ASIN List Searches

Random Selection

Note: See Bug section below regarding a limitation.

Searching for random ASIN's based on a file of ASIN's is supported. Create a text file containing the ASIN's and save it in the ae-asin directory as mylist.txt (you can use any filename, such as cookbooks.txt).

There is no limit to the number of ASIN's that you can put in an ASIN list file.

On our webserver, we created a file ae-asin/mylist.txt that contains the following lines: (they are the ASIN's of 6 books about the artist Salvator Dali)

0486274543 0486282864 0821224808 3822812099 3822827401 3822872059

Then do a search:

1. asinsearch=mylist
   Searches for one random ASIN from mylist.txt file.

2. asinsearch=mylist:3
   Searches for 3 random ASIN's from mylist.txt file, preserving order of ASIN's. Use any number after the colon to specify how many ASIN's to use. To show all the ASIN's, use a large number (maximum is 30).

3. asinsearch=mylist:-3
   Searches for 3 random ASIN's from mylist.txt file, scrambling the ASIN's so the order is not preserved. Use any number after the colon to specify how many ASIN's to use. To show all the ASIN's, use a large number (maximum is 30).

---

Pre-Defined Searches

You could also use search.* configuration variables to pre-define searches. For example, you could define the following configuration variable:

search.artbooks "asinsearch=mylist:3&grid=c:3"

The above line defines a search called artbooks as being equivalent to the search asinsearch=mylist:3 and formatted as a 3-column grid. As indicated above, this would do a search of 3 random ASIN's from the mylist ASIN file. You could then use this pre-defined search via:

/cgi-bin/ae.pl?search=artbooks

With the above definition of search.artbooks, this URL is equivalent to:

/cgi-bin/ae.pl?asinsearch=mylist:3&grid=c:3

---

"No results found" Error

If any of the ASIN's in a multi-ASIN request do not exist, then Amazon.com's AWS server reports an error response back to Associate Engine. In that case, AWS does not returned data for any of the ASIN's that do exist. Associate Engine therefore reports "No results found" message. Manually test each of the ASIN's until you determine which one is causing the error, e.g.: to test ASIN 1234567890, use something like: /cgi-bin/ae.pl?asinsearch=1234567890

---

Timed Selection

The asinsearch parameter supports Clock Codes. Thus you could have ASIN lists week01.txt, week02.txt, ... week52.txt for each week of the year and use asinsearch=week%W:3 to display 3 random ASIN's from the current week's file.

---

Bug

Currently, at most 9 ASIN's can be selected otherwise the first 10 results will be repeated. So select at most 9 results, such as: /cgi-bin/ae.pl?asinsearch=mylist:9

For more than 9 products, use a different type of search, such as a keyword search or a browse node # search.

PowerSearch (Advanced Search of Books)

The PowerSearch (power search) parameter allows searching books against a variety of specific product fields such as publisher name and format (see table below for fields). Power Search is basically equivalent to amazon.com's "Power Search" search feature.

The format is:

powersearch=QUERY

If necessary, you can also break the fields of the QUERY into separate parameters: (see "Seperate Parameters" section below)

powersearch.OPTION1=VALUE1&powersearch.OPTION2=VALUE2&...

Note: If there are any spaces in the QUERY, then type them as either + or as %20 (the ASCII value of a space character).

Field	Query	VALUE
Title	title: VALUE title-words-begin: VALUE title-begins: VALUE	any text
Subject	subject: VALUE subject-words-begin: VALUE subject-begins: VALUE	any text
Author	author: VALUE author-exact: VALUE author-begins: VALUE	any text
Keyword	keywords: VALUE keywords-begin: VALUE	any text
ISBN	asin: VALUE	an ISBN number
Publisher	publisher: VALUE	any text
Language	language: VALUE	spanish
Publication Date	pubdate: VALUE	before YEAR during YEAR after YEAR (e.g.: during 2003)
Format	binding: VALUE	hardcover paperback digital abridged large print calendar (*for audiobooks, see note below)
Browse node	browse: VALUE	any amazon.com browse node number

*Note: To search for audiobooks, use "browse:44" (audiobooks is amazon.com browse node 44). For example, "harry potter" audiobooks would be: powersearch=title:harry+potter+and+browse:44

You can use the words and, or, and not to link different queries together. You can also group queries or values together using parentheses ( and ).

Some sample queries:

• author: ambrose (note: this is equivalent to an AuthorSearch)
• author: ambrose and binding: (abridged or large print) and pubdate: after 11-1996
• subject: history and (spain or mexico) and not military and language: spanish
• (subject: marketing and author: kotler) or (publisher: harper and subject: high technology)
• keywords: high tech and not fiction and pubdate: during 1999

---

Separate Parameters

If necessary, you can break the fields of the QUERY into separate parameters:

powersearch.FIELD1=VALUE1&powersearch.FIELD2=VALUE2&...

Associate Engine will "glue" the separate parameters together to internally make one PowerSearch parameter. When Associate Engine glues the parameters together, a boolean AND is put between each parameter and parentheses are added around each field/value. The internal processing is effectively:

(FIELD1: VALUE1) and (FIELD2: VALUE2) and ...

Using separate parameters is useful in a situation where you want the user to select one or more field values (e.g.: keyword) and you want other field values to be set by you the webmaster. For example, the following is a form that would search for audiobooks (browse node 44) from the author that the user types in.

<FORM ACTION="/cgi-bin/ae.pl" METHOD="GET"><P>    <INPUT TYPE="HIDDEN" NAME="powersearch.browse" VALUE="44">    Author: <INPUT TYPE="TEXT" NAME="powersearch.author">    <INPUT TYPE="SUBMIT" VALUE="Search"> </P></FORM> Author: (try: dyer)

You can mix a powersearch parameter with powersearch.* parameters. They will all be glued together. For example, the above example could also be written as:

<FORM ACTION="/cgi-bin/ae.pl" METHOD="GET"><P>    <INPUT TYPE="HIDDEN" NAME="powersearch" VALUE="browse:44">    Author: <INPUT TYPE="TEXT" NAME="powersearch.author">    <INPUT TYPE="SUBMIT" VALUE="Search"> </P></FORM> Author: (try: dyer)

If necessary, you can use an expression as a parameter value. For example, the following searches for books about Spanish or Mexican history from the author that the user specifies:

<FORM ACTION="/cgi-bin/ae.pl" METHOD="GET"><P>    <INPUT TYPE="HIDDEN" NAME="powersearch"       VALUE="subject: history and (spain or mexico)">    Author: <INPUT TYPE="TEXT" NAME="powersearch.author">    <INPUT TYPE="SUBMIT" VALUE="Search"> </P></FORM> Author: (try: parker)

When the user submits the above form, the PowerSearch query gets processed internally as:

(subject: history and (spain or mexico)) and (author: VALUE)

As with any form, you can use a drop-down menu to let the user pick from a list of pre-defined values. For example, the following form is similar to the above form yet the user is given the choice of whether to search for books about Spanish history, or Mexican history, or both (Spanish or Mexican history).

<FORM ACTION="/cgi-bin/ae.pl" METHOD="GET"><P>    Subject:    <SELECT NAME="powersearch.subject" SIZE="1">       <OPTION VALUE="history and spain">Spanish History</OPTION>       <OPTION VALUE="history and mexico">Mexican History</OPTION>       <OPTION VALUE="history and (spain or mexico)">both</OPTION>    </SELECT>    <BR>    Author: <INPUT TYPE="TEXT" NAME="powersearch.author">    <INPUT TYPE="SUBMIT" VALUE="Search"> </P></FORM> Subject: Spanish History Mexican History both Author: (try: parker)

E.&O.E.; © Cusimano.Com Corporation; www.c3scripts.com