• 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
• Additional search results content
  • Get product specifications
  • Get product reviews
• 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
  • 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
  • Sort results containing a mix of products and offers
  • Sort results containing only products
  • Sort results containing only offers
  • Set number of Featured Stores
  • Include 'Smart Buy' offer
  • Sort product reviews
• Miscellaneous search options
  • Get estimated sales tax and shipping
  • Disable keyword normalization
  • Disable skipping
  • Group items by category in multiple category results
  • Disable 'Soft Productization'
  • Include products without offers
  • Limit search results to matching offers
• Requesting category tree information
  • Get category tree by ID
  • Include all descendants in category tree

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=nikon

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=sony&numItems=0

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=sony&showAllMatchingCategories=true

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. If you search using a parent level category ID, you must also include a keyword (see Search by category and keyword), or you will get an error (e.g. you cannot request all items in the top level 'Electronics' category.)

<GeneralSearchRequest>
  <NavigationFilter>
    <categoryId>31515</categoryId>
  </NavigationFilter>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=31515

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&keyword=nikon

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&attributeValue=price_range_0_200&attributeValue=brand_nikon

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=40940649

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&offerId=l3tBk8OnVy5sZrIg6liT9g%3D%3D

Additional search results content

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=40940649&showProductSpecs=true

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, upon acceptance of an amendment to the original API agreement (which they will provide.)

<GeneralSearchRequest>
  <Options>
    <showProductReviews>true</showProductReviews>
  </Options>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=40940649&showProductReviews=true

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&numAttributes=2

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&numAttributes=10&numAttributesWithValues=5

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&numValuesPerAttribute=3

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&showAllValuesForAttr=21885_resolution

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=sony&numCategories=2&groupItemsByCategory=true

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&numItems=2

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&showProductOffers=true

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&showProductOffers=true&numOffersPerProduct=3

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&showProductReviews=true&numReviewsPerProduct=3

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=96602&pageNumber=2

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=36406706&productReviewsPageNumber=2

Sorting

Sort results containing a mix of 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:

• 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.
• 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 (see Sort results containing only products and Sort results containing only offers).

<GeneralSearchRequest>
  <Sort>
    <hybridSortType>price</hybridSortType>
    <hybridSortOrder>asc</hybridSortOrder>
  </Sort>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=96602&hybridsorttype=price&hybridsortorder=asc

Sort results containing only products

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 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:

• 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.
• product-rating - The average rating (between 0 and 5) of the product based on reviews by Epinions members.
• price - The average price of the product.
• 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.

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

<GeneralSearchRequest>
  <Sort>
    <productSortType>price</productSortType>
    <productSortOrder>asc</productdSortOrder>
  </Sort>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=7185&productSortType=price&productSortOrder=asc

Sort results containing only 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:

• 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. The stores bid is used in the case of a list of offers for a single product, since all offers are equally relevant.
• 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 (see Set number of Featured Stores,) 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 (see Sort results containing only products and Sort results containing a mix of products and offers).

<GeneralSearchRequest>
  <Sort>
    <offerSortType>price</offerSortType>
    <offerSortOrder>asc</offerSortOrder>
  </Sort>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&categoryId=31515&offerSortType=price&offerSortOrder=asc

Set number of Featured Stores

When sorting a list of offers using the 'featured-store' sort type (see Sort results containing only offers), 3 featured stores are returned by default. To change the number of featured stores returned, use the 'numFeatured' parameter.

<GeneralSearchRequest>
  <Sort>
    <offerSortType>featured-store</offerSortType>
    <numFeatured>3</numFeatured>
  </Sort>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=40940649&offerSortType=featured-store&numFeatured=3

Include 'Smart Buy' offer

By enabling the 'showSmartBuy' parameter, the offer matching the Shopping.com 'Smart Buy' criteria (if one exists) will be marked as the 'smartBuy'. Additionally, if using the 'featured-store' sort type (see Sort results containing only offers), the Smart Buy will be moved to the first position below any featured offers.

<GeneralSearchRequest>
  <Sort>
    <showSmartBuy>true</showSmartBuy>
  </Sort>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=40940649&showSmartBuy=true

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=40940649&productReviewsSortType=product-rating&productReviewsSortOrder=asc

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&productId=40940649&postalCode=90210

Disable keyword normalization

By default, the SDC search engine may modify search phrases (keywords) to produce better results. These modifications include things such as spelling correction, stemming (e.g. removing pluralization), tokenization (e.g. D40 -> D 40), etc. It is recommended that you allow the SDC API/search engine to perform these normalization steps, as they are tuned to produce better results in almost all cases. However, if you would like to disable them, you can set the 'doKeywordNormalization' parameter to false.

<GeneralSearchRequest>
  <Options>
    <doKeywordNormalization>false</doKeywordNormalization>
  </Options>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=cannon&doKeywordNormalization=false

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=digital%20cameras&doSkipping=false

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=sony&groupItemsByCategory=true

Disable "Soft Productization"

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. If you would like to disable Soft Productization, and receive only offers in soft categories (i.e. no products), use the 'showSoftProducts' parameter.

<GeneralSearchRequest>
  <Options>
    <showSoftProducts>false</showSoftProducts>
  </Options>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=shoes&showSoftProducts=false

Include products without offers

By default, the SDC API will exclude products for which we have no store offers, even if those products are relevant to the search criteria, as partners usually cannot monetize those results. If you would like to include all products which match your search criteria, regardless of whether any store offers exist for those products, use the 'showProductsWithoutOffers' parameter.

<GeneralSearchRequest>
  <Options>
    <showProductsWithoutOffers>true</showProductsWithoutOffers>
  </Options>
</GeneralSearchRequest>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&trackingId=7000610&keyword=ipod%20mini%20gold&showProductsWithoutOffers=true

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/GeneralSearch?apiKey=authorized-key&showOffersOnly=true&trackingId=7000610&categoryId=7185

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/CategoryTree?apiKey=authorized-key&trackingId=7000610&categoryId=3

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>

API 3 REST query
http://sandbox.api.shopping.com/publisher/3.0/rest/CategoryTree?apiKey=authorized-key&trackingId=7000610&categoryId=3&showAllDescendants=true