The Product API is a service designed to provide a way to access products from various item sources used by the Product Portals platform.  Currently, there are two different versions of the API: Single Product Lookup and Product Search.  Both forms return data in an XML format.  There are also two different forms of each call: one using a Domain, and one using a Placement.

 

Single Product API

Domain

This form of the API is designed to look up a single item sold on a product portal.  Here is how you should structure your url to correctly use this service:

http://productportals.wishpot.com/product_api.xml?<item number>&domain_id=<domain id>

There are two fields of interest:

• Item Number - Required

This value is used to lookup the product.  Across different item sources the form of the item number may vary, but in product search responses you will always see a long number, followed by an underscore, a (for now) single-digit number, another underscore, and yet another single digit value.  Here is an example:

1697020230_2_1

Generally, the easiest way to find an item number is to find the item you want to look up, go to its product page, and locate the item number in the URL for that page.  The item number will be the last part of the URL before any parameters.

• Domain Id - Required

For the Product Lookup API, the domain is used exclusively for tracking.  The domain id is actually the database id for the record that represents the domain.  For instance, http://www.harddrives.com has all of its domain-specific information stored in record 143.  Any valid domain id will allow the look-up to work; however, the domain you include will ultimately be where the clicks are sent, so choosing a random domain is probably not a good idea.

 

Placement

The only change you need to make between the domain and placement forms is one parameter.  Instead of the domain_id being equal to a domain's database id, you simply need to replace it with "placement_id", with a value of a placement's database id.  So the following would be an example of the url form:

http://productportals.wishpot.com/product_api.xml?<item number>&placement_id=<placement id>

 

Product Lookup: Example Response

Here is an example response for a product lookup:

 

<summary>

            <totalProducts>1</totalProducts>

            <products>

                        <product>

                                    <title>

Seagate(R) FreeAgent(R) GoFlex(TM) Ultra-Portable External USB 3.0 Hard Drive, 500GB, Black

                                    </title>

                                    <item_num>2253013528_2</item_num>

                                    <price>79.99</price>

                                    <currency>en</currency>

                                    <url>

http://www.bizrate.com/rd?t=http%3A%2F%2Flink.mercent.com%2Fredirec...

                                    </url>

                                    <description>

Seagate(R) FreeAgent(R) GoFlex(TM) Ultra-Portable External USB 3.0 Hard Drive, 500GB, Black

                                    </description>

                                    <brand>Seagate</brand>

                                    <image>

                                                <width>400.0</width>

                                                <height>400.0</height>

                                                <source>

http://image10.bizrate-images.com/resize?sq=400&uid=2253013528&...

                                                </source>

                                    </image>

                        </product>

            </products>

</summary>

 

Product Search API

Domain

This form of the API is used to get multiple products.  This call emulates the call a domain makes to an actual item provider, so some of the same information is required.  This information is encapsulated by both a domain (again, for tracking) and its home page.  Here is the form for the product search api:

http://productportals.wishpot.com/product_api.xml?term=<search term>&domain_id=<domain id>

There are quite a few more parameters available to the product search API.  In this section, the ones that are particular in some way to domains are described.

• Domain ID - Required 

Example parameter: domain_id=143

Like the Single Product Lookup API, this is a database ID value for a domain.  However, this is used for more than just tracking for the Product Search API.  The search that occurs for the products will use the category and item source that is assigned to the home page of the domain that is used.

• Search Term - Optional

Example Parameter: search_term=hard+drives

This is the string used to search for products for the item source the home page of the passed in domain is using.  If you do not include a search term, the default search term associated with the domain will be used instead.  Though it can be anything you like, its most useful when relevant to the category being used (also assigned to the domain's home page).

 

Placement

Placements do not have as much data associated with them as a domain, so they require a little more work to 'tune' effectively.  Below is an example product search with a placement:

http://productportals.wishpot.com/product_api.xml?placement_id=<... id>&term=<search term>

The additional parameters whose behavior is unique to placements are described below:

• Placement ID - Required

Example parameter: placement_id=1

This value is identical to the item look up placement id, and is essentially used for the same purpose.

• Search Term – Required

Example parameter: search_term=hard+drives

Unlike a domain, a placement has no default search term, thus making this a required field.  As with a domain, you may use any value you want, but it should be relevant to your category for the best effect.

• Source – Optional

Example parameter: source=Wishpot+CPC+Blend

This parameter is used to determine from what item source your items will be pulled from.  Not specifying one will cause your placement to use whatever you item source you assigned to it.  The acceptable values for this field are the same as the ones listed in the item source selection for a placement form when you create/edit one.

• Category – Optional (but suggested)

Example Parameter: category=Computers+%26+Software

If you do not specify a category, the broadest category available for the source you are using (either the one assigned to the placement or one that is passed in) will be used instead.  Because having an extremely broad category is often undesirable, it is suggested that this parameter is used.

Product Search – Other Parameters

These parameters are available to either form of the API.

• Brand

Example parameter: brand=32295_2

A brand can be specified to limit the products returned to just one manufacturer.  Brands are included in product search results, in an element called <brands>.  Below is an example:

<brand>

            <name>HP</name>

            <code>32295_2</code>

</brand>

The name will allow you to choose the brand you want to use, while the code is the actual value that needs to be passed.  A brand must include the underscore and (for now) single digit number at the end.

 

• Price Range

Example parameters min=100&max=200 

These parameters can be used to limit the products you receive by their price.  Here are some basic constraints:

• A min value must be specified, but a max value is optional.
• A min must be less than a max value
• Both the min and max values must be numeric
• Both must be greater than 0.
• Including a max without a min will cause the max to be ignored.

Beyond that, the only other note is the format: prices are integral.  Thus, to limit products to being at least $100.00, use a min value of 100.

 

• Page

Example parameter: page=2

Oftentimes, the number of products your search generates will far exceed the number that is returned.  To get at the others, you can use subsequent requests with the same variables, but specifying a different page number.

 

• Limit

Example parameter: limit=4 

There may be times when you would like to limit the number of products that are returned.  In this case, you may use the limit parameter.  There are a couple of constraints to this:

• A limit must be larger than 0.
• A limit must be no larger than the page size.
• A limit that is higher than the number of products being returned for a particular search will be ignored.

In the case of the second point, it is important to note that a page's size is not defined by the limit used.  In other words, if you pass a limit of 4 on a page size of 20, you will get the first 4 items.  If you pass in the page=2 parameter, with the same limit, the next 4 items you get will be from the next set of 20 items.  They will not be from the first set.  This is due to constraints from normalizing paging across multiple item sources.

 

 

Notes:

The database id for a domain can easily be found in the URL for the domain's edit page.  The id will be the numeric value at the end of the edit page URL *before* the parameters.  Example:

 

http://productportals.wishpot.com/edit/<domain id>?tab_id=579

 

The database id for a placement is a little trickier to find, but not too much more difficult.  When visiting either the stats page or the widget page for the placement, the final number before any parameters will be the database id.  Example:

 

http://productportals.wishpot.com/placements/stats/<placement id>/