Documentation for Yahoo! Shopping Web Services: Merchant Search

Support & Community

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

Request URL

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

Request parameters

See information on constructing REST queries

Parameter	Value	Description
appid	string (required)	The application ID. See Application IDs for more information.
merchantid	integer (required)	The merchant id to search for. You may submit multiple values as separate parameters `(e.g. merchantid=1021849&merchantid=1015600)`.
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 Url: http://api.shopping.yahoo.com/ShoppingService/v1/MerchantSearch?appid=YahooDemo&merchantid=1021849&merchantid=1015600

Response fields

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

Field	Description
MerchantResultSet	Contains all of the query responses (one per merchantid submitted). `
Merchant	Contains data for each individual merchant. Has attributes: ID: The ID for this merchant.
Name	The name of the merchant.
Rating	An enclosing tag for user 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.
OverallRating	A value from 1 (worst) to 5 (best) representing the average rating given to this merchant by a user.
PriceSatisfactionRating	A value from 1 (worst) to 5 (best) representing the average rating based on satisfaction with merchant pricing.
ShippingOptionsRating	A value from 1 (worst) to 5 (best) representing the average rating based on satisfaction with merchant shipping options.
TimelyDeliveryRating	A value from 1 (worst) to 5 (best) representing the average rating based on satisfaction with merchant delivery fulfillment.
EaseOfPurchaseRating	A value from 1 (worst) to 5 (best) representing the average rating based on satisfaction with the buying experience.
CustomerServiceRating	A value from 1 (worst) to 5 (best) representing the average rating based on satisfaction with merchant customer service.
RatingUrl	The URL to the ratings and reviews overview page for this merchant on Yahoo! Shopping.
InfoUrl	The URL for further information about this merchant on Yahoo! Shopping.
IsCertifiedMerchant	A Boolean indicating whether the merchant has been certified by Yahoo! Shopping's Buyer Protection program.

Sample response

The following is a sample response for a query for merchants 1015600 (WalMart) and 1021849 (The Apple Store):


<?xml version="1.0" encoding="ISO-8859-1"?>

<MerchantResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:yahoo:merchinfo" xsi:schemaLocation="urn:yahoo:merchinfo http://api.shopping.yahoo.com/shoppingservice/v1/merchantsearch.xsd">

<Merchant ID="1015600">

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

<Rating>

<MaxRating>5</MaxRating>

<NumRatings>643</NumRatings>

<OverallRating>3.7</OverallRating>

<PriceSatisfactionRating>3.9</PriceSatisfactionRating>

<ShippingOptionsRating>3.5</ShippingOptionsRating>

<TimelyDeliveryRating>3.6</TimelyDeliveryRating>

<EaseOfPurchaseRating>3.8</EaseOfPurchaseRating>

<CustomerServiceRating>3.7</CustomerServiceRating>

<RatingUrl>http://shopping.yahoo.com/merchrating/user_rv.html?merchant_id=1015600</RatingUrl>

</Rating>

<IsCertifiedMerchant>true</IsCertifiedMerchant>

<InfoUrl>http://shopping.yahoo.com/stores/minfo.html?mid=1015600</InfoUrl>

</Merchant>

<Merchant ID="1021849">

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

<Rating>

<MaxRating>5</MaxRating>

<NumRatings>44</NumRatings>

<OverallRating>4.2</OverallRating>

<PriceSatisfactionRating>3.8</PriceSatisfactionRating>

<ShippingOptionsRating>4.3</ShippingOptionsRating>

<TimelyDeliveryRating>4.3</TimelyDeliveryRating>

<EaseOfPurchaseRating>4.2</EaseOfPurchaseRating>

<CustomerServiceRating>4.3</CustomerServiceRating>

<RatingUrl>http://shopping.yahoo.com/merchrating/user_rv.html?merchant_id=1021849</RatingUrl>

</Rating>

<IsCertifiedMerchant>true</IsCertifiedMerchant>

<InfoUrl>http://shopping.yahoo.com/stores/minfo.html?mid=1021849</InfoUrl>

</Merchant>

</MerchantResultSet>

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 Merchant 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 Merchant Search service returns the standard errors. A 999 error is returned if the query limit has been exceeded.