Documentation for Yahoo! Shopping Web Services: Product Search

Support & Community

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

Request URL

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

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)	The query to search for.
results	integer: default 10, max 50	The number of results to return.
start	integer: default 1	The starting result position to return (1-based). The finishing position (start + results - 1) cannot exceed 300.
merchantid	integer: default no value	If specified, the service will only return results offered by that merchant.
highestprice	floating point number: default no value	The maximum price for returned results (in US dollars).
lowestprice	floating point number: default no value	The minimum price for returned results (in US dollars).
sort	relevance (default), or price	If price is specified, the results will be returned in ascending order of price. Otherwise, the most relevant results will be displayed first.
department	integer: default no value	The specific department of Yahoo! Shopping to search in. See Supported Department Codes.

Sample Request Url: http://api.shopping.yahoo.com/ShoppingService/v1/productSearch?appid=YahooDemo&query=ipod+shuffle

Response fields

The schema document for this service response is located at http://api.shopping.yahoo.com/shoppingservice/v1/productsearch.xsd

Field	Description
ResultSet	Contains all of the query responses. Has 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: This optional attribute is returned when common spelling mistakes are detected in the query (i.e. digital camera, which would prompt a suggested query of digital camera).
Result	Contains each individual product offering. A Result will either contain a Catalog or an Offer. Details for each of these types are listed below.

Field

Description

ResultSet

Contains all of the query responses. Has 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: This optional attribute is returned when common spelling mistakes are detected in the query (i.e. digital camera, which would prompt a suggested query of digital camera).

Result

Contains each individual product offering. A Result will either contain a Catalog or an Offer. Details for each of these types are listed below.

Catalog response fields

Field	Description
Catalog	Contains the data for a Yahoo! Shopping OfferCatalog Buyer's Guide. Has attributes: ID: The ID for this catalog for use in catalogListing.
Url	The URL for the corresponding catalog page on Yahoo! Shopping.
ProductName	The name 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.
Thumbnail	The URL of a product thumbnail image and its height and width in pixels.
Summary	A short description of the product.
Description	A longer description of the product.
UserRating	An enclosing tag for user rating information for this product.
MaxRating	A value from 1 (worst) to 5 (best) representing the maximum rating given to this product by a user.
NumRatings	The number of users who have rated this product.
AverageRating	A value from 1 (worst) to 5 (best) representing the average rating given to this product by a user.
RatingUrl	The Url to the ratings page for this product on Yahoo! Shopping.
CreateRatingUrl	The Url to the page for posting reviews of this product on Yahoo! Shopping.
SpecificationList	Contains product specifications in key/value pairs
Specification	Contains an individual key/value specification pair
SpecificationLabel	Contains the label for the specification.
SpecificationValue	Contains the value for the specification.

Offer response fields

Field	Description
Offer	Contains the data for an individual merchant offering of a product.
Url	The URL for the product page on the merchant site.
ProductName	The name of the product.
Price	Price of the product in US dollars.
Thumbnail	The URL of a product thumbnail image and its height and width in pixels.
Summary	A short description of the product.
Merchant	Contains the name of the merchant making this offer. Has attributes: ID: The ID for this merchant for use in merchantSearch.

Sample response

The following is a sample response for the query iPod Shuffle:

<?xml version="1.0"?>

