Shopping.com Publisher API REST Option Reference

apiKey

The key that uniquely identifies the publisher with Shopping.com, attained through the Partner Account Center online application.

trackingId

SDC generated ID used for revenue tracking at the campaign (placement) level. This ID will be provided through the Partner Account Center when you sign up for the API. Previously known as a "linkin ID".

subTrackingId

User generated ID used to further break down traffic sources beyond SDC campaign level tracking. You may choose any arbitrary alpha-numeric sequence (up to 25 characters), and use as many different IDs as required.  Please note that you must contact your account manager to have reporting enabled for this sub-tracking ID - otherwise the parameter will simply be ignored.

visitorUserAgent

The browser user-agent of the visitor to which this data is being presented.  This data helps Shopping.com to differentiate real users from web crawlers or robots.

visitorIPAddress

The IP address of the visitor to which this data is being presented.  Like visitorUserAgent, this data helps Shopping.com to differentiate real users from web crawlers or robots.

categoryId

Used to restrict query results to a given category. There are two classes of category: leaf-level categories contain products and offers, whereas parent-level categories contain only other categories. Searches on parent-level categories must be additionally constrained by at least one keyword.

keyword

The simplest and most popular way to query Shopping.com is to request results using keywords. Results can vary widely depending on the corresponding options and the keyword(s) used. For example, searching for a keyword like "Sony" may return items in many different categories while searching for "digital cameras" may return items from a single category (if skipping is enabled). Multiple keywords (and/or attribute values) may be submitted to further constrain the results.

attributeValue

Used to filter query results based on item properties. Shopping.com API queries may return a list of attribute values, which can be used to filter a given list of items to a more manageable set. The resulting list can be further filtered by supplying additional attribute values. Searches by attribute value can be mixed with searches by keywords to help the user filter results to the desired item(s).

showAllValuesForAttr

Request all values to be returned for a single attribute. Generally, a page will display a truncated list of values for the attributes being presented.  This is also useful when requesting attributes without values, as you need a way for the user to view the actual list of values should they want to filter results using that attribute.  Use this parameter to allow the user to select from among all possible values for an attribute (at least all values which are applicable to the result set.)

productId

Searching by productId returns offers for a specific product. For a valid product ID, the API will return a single category, containing a single product, containing a list of offers.  Multiple productId parameters may be provided in a single request.

offerId

Searching by offerId returns a single offer matching the given ID. For a valid offer ID, the API will return a single category, containing a single offer.  Multiple offerId parameters may be provided in a single request, in which case, the returned category will be the lowest common ancestor of all offers returned.

It should also be noted that the Shopping.com offer catalog is much more dynamic than the product catalog since it reflects available inventory, and as such, offer IDs will not be as stable as product IDs.  We suggest storing other relevant information along with the offer ID (e.g. product ID, category ID, attribute values, etc.) to allow displaying related results should an offer ID becomes invalid.

groupItemsByCategory

Control whether or not items are separated into different categories. By default, searches don't separate items by category. Instead, a single category (with id "0") is returned containing items from different categories.

numAttributes

The number of attributes to return in results which contain only one category. For any result composed of a single category containing a list of products or offers (not for the same product), the Shopping.com API may provide attributes for filtering the results to more manageable sizes. By default, the API will return 0 attributes, which can be changed by using this parameter. However, any attributes above 5 will not include values unless you also set the numAttributesWithValues parameter. Note that attributes are never returned for offers under a single product, only for items at the category level.

numAttributesWithValues

Control the number of attributes for which values will be returned. Requesting attributes without values (i.e. setting this parameter to a smaller value than numAttributes,) allows you to present the user with more filtering options while saving space on the page. By default, up to 5 attributes will include values.

numValuesPerAttribute

Control the number of values to include with each attribute. Attribute values can be used to filter the list of items in a query result. By default, 5 values will be provided for each of the first 5 attributes returned.

doKeywordNormalization

Control whether or not submitted keywords should be "normalized" by the search engine. Normalization consists of several steps including spell checking, stemming, tokenization and special character removal.

numCategories

When a search result contains multiple categories, the API will return up to 5 matching categories (within the relevance thresholds). If you would like more (or fewer) categories returned (still within the relevance thresholds), use the numCategories parameter. If, on the other hand, you would like to return all matching categories, regardless of relevance, use the showAllMatchingCategories parameter.

showAllMatchingCategories

Control whether or not this query will return all matching categories, regardless of relevance. When performing a keyword search, the Shopping.com API will normally return 0 or more matching categories up to a relevance threshold. This means that even if the search engine finds 100 categories matching the keyword, it may only return a fraction of those if it determines that the remaining categories are outside of the relevance threshold. Setting the numCategories parameter to 100 will not change this behavior, as numCategories is overruled by relevance thresholds.

