Welcome, guest Sign In

Product Search API v3

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 API for merchant ratings and info, and Catalog Listing API for offers, reviews, and product specifications.

Request URL

http://shopping.yahooapis.com/ShoppingService/V3/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://shopping.yahooapis.com/ShoppingService/ V3/productSearch? appid=YahooDemo&query=erector

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

http://shopping.yahooapis.com/ShoppingService/ V3/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://shopping.yahooapis.com/ShoppingService/ V3/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://shopping.yahooapis.com/ShoppingService/ V3/productSearch?appid=YahooDemo& category=Video%20Games&query=Doom&results=20&start=21

Using Refinement Keys

A list of refinement keys is returned if there are refinements to return (setting the show_narrowing parameter to 0 excludes refinements from being returned). These values can be used in subsequent requests to further narrow your search. In the request below, two Refinement keys returned are Atari items, 4168-Brand=Atari, 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 Atari and Nintendo brand items will be searched:

http://shopping.yahooapis.com/ShoppingService/ V3/productSearch?appid=YahooDemo& category=All%20Video%20Games&query=Doom&refinement=4168-Brand=Atari&refinement=4168-Brand=Nintendo

Using Subcategories

A list of subcategories is returned if there are subcategories available (setting the show_narrowing parameter to 0 excludes subcategories from being returned). You can use these subcategories with the category parameter in subsequent requests to further narrow your search. This request yields a subcategory listing:

http://shopping.yahooapis.com/ShoppingService/V3/productSearch? appid=YahooDemo&category=All%20Video%20Games&query=Doom&results=20&

You can chose a subcategory from the response, for example, Xbox Games, to further refine your search:

http://shopping.yahooapis.com/ShoppingService/V3/productSearch? appid=YahooDemo&category=Xbox%20Games&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.
To return a list of the most popular products for Computers and Electronics categories, simply submit a query using the category parameter, without specifying a keyword for the query parameter.
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).
merchantid integer: default is no value If specified, the service will return only results offered by that merchant. The argument will be ignored if a non-numeric category (not beginning with 1can1) is specified.
refinement string Used only if category is specified. Category used should be from the Category element returned in the RefineValue node. Multiple refinement keys having the same category can be specified.
eg:
&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_narrowing 0 or 1 (default is 1) Set to 0 to exclude subcategory or refinement-narrowing options from results.
sort string: price_ascending,
price_descending,
userrating_ascending, or
userrating_descending		 By default, results are sorted by relevance. The sort argument gives you the option of sorting by price or user rating. To sort by user rating, you must specify a category that is non-numeric and not beginning with 1can1.
start integer: 1-300 default value is 1 The starting result position to return. The starting position cannot exceed 300.
output xml (default),
php,
json 		The format for the output. If output=json, the results will be returned in JSON format. If output=php, the results will be returned in Serialized PHP format.
callback string: default no value The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9. [] and _. If output=json has not been requested, this parameter has no effect. More information on the callback can be found in the Yahoo! Developer Network JSON Documentation.

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://shopping.yahooapis.com/shoppingservice/v3/productsearch.xsd

Top-Level Elements

Element Description
ProductSearch Top level container for all responses.
Categories Container for element SubCategory. Contains a list of subcategories. Returned only if subcategories are available (setting show_narrowing parameter to 0 will exclude subcategories from being returned). Details of each subcategory are provided below. Attributes:
  • total_subcategories: integer indicating total subcategories returned.
  • type: when type=can it is recommended to display subcategories below refinements.
Refinements Container for element Refinement. Returned only if there are available Refinements to return (setting show_narrowing parameter to 0 excludes refinements from being returned). 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.
  • totalAvailable: An attribute specifying the total number of values available for this refinement key. This attribute is set when the number of refinement values returned is less than the number of refinement values available for the refinement group. The last refinement value is More and its value can be used with the refinement flag to get more refinement values for this refinement group
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.

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.)
SubCategory Contains nested subcategories. Returned only if nested subcategories are available. Each SubCategory element has elements listed in this table.

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.
Category Contains the category, that should be used as a value for the category parameter in the API's URL, for this refinement to be applied.

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 Offer merchant comparison grid. Has the attribute ID for this catalog, which you can use to compare prices with the CatalogID parameter.
Category Contains the value for the catgory that the product belongs to.
CreateRatingUrl The Url to the page for posting reviews of this product on Yahoo! Shopping.
Department Contains the value for the department that the product belongs to. Has the attribute ID for this department, which you can use to get other products from the same department using the department parameter in the ProductSearch API.
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.
Model Contains the value for Model of the product.
NumOfStores Contains the value for number of stores offering the product.
NumRatings The number of users who have rated this product.
Part Number Contains the value for the Manufacturer Part Number of the 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
UPC Contains the value for UPC/ISBN number of the product.
Url The URL for the corresponding catalog page on Yahoo! Shopping.
UserRating Contains the user rating information for this item.

Offer Elements

Element Description
Average Rating A value from 1(worst) to 5 (best) representing the average rating given to this merchant by a user.
Category Contains the value for the category that the product belongs to.
Department Contains the value for department that the product belongs to. Has the attribute ID for this department, which you can use to get other products from the same department using the department parameter in the ProductSearch API.
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 merchant by a user.
Merchant An enclosing tag for information about the merchant making this offer. Has the attribute ID for this merchant, which you can use in Merchant Search.
Name Contains value for name of the merchant.
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.
RatingUrl The Url to the ratings page for this merchant on Yahoo! Shopping.
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 with category=Computers

Errors

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

Related Information

Rate Limits

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.

Terms of Use

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:

  • Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1) (for IE)
  • Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.1) Gecko/20060111 Firefox/1.5.0.1 (for FireFox)

If a valid user agent is not set, no results will be returned. A 400 HTTP status code will be returned, along with an error message indicating that the user agent is not valid.

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.

Support & Community

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

Ready to get started?

By applying for an Application ID for this service, you hereby agree to the Terms of Use

YDN LIBRARIES & BEST PRACTICES

YAHOO! APIs & WEB SERVICES

LANGUAGE CENTERS

Copyright © 2008 Yahoo! Inc. All rights reserved. Copyright | Privacy Policy

Help us continue to improve the Yahoo! Developer Network - Send Your Suggestions