Developer Network Home - Help

Documentation for Yahoo! Shopping Web Services: Product Search

Version 2Shopping Web Services : Product Search

Submitting Product Search Queries

The Product Search service allows you to search the Internet for product offerings from Yahoo! Shopping. See also the Merchant Search, Catalog Specs, Catalog Listing and User Product Review services.

Support & Community

The Product Search service is discussed on the yws-shopping mailing list.

Request URL

http://api.shopping.yahoo.com/ShoppingService/V2/productSearch

Summary

The Yahoo! Product Search web service lets you search for products through Yahoo! Shopping. The only required request parameters are your Yahoo! Application ID, and either a top level category name or query string. You can use YahooDemo as a sample application ID for testing. See Requesting an Application ID for information on requesting your own application ID.

You can search for items containing a specific keyword with the query parameter. The item's name and summary are searched:

http://api.shopping.yahoo.com/ShoppingService/ V2/productSearch? appid=YahooDemo&query=erector

You can search for items in a specific Top Level Product Category or subcategory using the category parameter:

http://api.shopping.yahoo.com/ShoppingService/ V2/productSearch? appid=YahooDemo&category=Video%20Games

The request must contain the query parameter or the category parameter, or both. If you leave off both the category and query parameters an error is returned.

Paginating Results

Your request may return a large number of items; use the results and start parameters to determine how many results you get back and from which result you want to start the display. By default, the response returns ten results, starting from result 1. The results parameter indicates how many product results to return. So, for example, to return twenty results per request, use this request:

http://api.shopping.yahoo.com/ShoppingService/ V2/productSearch?appid=YahooDemo& category=Video%20Games&query=Doom&results=20

Use the start parameter to start the block of results from some result number other than 1. So, for example, the previous request returned the first 20 product results. To get the next 20 in the list, use the start parameter with the value 21:

http://api.shopping.yahoo.com/ShoppingService/ V2/productSearch?appid=YahooDemo& category=Video%20Games&query=Doom&results=20&start=21

Using Refinement Keys

A list of refinement keys is returned if the category parameter is specified in your request and there are refinements to return. These values can be used in subsequent requests to further narrow your search. In the request above, two Refinement keys returned are Microsoft items, 4168-Brand=Microsoft, and Nintendo items, 4168-Brand=Nintendo. We can use these two refinements, and any others returned, in a new request to limit the search. In this case, only Microsoft and Nintendo brand items will be searched:

http://api.shopping.yahoo.com/ShoppingService/ V2/productSearch?appid=YahooDemo& category=Video%20Games&query=Doom&refinement=4168-Brand=Microsoft&refinement=4168-Brand=Nintendo

Using Subcategories

A list of subcategories is returned if you use the parameter show_subcategories=1 and there are subcategories to return. You can use these subcategories with the category parameter in subsequent requests to further narrow your search. This request yields a subcategory listing:

http://api.shopping.yahoo.com/ShoppingService/V2/productSearch? appid=YahooDemo&category=Video%20Games&query=Doom&results=20& show_subcategories=1

You can chose a subcategory from the response, for example, Video Game Accessories, to further refine your search:

http://api.shopping.yahoo.com/ShoppingService/V2/productSearch? appid=YahooDemo&category=Video%20Game%20Accessories&query=Doom

By default, requests return an XML document. See Response Elements for information on the elements contained in responses.

Request Parameters

See information on constructing REST queries

Parameter Value Description
appid string (required) The application ID. See Application IDs for more information.
query string (required if category is not specified) The query to search for.
category string or integer (required if query is not specified) Specifies the category to be searched. See the list of Top Level Categories available for use.
class string: catalogs, freeoffers, or paidoffers default: all three types Limits response to catalog listings (catalogs), free merchant listings (freeoffers), or paid merchant listings (paidoffers). You may also use the comma-separated list catalogs,paidoffers to return a combination of catalog and paidoffer listings.
department integer: default is no value Only used if the category parameter is NOT specified. The specific department of Yahoo! Shopping to search. See Supported Department Codes.
highestprice floating point number: default is no value The maximum price for returned items (in US dollars).
lowestprice floating point number: default is no value The minimum price for returned items (in US dollars).
max_refines integer: 0-2000 default value is 10 Only used if category is specified. Specifies the maximum number of refinement values, per refinement key, to be returned by the request.
merchantid integer: default is no value If specified, the service will only return results offered by this merchant. The argument will be ignored if a non-numeric category is specified.
refinement string Only used if category is specified. Refinement keys. Multiple refinement keys can be specified e.g. &refinement=4354-Brand=Dell&refinement=1234-Store=CompUsa
results integer: 1-50 default value is 10 The number of results to return.
show_numratings boolean: 0 or 1 default is 0 When set to 1, returns the number of ratings for each product (if available).
Caution: If set to 1, it will result in increased response time for your request.
show_subcategories boolean: 0 or 1 default is 0 When set to 1, returns subcategories (if any).
sort string: price_ascending,
price_descending,
userrating_ascending, or
userrating_descending		 Sort by price or user rating. If no sort is specified, results are sorted by relevancy. Note: Sorting by user rating, userrating_ascending or userrating_descending, will not have any effect unless a non-numeric category parameter is used.
start integer: 1-300 default value is 1 The starting result position to return. The starting position cannot exceed 300.

Sample Request Urls:

Response Elements

