getBestMatchItemDetails

Deprecation Notice

Beginning January 1, 2013, the Best Match Item Details API will no longer be available. eBay sellers will continue to have access to information about listing performance via the eBay Listing Analytics tool. If your application currently supports the Best Match Item Details API, please direct your users to eBay's Listing Analytics tool instead.

This call helps sellers understand how their item listings are performing and how they are ranked in search results sorted by Best Match. Input an itemId value for each item you want to inspect. Only valid for the site on which the item is listed. Thus, the call cannot be used for half.com items. And since the BestMatchItemDetails API is available only on the US site, the call cannot be used for international items.

The response contains the following data that sellers can use to rate the performance and Best Match placement of the specified items:

Best Match—Best Match data is returned for an item only if the item was listed by the authorized user of the BestMatchItemDetails call. Best Match data, among other things, includes an impression count range and a sales-per-impression value. The fields in the bestMatchData container list some of the values that eBay uses to determine the Best Match sorting order.
Item Ranking—The results for each item include itemRank and itemRankWithinGroup fields. The values of these fields show where your item is placed in search results, and where it lands when compared to other items within the same group (the groups being Featured or Best Match). With this call, items are ranked in relation to the other items returned in the call.
Quantity Sold—Search results also return QuantitySold and QuantityAvailable fields. The QuantitySold value (when combined with the item impression counts) plays a roll in how the item is sorted by Best Match.

getBestMatchItemDetails Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

getBestMatchItemDetails Output

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<getBestMatchItemDetailsResponse xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <!-- Call-specific Output Fields -->
  <item> BestMatchSearchItem (SearchItem)
    <autoPay> boolean </autoPay>
    <bestMatchData> BestMatchData
      <freeShipping> boolean </freeShipping>
      <impressionCountRange> LongRange
        <max> long </max>
        <min> long </min>
      </impressionCountRange>
      <salesCount> int </salesCount>
      <salesPerImpression> double </salesPerImpression>
      <salesPerViewItem> double </salesPerViewItem>
      <viewItemCount> int </viewItemCount>
      <viewItemPerImpression> double </viewItemPerImpression>
      <watchCount> int </watchCount>
    </bestMatchData>
    <charityId> string </charityId>
    <country> token </country>
    <galleryPlusPictureURL> anyURI </galleryPlusPictureURL>
    <!-- ... more galleryPlusPictureURL values allowed here ... -->
    <galleryURL> anyURI </galleryURL>
    <globalId> token </globalId>
    <itemId> string </itemId>
    <itemRank> int </itemRank>
    <itemRankWithinGroup> int </itemRankWithinGroup>
    <listingInfo> ListingInfo
      <bestOfferEnabled> boolean </bestOfferEnabled>
      <buyItNowAvailable> boolean </buyItNowAvailable>
      <buyItNowPrice currencyId="string"> Amount (double) </buyItNowPrice>
      <convertedBuyItNowPrice currencyId="string"> Amount (double) </convertedBuyItNowPrice>
      <endTime> dateTime </endTime>
      <gift> boolean </gift>
      <listingType> token </listingType>
      <startTime> dateTime </startTime>
    </listingInfo>
    <location> string </location>
    <paymentMethod> token </paymentMethod>
    <!-- ... more paymentMethod values allowed here ... -->
    <postalCode> string </postalCode>
    <primaryCategory> Category
      <categoryId> string </categoryId>
      <categoryName> string </categoryName>
    </primaryCategory>
    <productId type="string"> ProductId (string) </productId>
    <quantityAvailable> int </quantityAvailable>
    <quantitySold> int </quantitySold>
    <secondaryCategory> Category
      <categoryId> string </categoryId>
      <categoryName> string </categoryName>
    </secondaryCategory>
    <sellingStatus> SellingStatus
      <bidCount> int </bidCount>
      <convertedCurrentPrice currencyId="string"> Amount (double) </convertedCurrentPrice>
      <currentPrice currencyId="string"> Amount (double) </currentPrice>
      <sellingState> token </sellingState>
      <timeLeft> duration </timeLeft>
    </sellingStatus>
    <shippingInfo> ShippingInfo
      <shippingServiceCost currencyId="string"> Amount (double) </shippingServiceCost>
      <shippingType> token </shippingType>
      <shipToLocations> string </shipToLocations>
      <!-- ... more shipToLocations values allowed here ... -->
    </shippingInfo>
    <storeInfo> Storefront
      <storeName> string </storeName>
      <storeURL> anyURI </storeURL>
    </storeInfo>
    <subtitle> string </subtitle>
    <title> string </title>
    <viewItemURL> anyURI </viewItemURL>
  </item>
  <!-- ... more item nodes allowed here ... -->
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage
    <error> ErrorData
      <category> ErrorCategory </category>
      <domain> string </domain>
      <errorId> long </errorId>
      <exceptionId> token </exceptionId>
      <message> string </message>
      <parameter name="string"> ErrorParameter (string) </parameter>
      <!-- ... more parameter values allowed here ... -->
      <severity> ErrorSeverity </severity>
      <subdomain> string </subdomain>
    </error>
    <!-- ... more error nodes allowed here ... -->
  </errorMessage>
  <timestamp> dateTime </timestamp>
  <version> string </version>