<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:yahoo:prods" xsi:schemaLocation="urn:yahoo:prods http://api.shopping.yahoo.com/shoppingservice/v1/productsearch.xsd" totalResultsAvailable="1285" totalResultsReturned="5" firstResultPosition="1" grouping="none">

  <Result>

    <Catalog ID="1991675140">

      <Url><![CDATA[http://shopping.yahoo.com/p:Apple%20%3Chi%3EiPod%20shuffle%3C%2Fhi%3E%20512MB%20MP3%20Player:1991675140]]></Url>

      <ProductName><![CDATA[Apple iPod shuffle 512MB MP3 Player]]></ProductName>

      <PriceFrom>93.95</PriceFrom>

      <PriceTo>199.00</PriceTo>

      <Thumbnail>

        <Url><![CDATA[http://us.f3.yahoofs.com/shopping/2852419/catalog_t_t1991675140.1105478782.jpg?rm_____DT6GNuZKq]]></Url>

        <Height>70</Height>

        <Width>53</Width>

      </Thumbnail>

      <Description><![CDATA[Welcome to a life less orderly. As official soundtrack to the random revolution, the iPod Shuffle Songs setting takes you on a unique journey through your music collection - you never know what's around the next tune. Meet your new ride. More roadster than Rolls, iPod shuffle rejects routine by serving up your favorite songs in a different order every time. Just plug iPod shuffle into your computer's USB port, let iTunes Autofill it with up to 240 songs and get a new experience with every connection. The trail you run every day looks different with an iPod shuffle. Daily gridlock feels less mundane when you don't know what song will play next. iPod shuffle adds musical spontaneity to your life. Lose control. Love it.]]></Description>

      <Summary><![CDATA[Apple iPod - 512 MB - Audio Format: AAC, AIFF, MP3, WAV - Battery Life: 12 hour(s) - Weight: .78 oz ...]]></Summary>

      <UserRating>

        <MaxValue>5</MaxValue>

        <NumRatings>88</NumRatings>

        <AverageRating>4.3</AverageRating>

        <RatingUrl>http://shopping.yahoo.com/p:p:1991675140:page=user-reviews</RatingUrl>

        <CreateRatingUrl>http://shopping.yahoo.com/p:p:1991675140:page=post-reviews</RatingUrl>

      </UserRating>

      <SpecificationList>

        <Specification>

          <SpecificationLabel><![CDATA[Memory]]></SpecificationLabel>

          <SpecificationValue><![CDATA[512 MB]]></SpecificationValue>

        </Specification>

        <Specification>

          <SpecificationLabel><![CDATA[Supports]]></SpecificationLabel>

          <SpecificationValue><![CDATA[AAC, AIFF, MP3, WAV]]></SpecificationValue>

        </Specification>

        <Specification>

          <SpecificationLabel><![CDATA[Battery Life]]></SpecificationLabel>

          <SpecificationValue><![CDATA[12 hour(s)]]></SpecificationValue>

        </Specification>

      </SpecificationList>

    </Catalog>

  </Result>

  <Result>

    <Catalog ID="1991675141">

      <Url><![CDATA[http://shopping.yahoo.com/p:Apple%20%3Chi%3EiPod%20shuffle%3C%2Fhi%3E%201GB%20MP3%20Player:1991675141]]></Url>

      <ProductName><![CDATA[Apple iPod shuffle 1GB MP3 Player]]></ProductName>

      <PriceFrom>118.95</PriceFrom>

      <PriceTo>299.00</PriceTo>

      <Thumbnail>

        <Url><![CDATA[http://us.f3.yahoofs.com/shopping/2852419/catalog_t_t1991675140.1105478782.jpg?rm_____DT6GNuZKq]]></Url>

        <Height>70</Height>

        <Width>53</Width>

      </Thumbnail>

      <Description><![CDATA[Welcome to a life less orderly. As official soundtrack to the random revolution, the iPod Shuffle Songs setting takes you on a unique journey through your music collection - you never know what's around the next tune. Meet your new ride. More roadster than Rolls, iPod shuffle rejects routine by serving up your favorite songs in a different order every time. Just plug iPod shuffle into your computer's USB port, let iTunes Autofill it with up to 240 songs and get a new experience with every connection. The trail you run every day looks different with an iPod shuffle. Daily gridlock feels less mundane when you don't know what song will play next. iPod shuffle adds musical spontaneity to your life. Lose control. Love it.]]></Description>

      <Summary><![CDATA[Apple iPod - 1 GB - Audio Format: AAC, AIFF, MP3, WAV - Battery Life: 12 hour(s) - Weight: .78 oz ...]]></Summary>

      <UserRating>

        <MaxValue>5</MaxValue>

        <NumRatings>32</NumRatings>

        <AverageRating>3.6</AverageRating>

        <RatingUrl>http://shopping.yahoo.com/p:p:1991675141:page=user-reviews</RatingUrl>

        <RatingUrl>http://shopping.yahoo.com/p:p:1991675141:page=post-reviews</RatingUrl>

      </UserRating>

      <SpecificationList>

        <Specification>

          <SpecificationLabel><![CDATA[Memory]]></SpecificationLabel>

          <SpecificationValue><![CDATA[1 GB]]></SpecificationValue>

        </Specification>

        <Specification>

          <SpecificationLabel><![CDATA[Supports]]></SpecificationLabel>

          <SpecificationValue><![CDATA[AAC, AIFF, MP3, WAV]]></SpecificationValue>

        </Specification>

        <Specification>

          <SpecificationLabel><![CDATA[Battery Life]]></SpecificationLabel>

          <SpecificationValue><![CDATA[12 hour(s)]]></SpecificationValue>

        </Specification>

      </SpecificationList>

    </Catalog>

  </Result>

  <Result>

    <Offer>

      <Url><![CDATA[http://click.linksynergy.com/fs-bin/click?id=ho*WNHtxSqs&offerid=80498.10000517&type=3&subid=0]]></Url>

      <ProductName><![CDATA[iPod shuffle 512MB]]></ProductName>

      <Price>99.00</Price>

      <Thumbnail>

        <Url><![CDATA[http://us.f3.yahoofs.com/shopping/2855235/1021849_t_tstoreapplecomcatalogusimagesbeautyshotipodshuffle050111jpg.th?rm_____DCa0dGr.V]]></Url>

        <Height>70</Height>

        <Width>47</Width>

      </Thumbnail>

      <Merchant ID="1021849">

        <Name><![CDATA[Apple Store]]></Name>

      </Merchant>

    </Offer>

  </Result>

  <Result>

    <Offer>

      <Url><![CDATA[http://www.crutchfield.com/I-rYHOc7GE/cgi-bin/prodview.asp?i=4721GSHFL]]></Url>

      <ProductName><![CDATA[Apple iPod shuffle 1G 1GB]]></ProductName>

      <Price>129.00</Price>

      <Thumbnail>

        <Url><![CDATA[http://us.f3.yahoofs.com/shopping/2871724/1001222_t_takamaipixcrutchfieldcomproducts2005472l472512shflfjpeg.th?rm_____DA5yu9dYQ]]></Url>

        <Height>70</Height>

        <Width>54</Width>

      </Thumbnail>

      <Summary><![CDATA[1GB 1GB embedded memory, plays MP3, WAV, AAC, and Audible files, USB 2.0 interface, weighs 0.8 oz. (includes built-in rechargeable battery), earbud...]]></Summary>

      <Merchant ID="1001222">

        <Name><![CDATA[Crutchfield]]></Name>

      </Merchant>

    </Offer>

  </Result>

  <Result>

    <Offer>

      <Url><![CDATA[http://www.ecost.com/referrals/default.asp?dpno=188265&store=ecost&source=EWBYAHOO1]]></Url>

      <ProductName><![CDATA[NEW! iPod shuffle 512MB]]></ProductName>

      <Price>94.00</Price>

      <Thumbnail>

        <Url><![CDATA[http://us.f3.yahoofs.com/shopping/2855326/1017634_t_timage1ccinccomprod188000188266smjpg.th?rm_____Dt1AlTM8O]]></Url>

        <Height>70</Height>

        <Width>70</Width>

      </Thumbnail>

      <Summary><![CDATA[Time to mix things up. Meet iPod shuffle, the unpredictable new iPod. What will it play...]]></Summary>

      <Merchant ID="1020455">

        <Name><![CDATA[eCOST.com, Inc.]]></Name>

      </Merchant>

    </Offer>

  </Result>

</ResultSet>

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:

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)

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.

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.