The Yahoo! Shopping Product Search REST response conforms to XML 1.0. The schema document for this response is located at http://api.shopping.yahoo.com/shoppingservice/v2/productsearch.xsd

Top-Level Elements

Element Description
ProductSearch Top level container for all responses.
Categories Container for element SubCategory
Contains a list of subcategories. Only returned if show_subcategories=1 is specified in the request and there are available subcategories to return. Details of each subcategory are provided below.
Attributes:
  • total_subcategories: integer indicating total subcategories returned.
Refinements Container for element Refinement
Each Refinement element contains a list of RefineValue elements. Only returned if category is specified in the request and there are available Refinements to return.
Attributes:
  • name: An attribute specifying the display name for the refinement key
  • totalvalues: An attribute specifying the number of values returned for this refinement key
Products

Container for element Product
Contains each individual product offering. (list of Product elements). Each Product element contains either a Catalog or an Offer element, and has an attribute named type to indicate whether the enclosed element is a Catalog or an Offer element.
Attributes:

  • totalResultsAvailable: The number of query matches in the database.
  • totalResultsReturned: The number of query matches returned. This may be lower than the number of results requested if there were fewer total results available.
  • firstResultPosition: The position of the first result in the overall search.
  • spellSuggestion: Returned when common spelling mistakes are detected in the query (i.e. digital camrea, which would prompt a suggested query of digital camera).
  • relatedSearches: This is a comma separated string of terms related to the query e.g. ipod mini,mini ipod,apple ipod,apple ipod mini,ipod 20gb for query=ipod . This attribute will appear if there are available related searches to return. If a non-numeric category is specified, relatedSearches will not appear.

SubCategory Elements

Element Description
Title Contains the display name for the subcategory.
NumberOfProducts Contains the number of products available for this subcategory
Value Contains the value for the subcategory that can be used as a value for the category request parameter. The value returned can be either numeric or non-numeric. (Numeric values signify departments, while non-numeric values signify subcategories.)

RefineValue Elements

Each Refinement element contains a list of RefineValue elements. Each RefineValue element may contain the following elements:

Element Description
Title Contains the display name for the Refinement.
NumberOfProducts Contains the number of products available for this Refinement.
Value Contains the value for the Refinement that can be used as a value for the refinement request parameter.

Catalog Elements

The Catalog elements describe an item.

Element Description
AverageRating A value from 1 (worst) to 5 (best) representing the average rating given to this product by a user.
Brand Contains the brand name of the product.
Catalog Contains the data for a Yahoo! Shopping OfferCatalog Buyer's Guide.

It has the attribute value:
CreateRatingUrl The Url to the page for posting reviews of this product on Yahoo! Shopping.
Description A longer description of the product.
GridImage Contains an image described by GridImage elements.
ListImage Contains an image described by ListImage elements.
MaxRating A value from 1 (worst) to 5 (best) representing the maximum rating given to this product by a user.
NumOfStores Contains the value for number of stores offering the product.
NumRatings The number of users who have rated this product.
PriceFrom The lowest price (in US dollars) for the product in this catalog.
PriceTo The highest price (in US dollars) for the product in this catalog.
ProductName The name of the product.
RatingUrl The Url to the ratings page for this product on Yahoo! Shopping.
SpecificationList Contains a list of Specification elements
Summary A short description of the product.
Thumbnail Contains an image described by Thumbnail elements
Url The URL for the corresponding catalog page on Yahoo! Shopping.
UserRating Contains the user rating information for this item.

Offer Elements

Element Description
GridImage Contains an image described by GridImage elements.
ListImage Contains an image described by ListImage elements.
Merchant Contains the name of the merchant making this offer.

It has the attribute value:

  • id: The ID for this merchant. Use this value to search using Merchant Search.
Offer Contains the data for an individual merchant offering of a product.
Price Price of the product in US dollars.
ProductName The name of the product.
Summary A short description of the product.
Thumbnail Contains an image described by Thumbnail elements.
Url The URL for the product page on the merchant site.

GridImage, ListImage, and Thumbnail Elements

GridImage, ListImage, and Thumbnail elements contain the details of an image.

Element Description
Url The URL link to the image.
Height The height of the image in pixels.
Width The width of the image in pixels.

UserRating Elements

Element Description
AverageRating The average rating of the item.
CreateRatingUrl A URL to the page to add ratings for the item.
MaxRating The highest rating for the item.
NumRating The total number of ratings for the item.
RatingUrl A URL to the ratings section of the item.

Specification Elements

Element Description
SpecificationLabel The name of a specification for an item. For example: Cable Type
SpecificationValue The value corresponding to SpecificationLabel. For example: Power Adapter

Sample Response

The following is a sample response for query=dell+6000 with category=Computers

Additional Terms of Service

When calling the shopping APIs, you must set the HTTP user agent to a valid web browser string. Bot and spider strings are not valid. The user agent can be set to some default value - it does not have to be changed based on the user's browser. Some examples are as follows:

More information on user agents can be found at http://en.wikipedia.org/wiki/user_agent.

For all Web sites and applications that present data from the Yahoo! Shopping API, the attribution text "Powered by Yahoo! Shopping" must be presented. You may link the attribution text back to the Yahoo! Shopping site.

Rate Limit

The Product Search service is a part of the Yahoo! Shopping Web Services, which are limited to 5,000 queries per appid per day. See information on rate limiting.

Errors

The Product Search service returns the standard errors. A 999 error is returned if the query limit has been exceeded.

Copyright © 2008 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings