Shopping.com Publisher API Use Cases
- Searching for products and offers
- Search by keyword
- Search by keyword, and return only categories
- Search by keyword, and show all matching categories (disregard relevance)
- Search by category
- Search by category and keyword
- Search by category and attributes
- Search by product ID
- Search by offer ID
- Filter results by price
- Search by UPC/EAN
- Additional search results content
- Controlling the number of search results
- Control the number of attributes returned
- Control the number of attributes which include values
- Control the number of values per attribute returned
- Return all values for a specific attribute
- Control the number of categories returned
- Control the number of products or offers returned
- Set number of Featured Stores
- Include offers for every product
- Control the number of offers returned per product
- Control the number of reviews returned per product
- Paginate products and/or offers
- Paginate product reviews
- Sorting search results
- Miscellaneous search options
- Requesting category tree information
Searching for products and offers
Search by keyword
A keyword search is the simplest and most popular way to request results from the Shopping.com API. However, the results generated by a keyword search can vary widely. A keyword such as 'sony' may return items across multiple matching categories, while a more specific keyword such as 'digital cameras' may skip directly to a single category, returning items within that category. In all, there are 5 possible sets of results a keyword search may return:
- No matching results ('qwerty')
- Multiple matching categories - optionally including top products/offers ('sony')
- A list of matching products ('digital cameras')
- A list of matching offers ('flowers')
- A mixed list of matching products and offers ('shoes')
While these results may all be different in content, structurally they will all be the same. Meaning, each result will contain zero or more categories, each category containing zero or more products or offers, and each product containing zero or more offers. This should enable you to write one set of parsing rules that will apply to all result sets.
It should also be noted that at this time, the Shopping.com API only supports boolean 'AND' searches between different words of a search phrase. If words are separated by anything other than a space, they will be searched for in order. For example, the keyword 'digital cameras' is seen by the search engine as 'digital AND cameras', while the keyword 'digital-cameras' is seen as 'FIRST digital AND THEN cameras'.
Finally, make sure to URI-encode all keywords using UTF-8 encoding. For example, the character "ü" would be encoded as "%C3%BC" (UTF-8), not "%FC" (ISO-8859-1/Latin1).
<GeneralSearchRequest>
<NavigationFilter>
<keyword>nikon</keyword>
</NavigationFilter>
</GeneralSearchRequest>
Search by keyword, and return only categories
By default, when a keyword is found in multiple categories, the API will return a result set containing a mix of items across those categories. If you only want the matching categories, and aren't concerned with the items within those categories, you can use 'numItems' parameter to exclude them (therefore making the result smaller and faster.) Note: you may also want to disable 'skipping' (see Disable skipping) in such cases, or you may often get results containing only a single category.
<GeneralSearchRequest>
<NavigationFilter>
<keyword>nikon</keyword>
</NavigationFilter>
<Options>
<numItems>0</numItems>
</Options>
</GeneralSearchRequest>
Search by keyword, and show all matching categories (disregard relevance)
When performing a keyword search with the 'groupItemsByCategory' parameter (see Group items by category in multiple category results), 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 (see Control the number of categories returned) 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 (see Disable skipping).
<GeneralSearchRequest>
<NavigationFilter>
<keyword>sony</keyword>
</NavigationFilter>
<Options>
<showAllMatchingCategories>true</showAllMatchingCategories>
</Options>
</GeneralSearchRequest>
Search by category
Searching by category rather than keyword allows the end user to browse the Shopping.com catalog. The category tree is broken down into two groups: parent level categories, and leaf level categories. Parent level categories contain other (child) categories, while leaf level categories contain items. Category IDs can be found in a number of places, including the category tree or SearchHistory section of a result.
Category search results come in all the same flavors as keyword search results (see Search by keyword), depending on the category ID used in the search.
<GeneralSearchRequest>
<NavigationFilter>
<categoryId>31515</categoryId>
</NavigationFilter>
</GeneralSearchRequest>
Search by category and keyword
Searching by category ID can produce a fairly large set of results, so the user may want to narrow the results using a keyword. For example, the user may want to navigate to the Digital Cameras category, then narrow the results to only Nikon cameras using the keyword 'nikon'. Keep in mind that using a keyword filter is required when doing a category search using a parent level category. Multiple keywords and attributes (see Search by category and attributes) are allowed, and should be provided in the API request in the same order they were entered by the user.
<GeneralSearchRequest>
<NavigationFilter>
<categoryId>7185</categoryId>
<keyword>nikon</keyword>
</NavigationFilter>
</GeneralSearchRequest>
Search by category and attributes
Just as you can filter category search results by keyword, you can also filter by attributes. However, attribute filters are actually preferred to keywords when available, as they will generally produce faster and more accurate and relevant results. Multiple keywords (see Search by category and keyword) and attributes are allowed, and should be provided in the API request in the same order they were entered by the user.
<GeneralSearchRequest>
<NavigationFilter>
<categoryId>7185</categoryId>
<attributeValue>price_range_0_200</attributeValue>
<attributeValue>brand_nikon</attributeValue>
</NavigationFilter>
</GeneralSearchRequest>
Search by product ID
Searching by product ID also allows browsing by the end user (i.e. when the user clicks on a product to see store offers.) For a valid product ID, the API will return a single category, containing a single product, containing a list of offers. Performing a product ID search is generally done after a list of items (including products) has been presented to the user, such that the product ID used in the query is determined by the users click, and comes from the results of the previous query. However, a search by product ID may be used in other cases as well, such as to promote a specific product on the homepage of a shopping channel, etc. In this case, you may want to look up the product ID on http://www.shopping.com, where it can be found at the bottom of the product specifications page.
Finally, a request can contain multiple product IDs - simply provide multiple productId parameters in the query. This will allow comparison of multiple, specific products, which is especially useful when comparing product specifications (see Get product specifications.)
<GeneralSearchRequest>
<ProductFilter>
<productId>40940649</productId>
</ProductFilter>
</GeneralSearchRequest>
Search by offer ID
Searching by offer ID is generally useful for merchandising or allowing bookmarking or wishlist functionality. For a valid offer ID, the API will return a single category, containing a single offer. A request can contain multiple offer IDs - simply provide multiple offerId parameters in the query. In this 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.
<GeneralSearchRequest>
<OfferFilter>
<offerId>l3tBk8OnVy5sZrIg6liT9g%3D%3D</offerId>
</OfferFilter>
</GeneralSearchRequest>
Filter results by price
Often, a user may want to filter large results by a given price range. You can filter the results of any keyword, category, or product request according to a desired price range, using the minPrice and maxPrice parameters.
<GeneralSearchRequest>
<NavigationFilter>
<categoryId>7185</categoryId>
<minPrice>500</minPrice>
<maxPrice>1000</maxPrice>
</NavigationFilter>
</GeneralSearchRequest>
Search by UPC/EAN
Searching by UPC/EAN is similiar to doing a keyword search. The Universal Product Code (UPC) or International Article Number (EAN) are numerical codes used to mark products that are commonly sold. The Shopping.com catalog supports these codes, and they are available when requesting Product Specifications and doing keyword searches.
<GeneralSearchRequest>
<NavigationFilter>
<keyword>013803105384</keyword>
</NavigationFilter>
</GeneralSearchRequest>
Additional search results content
Request Featured Stores
By enabling the 'showFeaturedOffersOnly' parameter, a number of offers from featured stores will be returned within the requested search context. The number of offers from featured stores can be controlled with the 'numFeatured' parameter (see Set number of Featured Stores.) No other results will be returned.
<GeneralSearchRequest>
<Sort>
<showFeaturedOffersOnly>true</showFeaturedOffersOnly>
</Sort>
</GeneralSearchRequest>
Request 'Smart Buy' offer
By enabling the 'showSmartBuyOfferOnly' parameter, the offer matching the Shopping.com 'Smart Buy' criteria (if one exists) will be returned for a given product request. No other results will be returned.
<GeneralSearchRequest>
<Sort>
<showSmartBuyOfferOnly>true</showSmartBuyOfferOnly>
</Sort>
</GeneralSearchRequest>
Get product specifications
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. To retrieve product specifications along with every product returned by the API, add the 'showProductSpecs' parameter to the request. You can also do a side by side comparison of any number of products, simply by providing multiple productId parameters in the request (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.)
<GeneralSearchRequest>
<Options>
<showProductSpecs>true</showProductSpecs>
</Options>
</GeneralSearchRequest>
Get product reviews
Reviews are provided for many of the products in the Shopping.com catalog courtesy of the Epinions community. To retrieve product reviews with every product returned by the API, add the 'showProductReviews' parameter to the request. 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, only once you have reached traffic levels of 10,000 leads per month, and upon acceptance of an amendment to the original API agreement (which your account manager will provide.)
<GeneralSearchRequest>
<Options>
<showProductReviews>true</showProductReviews>
</Options>
</GeneralSearchRequest>
Controlling the number of search results
Control the number of attributes returned
For any result containing a list of items (excluding a list of offers for a single product), the Shopping.com API can provide attributes for filtering the result set to a more manageable size. By default, your account will be set up to return 0 attributes - if you would like to display attributes to allow filtering, use the 'numAttributes' parameter. However, any attributes above 5 will not include values unless you also change the 'numAttributesWithValues' parameter (see Control the number of attributes which include values).
<GeneralSearchRequest>
<Options>
<numAttributes>2</numAttributes>
</Options>
</GeneralSearchRequest>
Control the number of attributes which include values
As mentioned in Control the number of attributes returned, only the first 5 attributes will include values, even if you request more attributes. This essentially allows you to present the user with more filtering options, while saving space on the page. If you would like to show more attributes with values, you can use the 'numAttributesWithValues' parameter to increase the number of attributes which also include values.
<GeneralSearchRequest>
<Options>
<numAttributes>10</numAttributes>
<numAttributesWithValues>5</numAttributesWithValues>
</Options>
</GeneralSearchRequest>
Control the number of values per attribute returned
For those attributes which include values (see Control the number of attributes returned and Control the number of attributes which include values, up to 5 values will be returned by default. If you would like more values for each attribute, use the 'numValuesPerAttribute' parameter.
<GeneralSearchRequest>
<Options>
<numValuesPerAttribute>3</numValuesPerAttribute>
</Options>
</GeneralSearchRequest>
Return all values for a specific attribute
When requesting attributes without values (see Control the number of attributes which include values), you need a way for the user to view the actual list of values should they want to filter results using that attribute. To do this, you can request all values for a single attribute, using the 'showAllValuesForAttr' parameter. The value for this parameter should be the ID of the attribute, provided in the previous request (the one that returned the original list of attributes).
<GeneralSearchRequest>
<NavigationFilter>
<showAllValuesForAttr>21885_resolution</showAllValuesForAttr>
</NavigationFilter>
</GeneralSearchRequest>
Control the number of categories returned
When a search result contains multiple categories and you have requested that matching items be grouped by category (see Group items by category in multiple category results), 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 (see Show all matching categories for a keyword search).
<GeneralSearchRequest>
<Options>
<numCategories>2</numCategories>
<groupItemsByCategory>true</groupItemsByCategory>
</Options>
</GeneralSearchRequest>
Control the number of products or offers returned
The number of items returned per category (or the number of offers for a single product result) is controlled by the 'numItems' parameter. This does not control the number of offers per product when using the 'showProductOffers' parameter. For that, use the 'numOffersPerProduct' parameter (see Control the number of offers returned per product).
<GeneralSearchRequest>
<Options>
<numItems>2</numItems>
</Options>
</GeneralSearchRequest>
Set number of Featured Stores
When requesting featured stores using the'showFeaturedStoresOnly' parameter (see Request Featured Stores,) 3 featured stores are returned by default. To change the number of featured stores returned, use the 'numFeatured' parameter.
<GeneralSearchRequest>
<Options>
<showFeatureOffersOnly>true</showFeaturedOffersOnly>
<numFeatured>3</numFeatured>
</Options>
</GeneralSearchRequest>
Include offers for every product
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 the Search by product ID query. If instead you would like offers included with every product returned, you can use the 'showProductOffers' parameter.
<GeneralSearchRequest>
<Options>
<showProductOffers>true</showProductOffers>
</Options>
</GeneralSearchRequest>
Control the number of offers returned per product
To control the number of offers included with every product returned (see Include offers for every product), use the 'numOffersPerProduct' parameter. If instead, you are trying to control the number of items returned per category (or the number of offers for a single product result,) use the 'numItems' parameter (see Control the number of products or offers returned).
<GeneralSearchRequest>
<Options>
<showProductOffers>true</showProductOffers>
<numOffersPerProduct>3</numOffersPerProduct>
</Options>
</GeneralSearchRequest>
Control the number of reviews returned per product
To control the number of reviews included with every product returned (see Get product reviews), use the 'numReviewsPerProduct' parameter.
<GeneralSearchRequest>
<Options>
<showProductReviews>true</showProductReviews>
<numReviewsPerProduct>3</numReviewsPerProduct>
</Options>
</GeneralSearchRequest>
Paginate products and/or offers
When more results are available than are returned in the current result set, (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 (unless using the 'groupItemsByCategory' parameter), or the offers returned by a product ID search (see Search by category and Search by product ID). I.e. you currently cannot paginate the results of a parent level category search or a keyword only search, nor can you paginate the offers returned for each product, when using the 'showProductOffers' parameter (see Include offers for every product).
<GeneralSearchRequest>
<Options>
<pageNumber>2</pageNumber>
</Options>
</GeneralSearchRequest>
Paginate product reviews
When more reviews are available for a product than are returned in the current result set, (indicated by a difference between the 'matchedReviewCount' and 'returnedReviewCount',) additional pages of reviews can be requested using the 'productReviewsPageNumber' 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.)
<GeneralSearchRequest>
<Options>
<productReviewsPageNumber>2</productReviewsPageNumber>
</Options>
</GeneralSearchRequest>
Sorting
Sort items at the category level
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 items at the category level, use the 'itemsSortType' parameter to control the type of sorting, and the 'itemsSortOrder' to control the direction of sorting. The available sort types are:
- store-name - The name of the store providing this offer, sorted alphabetically.
- store-rating - The average rating (between 0 and 5) of the store providing this offer, based on reviews by Epinions members.
- product-rating - The average rating (between 0 and 5) of the product based on reviews by Epinions members.
- price - The total price of the offer (base price if total price isn't available.)
- 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.
- yield - A calculation taking into account relevance, CPCs and other factors, in order to maximize the yield (or RPM) of a result.
- publisher-revenue - A special sort type which returns products sorted by the revenue generated by the partners traffic over the trailing 2 months. This sort type can currently be used with either top level or leaf level category searches, and will disregard keywords.
- sdc-revenue - Similar to the publisher-revenue sort type, but based on the revenue generated across the entire Shopping.com network, rather than limited to the partners own traffic.
Please note that some sort types may not be applicable in all results. For instance, the 'product-rating' sort type would not apply to results containing only offers. To address situations in which you need to request a default sort order without knowing the type of results which will be returned, you can chain multiple sort types together using a comma (e.g. itemsSortType=product-rating,store-rating), and the API will use the appropriate type. There are separate sort type and sort order parameters for offers under products (see Sort product under offers.)
<GeneralSearchRequest>
<Sort>
<itemsSortType>price</itemsSortType>
<itemsSortOrder>asc</itemsSortOrder>
</Sort>
</GeneralSearchRequest>
Sort offers under products
The API will return offers under 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 offers under products, use the 'productOffersSortType' parameter to control the type of sorting, and the 'productOffersSortOrder' to control the direction of sorting. The available sort types are:
- store-name - The name of the store providing this offer, sorted alphabetically.
- store-rating - The average rating (between 0 and 5) of the store providing this offer, based on reviews by Epinions members.
- price - The total price of the offer (base price if total price isn't available.)
- 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.
- yield - A calculation taking into account relevance, CPCs and other factors, in order to maximize the yield (or RPM) of a result.
There are separate sort type and sort order parameters for items at the category level (see Sort items at the category level.)
<GeneralSearchRequest>
<Sort>
<productOffersSortType>price</productOffersSortType>
<productOffersSortOrder>asc</productOffersSortOrder>
</Sort>
</GeneralSearchRequest>
Sort product reviews
By default, the API will return product reviews ordered by the date of the review - most recent first. If you would like to use a different type of ordering (e.g. the user requested to sort by rating), use the 'productReviewsSortType' parameter to control the type of sorting, and the 'productReviewsSortOrder' to control the direction of sorting. The available sort types are:
- review-date - The date (and time) the review was written.
- product-rating - The authors overall rating (between 0 and 5) of the product.
In the case of a result containing multiple products, each products reviews sections will be sorted separately.
<GeneralSearchRequest>
<Sort>
<productReviewsSortType>product-rating</productReviewsSortType>
<productReviewsSortOrder>asc</productReviewsSortOrder>
</Sort>
</GeneralSearchRequest>
Miscellaneous search options
Get estimated sales tax and shipping
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 offers base price to calculate a total price, which is then used for sorting by price (see Sort results containing only offers, Sort results containing only products and Sort results containing a mix of products and offers). To include a postal code in API requests, use the 'postalCode' parameter.
<GeneralSearchRequest>
<Options>
<postalCode>90210</postalCode>
</Options>
</GeneralSearchRequest>
Disable skipping
When the SDC search engine performs a keyword search and finds a majority of results in a single category (or product), it will skip directly to that category or product, rather than providing a wider (but less relevant) selection of results across multiple categories or products. If you would like to disable this behavior in order to see items across the most relevant categories in which a search term is found, use the 'doSkipping' parameter. If instead, you would like to see all categories in which the keyword was found (not limited by relevance thresholds), use the 'showAllMatchingCategories' parameter (see Show all matching categories for a keyword search).
<GeneralSearchRequest>
<Options>
<doSkipping>false</doSkipping>
</Options>
</GeneralSearchRequest>
Group items by category in multiple category results
Normally when a keyword is found across multiple relevant categories, the items from those categories are returned in one combined list, and the categories are returned as attribute filters. If you would rather have the categories returned as normal category elements, with the items grouped underneath their respective categories, use the 'groupItemsByCategory' parameter.
<GeneralSearchRequest>
<Options>
<groupItemsByCategory>true</groupItemsByCategory>
</Options>
</GeneralSearchRequest>
Limit search results to matching offers
As mentioned in other use cases, the results of a search may come in many flavors. If you would like to limit the results to only offers, you can use the 'showOffersOnly' parameter. At the moment, showOffersOnly does not support searches by keyword only, nor within parent level categories, which means you can limit the search results to offers only when performing a product ID search or a leaf level category search. Using this parameter with a keyword only search or a parent level category search will produce an error.
<GeneralSearchRequest>
<NavigationFilter>
<categoryId>7185</categoryId>
</NavigationFilter>
<Options>
<showOffersOnly>true</showOffersOnly>
</Options>
</GeneralSearchRequest>
Requesting category tree information
Get category tree by ID
The category tree defines the relationships between all categories in the Shopping.com catalog. The CategoryTree request can be used to look up information on a single category (e.g. name), to learn the relationship hierarchy between categories, or to present a category browsing experience to the end user. Simply provide a category ID in the 'categoryId' parameter to see the information for that category as well as the information for all immediate children (if any) of the specified category. If you want to see information for all descendants of the specified category (not just for immediate children), use the 'showAllDescendants' parameter as well (see Include all descendants in category tree.) Finally, to see all top level categories, use category ID '0', or simply omit the categoryId parameter altogether.
<CategoryTreeRequest>
<categoryFilter>
<categoryId>3</categoryId>
</categoryFilter>
</CategoryTreeRequest>
Include all descendants in category tree
Normally, when making a CategoryTree request (see Get category tree by ID), only the specified category and it's immediate children will be returned in the result. If instead you would like to see information for all descendants of the specified category, add the 'showAllDescendants' parameter. To see the entire category tree, combine this parameter with a category ID of '0', or simply omit the category ID altogether.
<CategoryTreeRequest>
<options>
<showAllDescendants>true</showAllDescendants>
</options>
</CategoryTreeRequest>
0 Comments
Please sign in to post a comment.