If you would like to see all matching categories (sorted alphabetically), regardless of relevance thresholds, use the showAllMatchingCategories parameter. Keep in mind, however, that due to the large number of categories normally returned, the API will not return items per category for this type of result. If, on the other hand, your keyword search has skipped to a single category, and you would simply like to see results from more than that one category (still subject to relevance thresholds), use the doSkipping parameter instead .

numItems

Control how many products and/or offers are returned within a category as well as the number of offers returned within a single product result. The only case where this parameter is not used is in the case where the showProductOffers option is being used to return offers for multiple products. In that case, the numOffersPerProduct parameter is the equivalent.

showProductOffers

Control whether or not offers are returned for each product in multi-product results. Normally when the API returns a product item, the offers for that product are not returned, unless the search engine has skipped to a single product. Instead, the API provides the product ID, which can be used to make a follow-up request for offers using a search by product ID query. If instead you would like offers included with every product returned, you can use the showProductOffers parameter.

numOffersPerProduct

If the showProductOffers option is true, this parameter controls how many offers will be returned for each product when a search returns multiple products.

showOffersOnly

Control whether search results should return only offers (i.e. no product information.) At the moment, showOffersOnly does not support searches across multiple categories, which means you can limit the search to offers only when searching by leaf-level category or product ID.

showSoftProducts

Control whether or not "soft products" are returned. "Soft Productization" allows SDC to create more of a structured experience around soft goods such as shoes and fragrances, much like that used for hard goods such as electronics. This parameter can be used to disable Soft Productization, and receive only offers in soft categories (i.e. no products.)

showProductsWithoutOffers

Control whether or not results should include all products which match your search criteria, regardless of whether any store offers currently exist for those products. Normally, products without offers are excluded from search results.

showProductSpecs

Product specifications include data about products from the Shopping.com catalog, including things such as MPN/UPC, weight, dimensions, or other features which may be unique to the specific product.  Generally, when products are returned in SDC API results, they only include a few details about the product itself, and then possibly a list of store offers.   This parameter will control the inclusion of complete specifications for the returned products in addition to any other information (offers, reviews) you have requested. 

You can also do a side by side comparison of any number of products, simply by providing multiple productId parameters in the request, or by using this parameter along with a request which returns multiple products (generally, products should be from the same category, as a comparison of products from different categories would generally not be meaningful.)  Finally, if you only want product specifications, and don't care about the store offers for those products, remember to set the parameter 'showProductOffers' to false (or set 'numItems' to 0 if making a single productId request.)

showProductReviews

Reviews are provided for many of the products in the Shopping.com catalog courtesy of the Epinions community.  This parameter will allow you to retrieve product reviews with every product returned by the API (if available).  Each reviews section will contain the overall (average) rating, as well as a list of individual ratings, including the 'pros', 'cons', 'bottom line', and a short snippet of the full review text.  As with product specifications, if you only want product reviews, and don't care about the store offers for those products, remember to set the parameter 'showProductOffers' to false (or set 'numItems' to 0 if making a single productId request.)

Any individual review displayed must include a link to the “full review” (which will be provided in the API response) as well as attribution to Epinions through the display of a logo (http://img.shopping.com/wtb/logos/logo_www.epinions.com.gif) and language that states "provided by Epinions".  Also, the complete reviews information must be presented as it is returned by the API and cannot be altered.  Finally, reviews content must be enabled by your account manager, upon acceptance of an amendment to the original API agreement (which they will provide.)

numReviewsPerProduct

If the showProductReviews option is true, this parameter controls how many reviews will be returned for each product in the API results.

pageNumber

Set which page of results to return. When more results are available than are returned in a single query (indicated by a difference between the matchedCount and returnedCount) additional pages of results can be requested using the pageNumber parameter. Pagination currently only works for items returned by a leaf-level category search, a keyword search resulting in items across multiple categories, or the offers returned by a product ID search. You currently cannot paginate any results of a groupItemsByCategory=true keyword-only search, nor can you paginate the offers returned for each product when using the showProductOffers parameter.

productReviewsPageNumber

Set which page of reviews to return for each product. When more reviews are available than are returned for a particular product, or list of products (indicated by a difference between the matchedReviewCount and returnedReviewCount) additional pages of reviews can be requested using the reviewsPageNumber parameter.  Generally, reviews pagination only makes sense in the context of a single product, as reviews will be paginated for all products present in the response (if applicable.)

doSkipping

Control whether or not the Shopping.com search engine should "skip" directly to the most relevant category or product as a result of a keyword search, rather than providing a wider (but less relevant) selection of results across multiple categories. With skipping disabled, the set of categories returned by the API will still be limited to the most relevant. If instead, you would like to see all categories in which the keyword was found (not limited by relevance thresholds), use the showAllMatchingCategories parameter.

postalCode

Set the postal code of the current user, for tax and shipping purposes. Tax and shipping costs will be provided along with each offer returned by the API (when available) if a valid postal code is included in the request. These costs will be added to the offer's base price to calculate a total price, which is then used for sorting by price.

offerSortType

Set the method of sorting offers. The API will return offers ordered to maximize yield by default. If you would like to use a different type of ordering (e.g. the user requested to sort by price) for results containing only offers, use the offerSortType parameter to control the type of sorting, and the offerSortOrder to control the direction of sorting. The available sort types are:

1. store-name - The name of the store providing this offer, sorted alphabetically.
2. store-rating - The average rating (between 0 and 5) of the store providing this offer, based on reviews by Epinions members.
3. price - The total price of the offer (base price if total price isn't available.)
4. relevance - A score calculated by the Shopping.com search engine to indicate how well the result relates to the search criteria, based on factors such as lexical relevance, user behavior, etc. The store's bid is used in the case of a list of offers for a single product, since all offers are equally relevant.
5. featured-store - The default sort order of the Shopping.com site, this places the offers from the N highest bidding stores at the top, followed by any remaining offers sorted by price. N is determined by the numFeatured parameter, and is set to 3 by default.

There are separate sort type and sort order parameters for results containing only products or a mix of products and offers.

numFeatured

Set the maximum number of featured stores to include in a result containing a list of offers, when using the 'featured-store' offer sort type. By default, up to 3 featured stores will be included.

showSmartBuy

Control whether or not the lowest-price offer from a trusted store will be flagged. The Shopping.com Smart Buy is the lowest offer from a trusted store within the list of offers for any given product. By enabling the showSmartBuy parameter, the offer matching these criteria (if one exists) will be marked as the smartBuy. Additionally, if using the "featured-store" offer sort type, the smartBuy will be moved to the first position below any featured offers.

offerSortOrder

Control whether results containing only offers will be sorted in ascending or descending order.

productSortType

Control how to sort results containing only products. The API will return products ordered to maximize yield by default. If you would like to use a different type of ordering (e.g. the user requested to sort by price) for results containing only products, use the productSortType parameter to control the type of sorting, and the productSortOrder to control the direction of sorting. The available sort types are:

1. relevance - A score calculated by the Shopping.com search engine to indicate how well the result relates to the search criteria, based on factors such as lexical relevance, user behavior, etc.
2. product-rating - The average rating (between 0 and 5) of the product based on reviews by Epinions members.
3. price - The average price of the product.

There are separate sort type and sort order parameters for results containing only offers or a mix of products and offers.

productSortOrder

Control whether results containing only products will be sorted in ascending or descending order.

hybridSortType

Control how to sort results containing both products and offers. The API will return items ordered to maximize yield by default. If you would like to use a different type of ordering (e.g. the user requested to sort by price) for results containing a mix of products and offers, use the hybridSortType parameter to control the type of sorting, and the hybridSortOrder to control the direction of sorting. The available sort types are:

1. relevance - A score calculated by the Shopping.com search engine to indicate how well the result relates to the search criteria, based on factors such as lexical relevance, user behavior, etc.
2. price - The total price of the offer (base price if total price isn't available,) or the average price for products.

There are separate sort type and sort order parameters for results containing only products or only offers.

hybridSortOrder

Control whether results containing a mix of products and offers will be sorted in ascending or descending order.

productReviewsSortType

Control how to sort product reviews listings. The API will return product reviews ordered by review date by default. If you would like to use a different type of ordering (e.g. the user requested to sort by rating) for product reviews, use the productReviewsSortType parameter to control the type of sorting, and the productReviewsSortOrder to control the direction of sorting. The available sort types are:

1. review-date - The date (and time) the review was written.
2. product-rating - The authors overall rating (between 0 and 5) of the product.

productReviewsSortOrder

Control whether product reviews listings will be sorted in ascending or descending order.

Option availability by search method

Shopping.com is trying to ensure every option is available in every use case it would makes sense. Some limitations, however, were not immediately addressable, and we are currently working hard to "plug these holes." In the meantime, this chart shows which options are usable in offerId, productId, categoryId, and keyword searches.

<sub>1. When performing a category search without an additional keyword, only leaf level category IDs are allowed.
2. Only available in the context of a multiple category result, with groupItemsByCategory=false (or undefined).</sub>