</getBestMatchItemDetailsResponse>

Return Value	Type	Occurrence	Meaning

Call-specific Output Fields [Jump to standard fields]

item	BestMatchSearchItem (SearchItem)	Always, repeatable: [1..*]	Container for the details of an item returned from the search query.
item.autoPay	boolean	Always	If true, the seller requests immediate payment for the item. If false (or not specified), immediate payment is not requested. If true, it does not indicate that the item is still a candidate for purchase via immediate payment, however it does indicate the original status of the item listing. Only applicable to items listed on PayPal-enabled sites and in categories that support immediate payment (see AutoPayEnabled in GetCategories). In addition, the seller must have a Premier or Business PayPal account (see PayPalAccountType in GetUser) and they must accept PayPal as a payment method (see item.paymentMethod). See the eBay Web Services guide section on Requiring Immediate Payment for additional requirements and dependencies. Also see the section on working with the eBay Motors site for additional rules. Not applicable to Half.com.
item.bestMatchData	BestMatchData	Conditionally	Container for the best match data for the item. This data is returned only for items that belong to the authorized caller; the service does not return Best Match data for items that were not listed by the caller of the function.
item.bestMatchData .freeShipping	boolean	Conditionally	If true, the item is considered a free shipping item by BestMatch.
item.bestMatchData .impressionCountRange	LongRange	Conditionally	Total number of times the item surfaced on a search results page. The impression count is returned as a range.
item.bestMatchData .impressionCountRange.max	long	Conditionally	Maximum impression range value.
item.bestMatchData .impressionCountRange.min	long	Conditionally	Minimum impression range value.
item.bestMatchData.salesCount	int	Conditionally	Number of item sales. Note that a single sale can include one or more items.
item.bestMatchData .salesPerImpression	double	Conditionally	Ratio of sale transactions to the mid-point (between the minimum and maximum number) of the impression range. Note that the number of items sold can exceed the number of transactions (sales) if a single sale has an item quantity greater than one. An "impression" is any time a buyer sees a search results page that includes the listing. Impression counts can be greater than unique item views. Note that salesPerImpression impacts Best Match results for only Fixed Price items.
item.bestMatchData .salesPerViewItem	double	Conditionally	Ratio of sales to unique views of the item.
item.bestMatchData .viewItemCount	int	Conditionally	Number of unique item views.
item.bestMatchData .viewItemPerImpression	double	Conditionally	Ratio of unique item-views to the mid-point of the impression range. An "impression" is any time a buyer sees a search results page that includes the listing whereas "unique views" counts each user only once.
item.bestMatchData.watchCount	int	Conditionally	Number of watches placed on the item.
item.charityId	string	Conditionally	A unique identification number assigned by eBay to registered nonprofit charity organizations. Not returned if the item is not listed as a charity item.
item.country	token	Always	Two-letter ISO 3166 country code to indicate the country where the item is located. For English names that correspond to each code (e.g., KY="Cayman Islands"), see the ISO site: http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html.
item.galleryPlusPictureURL	anyURI	Conditionally, repeatable: [0..*]	URL for the Gallery Plus image. The size of Gallery Plus images (up to 400 x 400 pixels) is bigger than the size of standard gallery images. In site search results, you can view the Gallery Plus image by hovering over or clicking the Enlarge link or magifying glass icon. The image uses one of the following graphics formats: JPEG, BMP, TIFF, or GIF. This field is only returned when the seller has opted for the Gallery Plus option for the given item.
item.galleryURL	anyURI	Conditionally	URL for the picture used for the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image.
item.globalId	token	Always	A token that represents the eBay site on which the item was originally listed. For example, if the item was listed on the eBay US site, the value is US. If item was listed on the eBay Germany site, the value is DE. For a list of possible enumeration values and how they map to eBay sites, see Global ID Values. Where the item was listed can affect the values of converted (localized) prices. This occurs when the site from which your request is sent is different from the site on which the item was listed.
item.itemId	string	Always	An identification number that uniquely identifies a listed item. eBay generates this ID when an item is listed and the ID is unique across all eBay sites.
item.itemRank	int	Always	Absolute rank of the item, across the groups, in relation to all returned items.
item.itemRankWithinGroup	int	Always	Rank of the item in relation to the other returned items in the same group. Item groups are Featured and Best Match. For media items, groups can be Brand New, Like New, Very Good, Good, and Acceptable.
item.listingInfo	ListingInfo	Always	Container for listing information related to the item. The information includes the item's listing format (online auction, fixed price, and so on), if Buy It Now is enabled, and more.
item.listingInfo .bestOfferEnabled	boolean	Always	Shows whether or not the seller will accept a Best Offer for the associated item. Best Offer allows a buyer to make a lower-priced binding offer on a fixed price item. Buyers cannot see how many offers have been made (only the seller can see this information). Buyers must use the eBay Web site to make a Best Offer.
item.listingInfo .buyItNowAvailable	boolean	Always	Used with competitive-bid auctions, the associated item includes a Buy It Now option if this value returns true. Buy It Now lets a user purchase the item at a fixed price, effectively ending the auction. On most sites, the Buy It Now option is removed (and this value returns false) once a valid bid is made on the associated item (a valid bid could be a bid above the reserve price).
item.listingInfo.buyItNowPrice	Amount (double)	Always	The Buy It Now Price of the item (if any), in the currency of the site on which the item was listed. You can use this field to determine if the item was originally listed with Buy It Now, even if the Buy It Now option is no longer available for the item. Only returned if an item was listed with Buy It Now.
item.listingInfo.buyItNowPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
item.listingInfo .convertedBuyItNowPrice	Amount (double)	Always	The listing's Buy It Now Price (if any), converted into the currency of the site to which you sent your search request. For active items, refresh this value every 24 hours to pick up possible changes in conversion rates. Price fields are returned as doubles, and not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. Only returned if an item was listed with Buy It Now.
item.listingInfo .convertedBuyItNowPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
item.listingInfo.endTime	dateTime	Always	Time stamp specifying when the listing is scheduled to end, or the actual end time if the item listing has ended. This value is returned in GMT, the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format, and for details on converting to and from the GMT time zone. Note: For items that are "Good Till Canceled," this value is 5 minutes later than the actual end time of the item. This difference in time is intended to facilitate the renewal of these items' end times (which occurs every 30 days).
item.listingInfo.gift	boolean	Always	If true, a small gift icon displays next the listing's title in search and browse pages.
item.listingInfo.listingType	token	Always	The format of the listing, such as online auction, fixed price, or advertisement. listingType values: AdFormat Advertisement to solicit inquiries on listings such as real estate. Permits no bidding on the item, service, or property. To express interest, a buyer fills out a contact form that eBay forwards to the seller as a lead. This format does not enable buyers and sellers to transact online through eBay and eBay Feedback is not available for AdFormat listings. Auction Competitive-bidding online auction format. Buyers engage in competitive bidding, although Buy It Now may be offered as long as no valid bids have been placed. Online auctions are listed on eBay.com; they can also be listed in a seller's eBay Store if the seller is a Store owner. AuctionWithBIN Same as Auction format, but Buy It Now is enabled. AuctionWithBIN changes to Auction if a valid bid has been placed on the item. Valid bids include bids that are equal to or above any specified reserve price. Classified Classified Ads connect buyers and sellers, who then complete the sale outside of eBay. This format does not enable buyers and sellers to transact online through eBay and eBay Feedback is not available for these listing types. FixedPrice A fixed-price listing. Auction-style bidding is not enabled. On some sites, this auction format is also known as "Buy It Now Only" (do not confuse this with the Buy It Now option available on competitive-bidding auctions). Fixed-price listings appear on eBay.com and they can be listed in a seller's eBay Store (if the seller is a Store owner). StoreInventory A fixed-price format for eBay Store sellers. Store Inventory listings appear after other listings in regular search and browse pages on eBay. Store items have a lower Insertion Fee and longer listing durations. This selling type can only be specified by sellers who have an eBay Store. Store Inventory listings are listed on eBay.com as well as in the seller's eBay Store.
item.listingInfo.startTime	dateTime	Always	Time stamp that eBay recorded as the moment the listing was made available. This value is returned in GMT, the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format and for details on converting to and from the GMT time zone.
item.location	string	Always	Physical location of the item, as specified by the seller. (This gives a general indication of from where the item will be shipped or delivered.)
item.paymentMethod	token	Always, repeatable: [1..*]	Identifies the payment method(s) the seller will accept from the buyer. An example is PayPal. Note: If the seller accepts only PayPal, the buyer can still pay with a credit card. PayPal supports major credit cards. Payment methods are not applicable to eBay Real Estate advertisement listings or other Classified Ad format listings.
item.postalCode	string	Conditionally	The postal code of where the item is located. Not returned if seller did not specify their postal code.
item.primaryCategory	Category	Always	Container for the numeric ID and name of the first (or only) category in which the item is listed. Note that listings can appear in more than a single category.
item.primaryCategory .categoryId	string	Always	The unique ID of a category on the specified eBay site.
item.primaryCategory .categoryName	string	Always	Display name of a category as it appears on the eBay Web site. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks).
item.productId	ProductId (string)	Conditionally	Product ID type and product ID code if the item is a catalogue item. Not returned if the item is not listed as a product.
item.productId [ attribute type ]	string	Conditionally	Specifies or returns the product type and product ID. productId types: ReferenceID The global reference ID (ePID) for an eBay catalog product. A reference ID is a fixed reference to a product, regardless of version. Use FindProducts in the Shopping API to determine valid ePID values that you can use as input to findItemsByProduct. Each product in the response includes its reference ID. ISBN ISBN-10 or ISBN-13 value for books. (The string length of ProductID indicates whether the ID is 10 or 13 characters.) If you know a book's ISBN, you can use this instead of the eBay Reference ID to search for that book. Max length of corresponding value: 13 UPC UPC value for products in Music (e.g., CDs), DVDs & Movies, and Video Games categories (or domains). If you know a product's UPC, you can use this instead of the eBay Reference ID to search for that product. Max length of corresponding value: 12 EAN EAN value for books. (This is used more commonly in European countries.) If you know a book's EAN, you can use this instead of the eBay Reference ID to search for that book. Max length of corresponding value: 13 For example: To search using an ISBN, specify productID.type=ISBN and set productID.value to an ISBN value. To search using an eBay Product Reference ID, specify productID.type=ReferenceID and set productID.value to an eBay Product Reference ID (ePID) value. If you do not know the eBay Product Reference ID of a product, use the Shopping FindProducts call to retrieve the desired ePID value.
item.quantityAvailable	int	Always	Quantity of available items in the listing.
item.quantitySold	int	Always	Number of listing items sold.
item.secondaryCategory	Category	Conditionally	Container for the numeric ID and name of the second category in which the item is listed, if the seller listed in a secondary category.
item.secondaryCategory .categoryId	string	Conditionally	The unique ID of a category on the specified eBay site.
item.secondaryCategory .categoryName	string	Conditionally	Display name of a category as it appears on the eBay Web site. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks).
item.sellingStatus	SellingStatus	Always	Signifies the listing's selling status in eBay's processing workflow.
item.sellingStatus.bidCount	int	Conditionally	The number of bids that have been placed on the item. Returned only if the selling format is an auction.
item.sellingStatus .convertedCurrentPrice	Amount (double)	Always	The listing's current price converted to the currency of the site from which the request is sent (the request's globalId value).
item.sellingStatus .convertedCurrentPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
item.sellingStatus .currentPrice	Amount (double)	Always	The current price of the item given in the currency of the site on which the item is listed. That is, currentPrice is returned in the original listing currency. For competitive-bid item listings, currentPrice is the current minimum bid price if the listing has no bids, or the current high bid if the listing has bids. A Buy It Now price has no effect on currentPrice. For Basic Fixed-Price (FixedPrice), Store Inventory (StoreInventory), and Ad Format (AdFormat) listings, currentPrice is the current fixed price.
item.sellingStatus .currentPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
item.sellingStatus .sellingState	token	Always	Specifies the listing's status in eBay's processing workflow. If an item's EndTime is in the past, but there are no details about the buyer or high bidder (and the user is not anonymous), you can use sellingState information to determine whether eBay has finished processing the listing. sellingState values: Active The listing is still live. It is also possible that the auction has recently ended, but eBay has not completed the final processing (e.g., the high bidder is still being determined). Canceled The listing has been canceled by either the seller or eBay. Ended The listing has ended and eBay has completed the processing of the sale (if any).
item.sellingStatus.timeLeft	duration	Always	Time left before the listing ends. The duration is represented in the ISO 8601 duration format (PnYnMnDTnHnMnS). For listings that have ended, the time left is PT0S (zero seconds). See the "duration" type for information about this time format.
item.shippingInfo	ShippingInfo	Always	Container for information about the listing's shipping details.
item.shippingInfo .shippingServiceCost	Amount (double)	Conditionally	The basic shipping cost of the item. Not returned if the shipping method is calculated or free.
item.shippingInfo .shippingServiceCost [ attribute currencyId ]	string	Conditionally	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
item.shippingInfo.shippingType	token	Always	The shipping method that was used for determining the cost of shipping. For example: flat rate, calculated, or free. The seller specifies the available shipping services when they list the item. shippingType values: Calculated The calculated shipping model: The posted cost of shipping is based on the buyer-selected shipping service, chosen by the buyer from the different shipping services offered by the seller. The shipping costs are calculated by eBay and the shipping carrier, based on the buyer's address. Any packaging and handling costs established by the seller are automatically rolled into the total. CalculatedDomesticFlatInternational The seller specified one or more calculated domestic shipping services and one or more flat international shipping services. Flat The flat-rate shipping model: The seller establishes the cost of shipping and any shipping insurance, regardless of what any buyer-selected shipping service might charge the seller. FlatDomesticCalculatedInternational The seller specified one or more flat domestic shipping services and one or more calculated international shipping services. Free Free is used when the seller has declared that shipping is free for the buyer. FreePickup No shipping available, the buyer must pick up the item from the seller. Freight The freight shipping model: the cost of shipping is determined by a third party, FreightQuote.com, based on the buyer's address (postal code). FreightFlat The flat rate shipping model: the seller establishes the cost of freight shipping and freight insurance, regardless of what any buyer-selected shipping service might charge the seller. NotSpecified The seller did not specify the shipping type.
item.shippingInfo .shipToLocations	string	Conditionally, repeatable: [0..*]	An international location or region to which the seller is willing to ship the item. Returned only for items that have shipToLocations specified. For a complete list of shipping locations, see shipToLocations.
item.storeInfo	Storefront	Conditionally	Container for information about the eBay store in which the item was listed. Not returned if the item is not listed in an eBay store.
item.storeInfo.storeName	string	Conditionally	The name of the seller's eBay Store.
item.storeInfo.storeURL	anyURI	Conditionally	The URL of the eBay Store page.
item.subtitle	string	Conditionally	Subtitle of the item. Only returned if the seller included a subtitle with the listing.
item.title	string	Always	Name of the item listing as it appears in search and browse results.
item.viewItemURL	anyURI	Always	The URL to view this listing on eBay. This URL is optimized to support natural search. That is, this URL is designed to make items on eBay easier to find via popular Internet search engines. Specifically, the URL specifies the item title and it is optimized for natural search: " _W0QQ" is like "?" (question mark), "QQ" is like "&" (ampersand), and "Z" is like "=" (equals sign). Do not modify the returned URL syntax in your application. For example, eBay won't recognize the URL if you change QQ to ?. In the Sandbox environment and on the Hong Kong site (site ID 201), the data returned in this field is a standard ViewItem URL, rather than the ViewItem URL for Natural Search that is normally returned in the Production environment.

Standard Output Fields

ack	AckValue	Always	Indicates whether or not the request was successful, or if errors or warnings were generated during the processing of the request. Applicable values: • Failure eBay encountered a fatal error during the processing of the request, causing the request to fail. When a serious application-level error occurs, the error is returned instead of the business data. • PartialFailure eBay successfully processed the request, but one or more non-fatal errors occurred during the processing. For best results, requests should return without warning messages. Inspect the message details and resolve any problems before resubmitting the request. • Success eBay successfully processed the request and the business data is returned in the response. Note that it is possible for a response to return Success, but still not contain the expected data in the result. • Warning The request was successfully processed, but eBay encountered a non-fatal error during the processing. For best results, requests should return without warnings. Inspect the warning details and resolve the problem before resubmitting the request.
errorMessage	ErrorMessage	Conditionally	Description of an error or warning that occurred when eBay processed the request. Not returned if the ack value is Success.
errorMessage.error	ErrorData	Conditionally, repeatable: [0..*]	Details about a single error.
errorMessage.error.category	ErrorCategory	Conditionally	There are three categories of errors: Request errors, Application errors, and System errors. Applicable values: • Application An error occurred due to a problem with the request, with the most likely source being the application sending the request. For example, the request is missing a required data element or it contains an invalid field. The problem must be corrected before the request can be resent. Inspect the error message to find the cause of the problem. If the problem is due to an application error, modify the application and resend the request. If the error is due to invalid data, the source of the data must be corrected before you resend the resend request to eBay. • Request An error occurred due to a problem with the request, with the most likely source being missing or invalid data in the request. The problem must be corrected before the request can be retried. Inspect the error message to find the cause of the problem. If the problem is a result of end-user data, alert the end-user to the problem and provide the means for them to correct the problem. Once the problem is resolved, resend the request to eBay. • System Indicates that an error has occurred on the eBay system side. For example, a database or server could be down. Inspect the error message to find the cause of the problem. If the problem is on the eBay side, an application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form.
errorMessage.error.domain	string	Conditionally	Name of the domain in which the error occurred. domain values: Marketplace A business or validation error occurred in the Merchandising Service. SOA An exception occurred in the Service Oriented Architecture (SOA) framework.
errorMessage.error.errorId	long	Conditionally	A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.
errorMessage.error.exceptionId	token	Conditionally	Unique identifier for an exception associated with an error.
errorMessage.error.message	string	Conditionally	A detailed description of the condition that caused in the error.
errorMessage.error.parameter	ErrorParameter (string)	Conditionally, repeatable: [0..*]	Various warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error.
errorMessage.error.parameter [ attribute name ]	string	Conditionally	The name of the input parameter returned with the error. Inspecting the parameter (or its input value) will often aid in understanding the cause of the error. Not all error messages contain this value.
errorMessage.error.severity	ErrorSeverity	Conditionally	Indicates whether the reported problem is fatal (an error) or is less severe (a warning). Review the error message details for information on the cause. If the request fails and the application is the source of the error (for example, a required element is missing), update the application before you retry the request. If the problem is due to incorrect user data, alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, re-send the request to eBay. If the source of the problem is on eBay's side, you can retry the request a reasonable number of times (eBay recommends you try the request twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, you can resend the request in its original form. If a warning occurs, warning information is returned in addition to the business data. Normally, you do not need to resend the request (as the original request was successful). However, depending on the cause of the warning, you might need to contact the end user, or eBay, to effect a long term solution to the problem. Applicable values: • Error eBay encountered a fatal error during the processing of the request, causing the request to fail. When eBay encounters an error, it returns error data instead of the requested business data. Inspect the error details and resolve the problem before resubmitting the request. • Warning The request was successfully processed, but eBay encountered a non-fatal error during the processing that could affect the data returned. For example, eBay might have changed the value of an input field. In this case, eBay returns a successful response, but it also returns a warning. For best results, requests should return without warnings. Inspect the warning details and resolve the problem before resubmitting the request.
errorMessage.error.subdomain	string	Conditionally	Name of the subdomain in which the error occurred. subdomain values: Search The error is specific to the search services. MarketplaceCommon The error is common to all Marketplace services.
timestamp	dateTime	Always	This value represents the date and time when eBay processed the request. This value is returned in GMT, the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format, and for details on converting to and from the GMT time zone.
version	string	Always	The release version that eBay used to process the request. Developer Technical Support may ask you for the version value if you work with them to troubleshoot issues. Note: The version in use is normally the latest release version, as specified in the release notes. Note that eBay releases the API to international sites about a week after the API version is released to the US site.

