Documentation for Yahoo! Shopping Web Services: Catalog Listing

Support & Community

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

Request URL

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

Request parameters

See information on constructing REST queries

Parameter	Value	Description
appid	string (required)	The application ID. See Application IDs for more information.
catalogid	integer (required)	The ID of the Yahoo! Shopping Buyers Guide catalog, as derived from a Catalog in a Product Search.
upc	string: default no value	The UPC code of the product to search for. This can be useful for disambiguating books/CDs/DVDs, etc.
zip	integer or <integer>-<integer>	The zip code being ordered from (for calculating shipping and taxes if possible).
onlynew	1 (default) or 0	If set to 0, the search will also display used or refurbished items along with new items. By default, only new item are displayed.
start	integer: default 1	The starting result position to return (1-based). The number of the finishing position is (start + results - 1).
results	integer:: default no value (returns all)	The number of results to return.

Sample Request Url: http://api.shopping.yahoo.com/ShoppingService/v1/CatalogListing?appid=YahooDemo&catalogid=1991675140&zip=95127

Response fields

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

Field	Description
CatalogListing	Contains all of the query responses. Has attributes: ID: The ID of this catalog. zip: The zip code specified for shipping data, if provided. numOffers: The number of offers in the catalog.
Offer	Contains each individual product offering.
Merchant	Contains the name of the merchant making this offer. Has attributes: ID: The ID for this merchant for use in merchantSearch.
Url	The URL for the corresponding offer page on Yahoo! Shopping.
Condition	The condition of the product, if known.
BasePrice	Price of the product in dollars from this merchant, not including tax and shipping.
TaxCost	If the zip parameter was provided, the taxes on the product, if available.
ShippingCost	If the zip parameter was provided, the cost of shipping, if available.
TotalPrice	Price of the product in dollars from this merchant, including tax and shipping if known.
StrikeThroughPrice	Price of the product suggested by the merchant as the original retail price. This price can be used as a "strikethrough" to indicate savings.

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"?>

<CatalogListing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:yahoo:merchoffers" xsi:schemaLocation="urn:yahoo:merchoffers http://api.shopping.yahoo.com/shoppingservice/v1/cataloglisting.xsd" ID="1991675140" zip="95127" numOffers="18">

  <Offer>

    <Merchant ID="1006427">

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

    </Merchant>

    <Url><![CDATA[http://store.yahoo.com/acsestore/apipshm951di.html]]></Url>

    <Condition>new</Condition>

    <TaxCost>0.00</TaxCost>

    <ShippingCost>11.00</ShippingCost>

    <BasePrice>94.99</BasePrice>

    <TotalPrice>105.99</TotalPrice>

    <StrikeThroughPrice>94.99</StrikeThroughPrice>

  </Offer>

  <Offer>

    <Merchant ID="1000027">

      <Name><![CDATA[Amazon.com]]></Name>

    </Merchant>

    <Url><![CDATA[http://www.amazon.com/exec/obidos/ASIN/B0002ZAILY/yahooce-20/ref=nosim]]></Url>

    <Condition>new</Condition>

    <BasePrice>99.99</BasePrice>

    <TotalPrice>99.99</TotalPrice>

    <StrikeThroughPrice>99.99</StrikeThroughPrice>

  </Offer>

  <Offer>

    <Merchant ID="1000422">

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

    </Merchant>

    <Url><![CDATA[http://www.newegg.com/Product/Product.asp?Item=N82E16855101412&ATT=iPod+Players+Accesso&CMP=OTC-yah00TT]]></Url>

    <Condition>new</Condition>

    <TaxCost>8.33</TaxCost>

    <ShippingCost>1.99</ShippingCost>

    <BasePrice>97.99</BasePrice>

    <TotalPrice>108.31</TotalPrice>

    <StrikeThroughPrice>97.99</StrikeThroughPrice>

  </Offer>

  <Offer>

    <Merchant ID="1001082">

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

    </Merchant>

    <Url><![CDATA[http://s0b.bluestreak.com/ix.e?dpc&s=256832&a=184861&d=564899&url=http%3A%2F%2Fwww%2Ecompusa%2Ecom%2Fproducts%2Fproduct%5Finfo%2Easp%3Fref%3Dyahoo%26pfp%3Dyahoo%26product%5Fcode%3D318368]]></Url>

    <Condition>new</Condition>

    <ShippingCost>5.00</ShippingCost>

    <BasePrice>99.99</BasePrice>

    <TotalPrice>104.99</TotalPrice>

    <StrikeThroughPrice>99.99</StrikeThroughPrice>

  </Offer>

  <Offer>

    <Merchant ID="1001222">

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

    </Merchant>

    <Url><![CDATA[http://www.crutchfield.com/I-rYHOc7GF/cgi-bin/prodview.asp?i=472512SHFL]]></Url>

    <Condition>new</Condition>

    <TaxCost>0.00</TaxCost>

    <ShippingCost>5.99</ShippingCost>

    <BasePrice>99.00</BasePrice>

    <TotalPrice>104.99</TotalPrice>

    <StrikeThroughPrice>99.00</StrikeThroughPrice>

  </Offer>

</CatalogListing>

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

Errors

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