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 service. You can also search by UPC, ISBN, or a combination of Brand and Manufacturer Part number. See also the Merchant Search service.
The Catalog Listing service is discussed on the yws-shopping mailing list.
http://shopping.yahooapis.com/ShoppingService/V2/catalogListing
See information on constructing REST queries
| Parameter | Value | Description |
|---|---|---|
| appid | string (required) | The application ID. See Application IDs for more information. |
| 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.
|
| catalogid |
integer (required if idtype,idvalue not specified)
|
The ID of the Yahoo! Shopping Buyers Guide catalog, as derived from
a Catalog in a Product Search. You may submit up to 5 Catalog IDs at a time for side-by-side product comparisons. |
| getlisting | 0 or 1 (default) |
When set to 0, merchant listings related to product identified by the
given catalogid OR (idtype-idvalue) combination, will
not be returned. By default, (if not specified, or when value=1), merchant
listings related to this product will be returned.
|
| getreview | 0 (default) or 1 |
When set to 1, returns user reviews related to product identified by
the given catalogid OR (idtype-idvalue) combination.
|
| getspec | 0 (default) or 1 |
When set to 1, returns specs (image, prices etc.) related to product
identified by the given catalogid OR (idtype-idvalue)
combination.
|
| idtype |
upc brand,model brand,partnum (to specify ISBN use upc) (required if catalogid not specified) |
To be used in combination with idvalue for specifying a product.
Used to specify a key/key-combination (among the ones supported) for specifying
a product. e.g. &idtype=upc
|
| idvalue |
integer: no default (required if catalogid not specified)
|
To be used in combination with idtype, for specifying a product.
Used to specify a value for the key/key-combinations used in idtype,
for specifying a product. Values for key-combination (only supported values)
should be comma separated. Order should be maintained in idtype,
idvalue if key-combination is used. e.g. &idvalue=0439784549 (with &idtype=upc)
Results will only be returned if an exact product match is found using the idtype, idvalue combination. For books, music, and
video products we recommend using ISBN and UPC values. For Computers
& Electronics products, we recommend using Brand & Manufacturer
Part # values for the greatest coverage.
|
| 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 items are displayed. |
| 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.
|
| reviewstart | integer: default 1 |
The starting position to return reviews(1-based). The number of the finishing position is (reviewstart + reviewresults - 1).
|
| reviewresults | integer: range 1-100, default 10 | The number of reviews to return. |
| reviewsort |
string:
|
Sort reviews based on three criteria:
|
| zip | string (5 digits) | The zip code being ordered from (for calculating shipping and taxes if possible). |
Sample request URLs:
The schema document for this service response is located at http://shopping.yahooapis.com/shoppingservice/v2/cataloglisting.xsd
| Field | Description |
|---|---|
| Catalogs | Top-level container for all responses. |
| Catalog |
Container for all elements (Offers, Reviews, Specs)
related to a Catalog. Attributes:
|
| Offers |
Container for a list of Offer elements. Details of each Offer element
are provided below. Attributes:
|
| Reviews |
Container for a list of Review elements. Returned only if getreview
is specified in the request with value set to 1 and there are available
Reviews to return. Details of each Review element are provided
below. Attributes:
|
| Specs | Container enclosing all specifications returned for the product. Returned only if getspec is specified in the request with value set to 1 and there are available Specs to return. The spec elements returned are described below. |
| Field | Description |
|---|---|
| Offer | Contains each individual product offering. |
| Merchant |
Required when presenting a subset of the merchants selling a product. Has attributes:
|
| Rating | An enclosing tag for rating information for this merchant. |
| MaxRating | A value from 1 (worst) to 5 (best) representing the maximum rating given to this merchant by a user. |
| NumRatings | The number of users who have rated this merchant. |
| AverageRating | A value from 1 (worst) to 5 (best) representing the average rating given to this merchant by a user. |
| NumReviews | The number of reviews available for this merchant. |
| RatingUrl | The Url to the ratings and reviews overview page for this merchant on Yahoo! Shopping. |
| CreateRatingUrl | The Url to the page for posting reviews of this merchant on Yahoo! Shopping. |
| Url | The URL of the product page on the merchant site. |
| 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. |
| Image | The URL of the product's image and its height and width in pixels, as supplied by the merchant. Use in combination with merchant offer when Image is not available in the Specs. |
| DisplayMerchant |
String used to properly display merchant. IMPORTANT: This string can include straight text or image source code when the merchant requires a logo to be displayed. This field is required when presenting a traditional comparison grid. Use the Merchant field when presenting a subset of merchants selling a given product. |
| Field | Description |
|---|---|
| Review | Contains each individual review. |
| Title | The title of the review as entered by the reviewer. |
| Reviewer | The name or Yahoo! ID that the reviewer chose to call them self. |
| CreateTime | The UNIX time when the review was written |
| HelpfulRecommendations | The number of people who found this review helpful |
| TotalRecommendations | The total number of people who have read this review. |
| Ratings | Container for sub-ratings / detailed components of the user review. |
| Rating | Sub-rating for detailed component of the user reivew. Has an attribute ratingType, which specifies the name of the sub-rating component |
| OverallRatings | The rating given by the reviewer for the product, out of 5. |
| Pro | The pros (positive attributes) of the product as per the reviewer. |
| Con | The cons (negative attributes) of the product as per the reviewer. |
| Posting | The body of the review. |
| Field | Description |
|---|---|
| MinPrice | The lowest price (in US dollars) for the product in this catalog. |
| MaxPrice | The highest price (in US dollars) for the product in this catalog. |
| Thumbnail | The URL of a product's thumbnail image and its height and width in pixels. |
| Image | The URL of a product's image and its height and width in pixels. |
| LargeImage | The URL of a product's Large image and its height and width in pixels. |
| ProductName | Title of the product |
| Description | A description of the product. |
| SpecificationList | Contains product specifications in label/value pairs. |
| Specification | Contains an individual label/value specification pair |
| SpecificationLabel | Contains the label for the specification |
| SpecificationValue | Contains the value for the specification. |
| 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. |
The following is a sample response for the query 1991675140, the ID for the Yahoo! Shopping Buyer's Guide for the iPod Shuffle:
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:
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.
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.
The Catalog Listing 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