getBestMatchItemDetails Detail Controls

Detail Control: DetailLevel

This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.

getBestMatchItemDetails Samples

New to making API calls? Please see Making an API Call.

Note: Some data in these samples might no longer be active. If necessary, you can substitute current data in your requests.

Sample: Basic

A basic call that retrieves two item listings.

Description

To review the Best Match information on two items, the seller uses this call to retrieve the specific items in which they are interested. Best Match information is returned for each item where the autorization token matches the seller's User Name.

Input

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<getBestMatchItemDetailsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <itemId>13474073440</itemId>
  <itemId>23484479761</itemId>
</getBestMatchItemDetailsRequest>

Output

XML format. Also available is the .txt version of this XML.

<getBestMatchItemDetailsResponse xmlns:ms="http://www.ebay.com/marketplace/services"
    xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <ack>Success</ack>
  <version>1.1.0</version>
  <timestamp>2009-10-22T19:00:33.594Z</timestamp>
  <item>
    <itemId>13474073440</itemId>
    <title>Canon EOS Digital Rebel XTi 10.1 Megapixel</title>
    <globalId>EBAY-US</globalId>
    <primaryCategory>
      <categoryId>162045</categoryId>
      <categoryName>Camera-Specific</categoryName>
    </primaryCategory>
    <secondaryCategory>
      <categoryId>31388</categoryId>
      <categoryName>Digital Cameras</categoryName>
    </secondaryCategory>
    <galleryURL>http://thumbs.ebaystatic.com/pict/12047734408080_1.jpg</galleryURL>
    <viewItemURL>http://cgi.ebay.com/Canon-EOS-Digital-Rebel-XTi-10-1-
        Megapixel_W0QQitemZ120474073440QQcmdZViewItemQQptZDigital_Cameras?
        hash=item1c0cd07960</viewItemURL>
    <productId type="ReferenceID">55528673</productId>
    <paymentMethod>PayPal</paymentMethod>
    <autoPay>false</autoPay>
    <postalCode>95125</postalCode>
    <location>San Jose,CA,USA</location>
    <country>US</country>
    <shippingInfo>
      <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
      <shippingType>Free</shippingType>
      <shipToLocations>US</shipToLocations>
    </shippingInfo>
    <sellingStatus>
      <currentPrice currencyId="USD">1400.0</currentPrice>
      <convertedCurrentPrice currencyId="USD">1400.0</convertedCurrentPrice>
      <bidCount>0</bidCount>
      <sellingState>Active</sellingState>
      <timeLeft>P0DT3H30M16S</timeLeft>
    </sellingStatus>
    <listingInfo>
      <bestOfferEnabled>false</bestOfferEnabled>
      <buyItNowAvailable>true</buyItNowAvailable>
      <buyItNowPrice currencyId="USD">1500.0</buyItNowPrice>
      <convertedBuyItNowPrice currencyId="USD">1500.0</convertedBuyItNowPrice>
      <startTime>2009-10-20T22:30:49.000Z</startTime>
      <endTime>2009-10-27T22:30:49.000Z</endTime>
      <listingType>AuctionWithBIN</listingType>
      <gift>false</gift>
    </listingInfo>
    <itemRank>1</itemRank>
    <itemRankWithinGroup>1</itemRankWithinGroup>
    <quantityAvailable>1</quantityAvailable>
    <quantitySold>0</quantitySold>
    <bestMatchData>
      <freeShipping>true</freeShipping>
      <impressionCountRange>
        <min>25001</min>
        <max>50000</max>
      </impressionCountRange>
      <salesCount>0</salesCount>
      <viewItemCount>399</viewItemCount>
      <watchCount>5</watchCount>
      <salesPerImpression>0.0</salesPerImpression>
      <salesPerViewItem>0.0</salesPerViewItem>
      <viewItemPerImpression>0.01064</viewItemPerImpression>
    </bestMatchData>
  </item>
  <item>
    <itemId>23484479761</itemId>
    <title>Canon SD950is 12.1 MP + 8GB Card, Open Box</title>
    <globalId>EBAY-US</globalId>
    <primaryCategory>
      <categoryId>31388</categoryId>
      <categoryName>Digital Cameras</categoryName>
    </primaryCategory>
    <galleryURL>http://thumbs.ebaystatic.com/pict/22044797618080_1.jpg</galleryURL>
    <viewItemURL>http://cgi.ebay.com/Canon-SD950is-12-1-MP-8GB-Card-Open-Box_
        W0QQitemZ220484479761QQcmdZViewItemQQptZDigital_Cameras?
        hash=item3355e62b11</viewItemURL>
    <productId type="ReferenceID">62415053</productId>
    <paymentMethod>PayPal</paymentMethod>
    <autoPay>true</autoPay>
    <postalCode>95125</postalCode>
    <location>San Jose,CA,USA</location>
    <country>US</country>
    <shippingInfo>
      <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
      <shippingType>Free</shippingType>
      <shipToLocations>US</shipToLocations>
    </shippingInfo>
    <sellingStatus>
      <currentPrice currencyId="USD">189.99</currentPrice>
      <convertedCurrentPrice currencyId="USD">189.99</convertedCurrentPrice>
      <bidCount>0</bidCount>
      <sellingState>Active</sellingState>
      <timeLeft>P0DT5H37M36S</timeLeft>
    </sellingStatus>
    <listingInfo>
      <bestOfferEnabled>false</bestOfferEnabled>
      <buyItNowAvailable>true</buyItNowAvailable>
      <buyItNowPrice currencyId="USD">249.99</buyItNowPrice>
      <convertedBuyItNowPrice currencyId="USD">249.99</convertedBuyItNowPrice>
      <startTime>2009-10-21T00:38:09.000Z</startTime>
      <endTime>2009-10-28T00:38:09.000Z</endTime>
      <listingType>AuctionWithBIN</listingType>
      <gift>true</gift>
    </listingInfo>
    <itemRank>2</itemRank>
    <itemRankWithinGroup>2</itemRankWithinGroup>
    <quantityAvailable>1</quantityAvailable>
    <quantitySold>0</quantitySold>
    <bestMatchData>
      <freeShipping>true</freeShipping>
      <impressionCountRange>
        <min>501</min>
        <max>750</max>
      </impressionCountRange>
      <salesCount>0</salesCount>
      <viewItemCount>5</viewItemCount>
      <watchCount>4</watchCount>
      <salesPerImpression>0.0</salesPerImpression>
      <salesPerViewItem>0.0</salesPerViewItem>
      <viewItemPerImpression>0.0080</viewItemPerImpression>
    </bestMatchData>
  </item>
</getBestMatchItemDetailsResponse>

getBestMatchItemDetails Change History

Version	Description
1.2.0 11/11/2009	searchResult.searchItemGroup.item.galleryPlusPictureURL (added): Image URL for items listed with Gallery Plus upgrade. itemFilter.name.SellerBusinessType (doc change): Corrected the allowed filter values to include Business and Private only.
1.0.1 09/30/2009	(added) New call.

User-Contributed Notes

eBay Best Match Item Details API Call Reference Version 1.7.0