ProductSearch API Improvements

Jan 11, 2010 No Comments by

This week we’ve released a few new features in our ProductSearch API module, aimed at improving the control affiliates have over how the search is actually performed.

First, there is now the ability to specify multiple search terms within one API request.  For instance, suppose you wanted to search for two kinds of snowboards, say the “Technine Icon Series Snowboard” and the “Rossignol Alias Snowboard”.  The best option, the one that gives you the most control over what results to show to your users, was – and still is – to do two separate API requests, one for each type of snowboard.  However, you now also have the option of making one search request, using “OR” syntax, e.g. “search_term=Technine Icon Series Snowboard OR Rossignol Alias Snowboard”; the API will automatically perform both searches separately and then combine the results for you.  To enable this functionality you must turn on an advanced syntax option for the API by adding the parameter “search_advanced_syntax=1″ to your request.

To see the effects yourself, take a look at the following search results for those two snowboards, with and without the new advanced syntax option turned on:|Product+Name|Merchant+Name&search_term=Technine+Icon+Series+Snowboard+OR+Rossignol+Alias+Snowboard&search_advanced_syntax=0
[Without advanced syntax, search terms are not processed separately, and results tend to be dominated by just one group.]|Product+Name|Merchant+Name&search_term=Technine+Icon+Series+Snowboard+OR+Rossignol+Alias+Snowboard&search_advanced_syntax=1
[With advanced search, each search term is treated separately, and results are more evenly spread.]

The next addition, also requiring the use of the advanced syntax option, is the ability to flag portions of your search term as required in all matches, or as “stop” words (terms that if found, should exclude an item from your results).  You can use the “+” and “-” characters to indicate terms that must or must not be present in your search results; you can even enclose groups of words in parentheses and then preface the whole group with a “+” or “-” character to quickly modify a whole series of keywords.  As an example, suppose you were looking for a particular jacket from The North Face; you might start off with a very simple search of “The North Face jackets”:|Product+Name|Merchant+Name&search_advanced_syntax=1&search_term=The+North+Face+jackets

But then you decide that you’re really only interested in the “Khumbu” style of jacket, so you can add “+Khumbu” to your search to require that “Khumbu” be present in each result, e.g|Product+Name|Merchant+Name&search_advanced_syntax=1&search_term=The+North+Face+jackets+%2BKhumbu

In case you’re wondering what that “%2B” business is, that’s the encoded equivalent of the “+” character; if you’re using PHP the urlencode() function can do this for you easily.  Finally, suppose that you’re interested only in Boy’s or Men’s versions of the jacket; you could add “-Girl -Women” or alternatively “-(Girl Women)” to your request to further filter the results:|Product+Name|Merchant+Name&search_advanced_syntax=1&search_term=The+North+Face+jackets+%2BKhumbu+-(Girl+Women)

The third, and last, of the improvements to the ProductSearch API does not involve the advanced syntax option, but rather adds the ability to specify which pieces of information (“input fields”) should be considered in a search.  Ordinarily a product search will consider all of the available, searchable information, specifically: product SKUs, names, UPCs, brand name/manufacturer details, and categorization data.  If you want to perform a very specific type of search however, you can use the “search_input_fields”  parameter to restrict your search to use just one or more of these pieces of information.  A common example would be if you were doing product name lookups only, and did not want brand name or categorization data to factor into your results at all.  Consider the following example to see the differences in a normal versus a field-restricted search for “GPS Running Watches”:|Product+Name|Merchant+Name&search_results_options=interleave&search_term=GPS+Running+Watches
[Searching all available fields can sometimes yield seemingly unrelated results, often due to categorization data which mentions some of the search keywords.]|Product+Name|Merchant+Name&search_results_options=interleave&search_term=GPS+Running+Watches&search_input_fields=name
[Searching only product names yields a much more tightly restricted set of results.]

If you get a chance to try out these advanced features on any projects of your own, be sure to let us know!

-David & AvantLink

P.S. Don’t forget about the API Request Builder (available from the “Tools” page of your affiliate account) – it can be a big help with learning about and experimenting with our API modules and their parameters.


AvantLink is a leading affiliate marketing, multi-channel analytics, referral tracking and technology platform for quality web retailers and savvy publishers. We believe in challenging standard practices and disrupting status quo technology solutions to produce high-performing programs for top merchants and premium publishers.

Affiliate Tools