Catalog Listing API v2

Submitting Catalog Price Queries

The Catalog Listing service allows you to display price, user review, and specification information for offers aggregated as Buyer's Guides by Yahoo! Shopping, in particular those identified by a Catalog ID via the Product Search API. You can also search by UPC, ISBN, or a combination of Brand and Manufacturer Part number. See also the Merchant Search API.

Request URL

http://shopping.yahooapis.com/ShoppingService/V2/catalogListing

Request parameters

See information on constructing REST queries

Sample request URLs:

• Get Merchant Listings, Specs for catalogid:1991675140, with the tax-shipping info for the zip:95127
  http://shopping.yahooapis.com/ShoppingService/v2/CatalogListing?appid=YahooDemo&
  catalogid=1991675140&zip=95127&getspec=1
• Get Merchant Listings, Specs for Canon SD600 using idtype,idvalue
  http://shopping.yahooapis.com/ShoppingService/v2/CatalogListing?appid=YahooDemo&
  &idtype=brand,partnum&idvalue=canon,1079B001&getspec=1
• Get user reviews for product with catalogid=1991675140
  http://shopping.yahooapis.com/ShoppingService/v2/CatalogListing?appid=YahooDemo&
  &catalogid=1991675140&getlisting=0&getreview=1&reviewstart=1&reviewresults=20
• Get specs for multiple products (max:5) for side-by-side comparision
  http://shopping.yahooapis.com/ShoppingService/v2/CatalogListing?appid=YahooDemo&
  &catalogid=1994289313,1994287117&getlisting=0&getspec=1
• Get output in serialzed php format
  http://shopping.yahooapis.com/ShoppingService/v2/CatalogListing?appid=YahooDemo&
  &catalogid=1994289313&output=php
• Get output in json format
  http://shopping.yahoo.com/ShoppingService/v2/CatalogListing?appid=YahooDemo&
  &catalogid=1994289313&output=json&callback=your_call_back_function_name

Response Elements

The schema document for this service response is located at http://shopping.yahooapis.com/shoppingservice/v2/cataloglisting.xsd

Top Level Elements

Offer Elements

Product Review Elements

Product Specification Elements

Sample response

The following is a sample response for the query 1991675140, the ID for the Yahoo! Shopping Buyer's Guide for the iPod Shuffle:

<?xml version="1.0" encoding="utf-8"?> <Catalogs xmlns="urn:yahoo:merchoffers" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:yahoo:merchoffers http://shopping.yahooapis.com/shoppingservice/v2/cataloglisting.xsd"> <Catalog ID="1991675140" zip="95127"> <Offers totalOffers="4"> <Offer> <Merchant ID="1017152"> <Name>Gizmos2G0.com</Name> <Rating> <MaxRating>5</MaxRating> <NumRatings>149</NumRatings> <AverageRating>4.3</AverageRating> <NumReviews>128</NumReviews> <RatingUrl>http://shopping.yahoo.com/merchrating/user_rv.html?merchant_id=1017152</RatingUrl> <CreateRatingUrl>http://shopping.yahoo.com/merchrating/mr_write.html?merchant_id=1017152</CreateRatingUrl> </Rating> </Merchant> <Url>http://www.gizmos2go.com/xcart/home.php?cat=1598</Url> <Condition>new</Condition> <Tax>0.06</Tax> <ShippingCost>12.00</ShippingCost> <Price>68.88</Price> <TotalPrice>80.94</TotalPrice> <StrikeThroughPrice>68.88</StrikeThroughPrice> <Image> <Url>http://f3c.yahoofs.com/shopping/mcid9_187579/simg_t_t84958494jpg70?rm_____DjcqQg619</Url> <Height>70</Height> <Width>70</Width> </Image> <DisplayMerchant>Gizmos2G0.com</DisplayMerchant> </Offer> <Offer> <Merchant ID="1027274"> <Name>Musicians Friend</Name> <Rating> <MaxRating>5</MaxRating> <NumRatings>12</NumRatings> <AverageRating>3.0</AverageRating> <NumReviews>11</NumReviews> <RatingUrl>http://shopping.yahoo.com/merchrating/user_rv.html?merchant_id=1027274</RatingUrl> <CreateRatingUrl>http://shopping.yahoo.com/merchrating/mr_write.html?merchant_id=1027274</CreateRatingUrl> </Rating> <Logo> <Url>http://f3c.yahoofs.com/productsubmit/b8c26/productsubmit_t_2566763.png?ss_____DdZDOJ.d5</Url> <Height>31</Height> <Width>88</Width> </Logo> </Merchant> <Url>http://na.link.decdna.net/n/3815/3816/www.musiciansfriend.com/5cc831c30025030000001f8c0000a12b0f25d0190000000000000000000000000000000100/i/c?0&pq=%2fproduct%2fApple%2d512MB%2diPod%2dshuffle%2d%3fsku%3d240574%26src%3d00633</Url> <Condition>new</Condition> <Price>69.00</Price> <TotalPrice>69.00</TotalPrice> <StrikeThroughPrice>69.00</StrikeThroughPrice> <Image> <Url>http://f3c.yahoofs.com/shopping/mcid2_69877/simg_t_t240574223295jpg70?rm_____DG8wmV1tK</Url> <Height>70</Height> <Width>54</Width> </Image> <DisplayMerchant>Musicians Friend</DisplayMerchant> </Offer> <Offer> <Merchant ID="1053780"> <Name>Best Electronics Disconut</Name> <Rating> <MaxRating>5</MaxRating> <NumRatings>0</NumRatings> <AverageRating>0.0</AverageRating> <NumReviews>0</NumReviews> <RatingUrl>http://shopping.yahoo.com/merchrating/user_rv.html?merchant_id=1053780</RatingUrl> <CreateRatingUrl>http://shopping.yahoo.com/merchrating/mr_write.html?merchant_id=1053780</CreateRatingUrl> </Rating> </Merchant> <Url>http://www.bestelectronicsdiscount.com/product_info.php?products_id=932</Url> <Condition>new</Condition> <Price>41.42</Price> <TotalPrice>41.42</TotalPrice> <StrikeThroughPrice>41.42</StrikeThroughPrice> <DisplayMerchant>Best Electronics Disconut</DisplayMerchant> </Offer> <Offer> <Merchant ID="1053776"> <Name>Best Electronics Disconut</Name> <Rating> <MaxRating>5</MaxRating> <NumRatings>0</NumRatings> <AverageRating>0.0</AverageRating> <NumReviews>0</NumReviews> <RatingUrl>http://shopping.yahoo.com/merchrating/user_rv.html?merchant_id=1053776</RatingUrl> <CreateRatingUrl>http://shopping.yahoo.com/merchrating/mr_write.html?merchant_id=1053776</CreateRatingUrl> </Rating> </Merchant> <Url>http://www.bestelectronicsdiscount.com/product_info.php?products_id=932</Url> <Condition>new</Condition> <Price>41.42</Price> <TotalPrice>41.42</TotalPrice> <StrikeThroughPrice>41.42</StrikeThroughPrice> <DisplayMerchant>Best Electronics Disconut</DisplayMerchant> </Offer> </Offers> <Reviews firstReviewPosition="1" totalReviewsAvailable="113" totalReviewsReturned="10"> <Review> <Title>Apple does it again</Title> <Reviewer>legstrong6</Reviewer> <CreateTime>1109216252</CreateTime> <HelpfulRecommendations>90</HelpfulRecommendations> <TotalRecommendations>102</TotalRecommendations> <Ratings> <Rating ratingType="Features">4</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">5</Rating> <Rating ratingType="Support">5</Rating> <Rating ratingType="Value">5</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>Small, lightweight, value, easy to use, stylish</Pro> <Con>No screen</Con> <Posting>It&#39;s small, lightweight, best value, easy to use and stylish. It keeps the iPod appeal but is a lot cheaper that the other ones. If you don&#39;t have a whole lot of music to fill the other iPods, which was my problem, you don&#39;t have to worry anymore. Get it.</Posting> </Review> <Review> <Title>Shuffle a good value</Title> <Reviewer>intelligentbricks</Reviewer> <CreateTime>1111511446</CreateTime> <HelpfulRecommendations>37</HelpfulRecommendations> <TotalRecommendations>41</TotalRecommendations> <Ratings> <Rating ratingType="Features">4</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">5</Rating> <Rating ratingType="Support">4</Rating> <Rating ratingType="Value">5</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>10 years ago this technology would have cost thousands and would have been worth it</Pro> <Con>inability to pick and choose songs or ablums to play, lack of availability of accessories</Con> <Posting>I recently purchased an ipod shuffle 512M to wear on the jobsite (construction). One of the reasons I bought the &quot;shuffle&quot; is that it is likely to be damaged at work and I didn&#39;t want to be out the $300 of an iPod Mini. So far, I am very happy with it. It may be lacking some of the features compared to the more extravagent (and expensive) MP3&#39;s, but compared to the old portable CD players or walkmen, you cannot go wrong. <br> <br>I have been able to put around 14 CDs of music on it. There are two ways to play the music: straight through in the order it was put on the playlist (itunes) or randomly in a &quot;shuffle&quot; mode. I&#39;ve played it both ways and am very happy with the ipod Shuffle. <br> <br>The battery life is excellent- so far I&#39;ve been able to play the ipod all day long without the battery indicator light even changing from green to amber or red. <br> <br>In Summary: Yes the Shuffle is &quot;cheap&quot; but it seems well made like all apple products. It&#39;s lightweight and tiny. It holds more music than one can listen to at a time, and at $99 how can you go wrong? <br> <br>Some day, all ipods will be this small.</Posting> </Review> <Review> <Title>shuffle</Title> <Reviewer>wenzel_t</Reviewer> <CreateTime>1110401005</CreateTime> <HelpfulRecommendations>19</HelpfulRecommendations> <TotalRecommendations>22</TotalRecommendations> <Ratings> <Rating ratingType="Features">5</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">5</Rating> <Rating ratingType="Support">5</Rating> <Rating ratingType="Value">5</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>light, compact, good sound quality, sleek, outstanding bat. life</Pro> <Con>no lcd</Con> <Posting>absolutly amazing. I use it for running. I run about 30-45 miles a week . so i run daily and i have only had to recharge the bat once. When im running i never hear the same song twice. Although i dont use the earbuds while running because they fall out, so i use the sony wraparound style head phones. Its light and i can hold it in my hand and its like its not even there. Its truely an amazing piece of technology that i would recomend.</Posting> </Review> <Review> <Title>More fun than it&#39;s size?</Title> <Reviewer>boozybaby224</Reviewer> <CreateTime>1110400731</CreateTime> <HelpfulRecommendations>16</HelpfulRecommendations> <TotalRecommendations>19</TotalRecommendations> <Ratings> <Rating ratingType="Features">2</Rating> <Rating ratingType="Overall">4</Rating> <Rating ratingType="Quality">4</Rating> <Rating ratingType="Support">4</Rating> <Rating ratingType="Value">3</Rating> </Ratings> <OverallRating>4</OverallRating> <Pro>Small, portable, light, and &quot;cute&quot;</Pro> <Con>No screen, hard to find the right song</Con> <Posting>I would definitely say that this mp3 player is more fun than a pack of gum, however, it is not the right item for someone who wants to hold a ton of songs for the following reasons: the most it can hold is 120 songs and it has no screen or play list so it is difficult to find the song you are looking for. I would suggest this item to someone who enjoys listening to dance music because of it is light weight and can be put on a wristband or necklace. Overall, it is not as good as the iPod mini however it is easier to jog with and definitely &quot;cuter&quot;. I would highly recommend it!</Posting> </Review> <Review> <Title>Great Little Item</Title> <Reviewer>rdog28</Reviewer> <CreateTime>1109602632</CreateTime> <HelpfulRecommendations>13</HelpfulRecommendations> <TotalRecommendations>13</TotalRecommendations> <Ratings> <Rating ratingType="Features">4</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">5</Rating> <Rating ratingType="Support">5</Rating> <Rating ratingType="Value">5</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>size, portability, ease of use, quick transfer rate</Pro> <Con>Display</Con> <Posting>This is a great MP3 player. I bought it for my girlfriend and now I want one for myself. It is very easy to use. Install the iTunes software, plug the MP3 player into a USP port and you&#39;re up and running. I wasn&#39;t familiar with iTunes and thought I had to use only music purchased from Apple, but quickly realized I could rip tracks from existing CDs...quickly and easily. <br>This is a must have if you want a small player for the gym or if you commute and don&#39;t need thousands of songs. I highly recommend the Shuffle.</Posting> </Review> <Review> <Title>Teeny little enabler</Title> <Reviewer>codemartial</Reviewer> <CreateTime>1132443611</CreateTime> <HelpfulRecommendations>11</HelpfulRecommendations> <TotalRecommendations>11</TotalRecommendations> <Ratings> <Rating ratingType="Features">4</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">5</Rating> <Rating ratingType="Value">4</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>Small and hassle free</Pro> <Con>Limited playlist functionality</Con> <Posting>I got an iPod Shuffle 512MB from my employer this summer and I must say, it&#39;s been great :-) <br> <br>The audio quality is reasonably good, though the earphones aren&#39;t extra-ordinary and occasionally tend to slip out. Such players should come with Bluetooth wireless headphones instead. <br> <br>It&#39;s quite conventient to use the controls and due to their contours, I can keep the player in my back-pocket and use the right control just by feeling it. <br> <br>The only problem is with playlist functionality. Though it&#39;s easy to switch between sequential or random modes, and select next/previous songs, there&#39;s no way to find a song since there&#39;s no screen. It allows jumping to the beginning of the playlist but that requires some funky combination of control-presses, which I can&#39;t remember. <br> <br>All in all, it&#39;s a good thing and thanks to it I&#39;ve been walking longer distances, more frequently, for the joy of listening to music on the move.</Posting> </Review> <Review> <Title>Big & Little</Title> <Reviewer>mrcsbrooks@sbcglobal.net</Reviewer> <CreateTime>1110329807</CreateTime> <HelpfulRecommendations>9</HelpfulRecommendations> <TotalRecommendations>9</TotalRecommendations> <Ratings> <Rating ratingType="Features">3</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">5</Rating> <Rating ratingType="Support">4</Rating> <Rating ratingType="Value">5</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>Size and its easy to use!</Pro> <Con>So easy to use it leaves it with very few features.</Con> <Posting>Overall the ishuffle serves it&#39;s purpose. It&#39;s an mp3 player for the people who dont need to load up alot of songs, but enough for a day on the road, it&#39;s inexpensive, but once you get the acccesories for it your pockets will ache a lil bit. But overall it worth it, all of the complaints about it not having a screen, DUH! It&#39;s called an ishuffle, the point is to have a random array of songs so you dont know whats next, or what to expect. If a display is a BIG issue, than save a LITTLE more and you can have it!- PEACE & HAIRGREASE!!!</Posting> </Review> <Review> <Title>Music fuss-free on the go</Title> <Reviewer>joy_squeak</Reviewer> <CreateTime>1109389176</CreateTime> <HelpfulRecommendations>8</HelpfulRecommendations> <TotalRecommendations>8</TotalRecommendations> <Ratings> <Rating ratingType="Features">4</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">5</Rating> <Rating ratingType="Support">5</Rating> <Rating ratingType="Value">5</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>Small, serves as thumb drive for storing data, no frills and easy to use.</Pro> <Con>hard to search for songs</Con> <Posting>On the whole this serves as a great companion whenever I&#39;m travelling. it&#39;s so small it fits into my pocket easily and doesn&#39;t add a load in the bag as well. Although there&#39;s no display to search for songs loaded in it, the ipod shuffle is what i&#39;ll call a back-to-basics mp3 player, sp easy to use even the elderly won&#39;t find it a chore to use. <br> <br>The main reason i bought it was so I could have a thumb drive as well, when i can bring work home in my shuffle. It makes more sense having an mp3 player that serves that purpose as well. <br> <br>The best thing about this? When i run after the bus, there&#39;s no skipping of tracks! a smooth trip all the way. <br> <br>I love my ipod shuffle!</Posting> </Review> <Review> <Title>great</Title> <Reviewer>grayfoxx91@sbcglobal.net</Reviewer> <CreateTime>1122326278</CreateTime> <HelpfulRecommendations>7</HelpfulRecommendations> <TotalRecommendations>9</TotalRecommendations> <Ratings> <Rating ratingType="Features">3</Rating> <Rating ratingType="Overall">5</Rating> <Rating ratingType="Quality">4</Rating> <Rating ratingType="Support">3</Rating> <Rating ratingType="Value">5</Rating> </Ratings> <OverallRating>5</OverallRating> <Pro>great sound, fairly cheap, and good quality</Pro> <Con>no screan to veiw your songs. although thats why its called a ipod shuffle</Con> <Posting>its a cheap alternative to the more expensive models from apple. its good quality and sound make it a great MP3 player</Posting> </Review> <Review> <Title>shuffle</Title> <Reviewer>kimberly_willows</Reviewer> <CreateTime>1115775572</CreateTime> <HelpfulRecommendations>2</HelpfulRecommendations> <TotalRecommendations>3</TotalRecommendations> <Ratings> <Rating ratingType="Features">2</Rating> <Rating ratingType="Overall">2</Rating> <Rating ratingType="Quality">3</Rating> <Rating ratingType="Support">1</Rating> <Rating ratingType="Value">2</Rating> </Ratings> <OverallRating>2</OverallRating> <Pro>small, lightweight</Pro> <Con>hard to download anything</Con> <Posting>I found that this is really hard to set-up. I have tried form two computers and I have now given it to a friend to try.It&#39;s inexpensive but I can&#39;t use t so so far it&#39;s a waste of money.</Posting> </Review> </Reviews> <Specs> <MinPrice>41.42</MinPrice> <MaxPrice>69.00</MaxPrice> <Thumbnail> <Url>http://f3c.yahoofs.com/shopping/mcid2_17104/simg_t_tcatalog_l_t19916751401105478782jpg85?rm_____Dy10zfXDq</Url> <Height>85</Height> <Width>65</Width> </Thumbnail> <Image> <Url>http://f3c.yahoofs.com/shopping/mcid2_17104/simg_t_mcatalog_l_t19916751401105478782jpg175?rm_____DZ1sDiQ9p</Url> <Height>175</Height> <Width>133</Width> </Image> <LargeImage> <Url>http://f3c.yahoofs.com/shopping/mcid2_17104/simg_t_ocatalog_l_t19916751401105478782jpg?rm_____D7V1Y7neP</Url> <Height>500</Height> <Width>381</Width> </LargeImage> <ProductName>Apple iPod shuffle 512MB MP3 Player</ProductName> <Description>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.<br></Description> <SpecificationList> <Specification> <SpecificationLabel>Product Line</SpecificationLabel> <SpecificationValue>iPod shuffle</SpecificationValue> </Specification> <Specification> <SpecificationLabel>Supported Memory</SpecificationLabel> <SpecificationValue>Integrated</SpecificationValue> </Specification> </SpecificationList> <UserRating> <MaxRating>5</MaxRating> <NumRatings>702</NumRatings> <AverageRating>4.2</AverageRating> <RatingUrl>http://shopping.yahoo.com/p:Apple%20iPod%20shuffle%20512MB%20MP3%20Player:1991675140:page=user-reviews</RatingUrl> <CreateRatingUrl>http://shopping.yahoo.com/p:Apple%20iPod%20shuffle%20512MB%20MP3%20Player:1991675140:page=post-reviews</CreateRatingUrl> </UserRating> </Specs> </Catalog> </Catalogs>

Errors

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

Related Information

Rate Limits

The Catalog Listing 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.

Support & Community

The Catalog Listing service is discussed on the yws-shopping mailing list.