eBay BestMatchItemDetails API
|
|
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. |
The BestMatchItemDetails API can help sellers understand the performance of their listings and the factors that influence Best Match. For an API for search, see the Finding API.
Best Match is the default sort order for search results on eBay. The goal of Best Match is to help buyers find what they're looking for, from sellers they trust.
You can use the BestMatchItemDetails API with other eBay APIs. See the Products page.
This Users Guide provides the following information:
Using the BestMatchItemDetails API, you can write applications that help sellers improve the Best Match rank of their listings. Additionally, you can enable sellers to view their items' click-through rates, their impression count range, and their items' sales per impression. An impression occurs on a listing when a user sees a search results page that contains the listing.
The Call Reference contains a list of API calls and their input and output.
For best practices and other information related to Best Match, see the following locations:
The Trading API Guide contains information about Best Match related to API calls for listing items (and relisting them).
eBay also is releasing the Search Visibility tool. The BestMatchItemDetails API provides extra functionality that is not available in the Search Visibility tool. However, before you write an application, please view the Search Visibility tool, located in My eBay (for sellers who can access the Seller Dashboard). For example, note the values returned for an item on the Search Visibility Report page of the tool. They correspond to some of the values returned in a getBestMatchItemDetails response.
The BestMatchItemDetails API is available only for the US site.
Note that in Best Match, fixed-price listings are treated differently from auction listings, as follows:
Therefore, when you use the API, the data you receive depends on the listing type.
The BestMatchItemDetails API enables you to get Best-Match related data about items.
You specify the items using search-related criteria or the item number. For descriptions of the types of input data you can send in a call request, see the Call Reference.
The following use cases apply to most of the API calls, and are described below:
The data returned by the BestMatchItemDetails API relates to the factors that are used in ranking under Best Match.
You can retrieve data by user ID, keyword, item number, category, or product.
Best Match data is returned for the seller whose user token is
in the following HTTP header: X-EBAY-SOA-SECURITY-TOKEN.
In most of the API calls, the output data for each listing includes the following:
Sellers review the Best Match ranking factors, and their own listings' performance, to determine what to change in their listings to help increase their sales.
Review the Ranking Factors for Best Match
Factors in ranking a listing under Best Match include:
Review the Listing Performance
The bestMatchData container has values for analyzing the performance of a listing. The salesPerImpression field contains the performance score. The salesCount field contains the number of sales that have occurred through the listing.
Your application could enable a seller to review listing performance by displaying items' impression count range, items' sales count, and items' sales per impression. These values relate to the performance score, which is a primary factor in Best Match.
Additionally, the item data returned by the API includes item.itemRank. This field indicates how the listing is currently ranked in search results, and is based on some of the values specified in the request, such as the keywords. You can specify common keywords and see the Best Match rank that would result if a user specified them.
To improve the rank of low-performing listings, and to see the characteristics that help an item perform well, a seller can ask what can be changed or retained based on the ranking factors described above.
The "page one listings" are some of the best-performing listings, and are returned on the first page of a query. The API can help sellers compare listings on page one to their listings, for a given search and/or in a given category.
Several calls, such as findBestMatchItemDetailsByKeywords,
enable you to retrieve best-match-related information about those listings.
Note that to retrieve this information with an applicable call, you must specify a
value of FirstPageSummary in the outputSelector field.
The "page one listing" information is returned in a firstPageSummary container, and includes such data as the range of shipping costs in the listings. The data is partly based on the number of items specified siteResultsPerPage; the value you provide in siteResultsPerPage determines how many entries to assess for the results returned in the firstPageSummary container.
The items in a firstPageSummary container are grouped by listing format.
Using the findBestMatchItemDetailsByCategory and findBestMatchItemDetailsAdvanced calls, you can review best-match-related information about listings in a specific category.
In findBestMatchItemDetailsByCategory, you specify any node of a category hierarchy. Using the data retrieved, you can analyze the performance of the listings. For information about listing performance, see Reviewing General Performance of Listings.
The findBestMatchItemDetailsByCategory response contains items ranked in a category, highest to lowest. The itemRankWithinGroup field contains each item's rank within the group. (The general item groups are Featured and Best Match; media items returned by findBestMatchItemDetailsByProduct have groups such as Brand New, Like New, etc.) The itemRank field contains each item's rank across groups.
This section describes various aspects of the BestMatchItemDetails API.
See Making an API Call for how to submit a BestMatchItemDetails API call.
Best Match ranks can vary with the keyword used in a given search. Therefore, in the following calls, the API provides a keywords input field: findBestMatchItemDetailsByKeywords, findBestMatchItemDetailsAdvanced, and findBestMatchItemDetailsAcrossStores. Use the field to retrieve listings where the specified keywords are found in the title and subtitle. The value specified in the keywords field can contain one or more keywords and wildcards ("*", "+", "-"). Only use "and," "or," or "the" if you are searching for listings that contain those words. You can use AND or OR logic by including modifiers. Note the effect, described below, of spaces before and after modifiers and wildcards.
The following table shows the operators and punctuation for keyword queries, and their effect.
| Operator | Description | Example | Returns |
|---|---|---|---|
| Space between words | Applies AND logic to multiple keywords. | baseball cardOR baseball%20card |
Items with both the words "baseball" and "card". |
| Comma between words, no parentheses | Applies AND logic to multiple keywords. | baseball,card |
Items with both the words "baseball" and "card". |
| Comma between words in parentheses | Applies OR logic to multiple keywords. | (baseball,card) |
Items with either the word "baseball" or the word "card". |
| Quoted words | Requires an exact sequence of words. | "baseball card" |
Items with the exact phrase "baseball card". |
| Minus ("-") sign before a word | Specified word cannot be present. | baseball -autograph |
Items that have the word "baseball" but not "autograph".
Note: A keyword query cannot consist of excluded words only. You must include one or more search terms in order to use the NOT operator ("-"). For example, "-autograph" is not a valid keywords value on its own, but "baseball -autograph" (i.e., <keywords>baseball -autograph</keywords>) will work.
|
| Minus ("-") sign before a group of words in parentheses | Specified words cannot be present. | baseball -(autograph,card,star) |
Items with the word "baseball" but not "autograph," "card," or "star". |
| Asterisk ("*") | Substitutes for one or more characters. | baseball* |
Items starting with the string "baseball". Use with a minimum of 2 characters. |
| At sign ("@") | Must find two of three words from a list. | @1 baseball autograph card |
Items with two of the three words "baseball," "autograph," and "card". For a "3 out of 4" search, use @2 and a list of four words. |
| Plus sign ("+") | Concatenates a query string using AND logic with another keyword. | @1 baseball autograph card +star |
Items with any two of the three words "baseball," "autograph," or "card" in the title plus the word "star". |
The findBestMatchItemDetailsByProduct call retrieves items by product. Sellers can view best match data about one or more items that they listed with a product identifier. This call is for sellers who listed items that included product information, i.e. data from a catalog.
The findBestMatchItemDetailsByProduct call requires a product ID and an ID type. The BestMatchItemDetails API supports the following product ID types:
Item filters are available in several calls. The itemFilter node contains name/value pairs.
In the following example, only items with free shipping are returned.
<itemFilter> <Name>FreeShippingOnly</Name> <Value>true</Value> </itemFilter>
Some item filters support multiple values. The query applies OR logic between the filter's multiple values. Specifying multiple values for a filter that does not support them returns an error. The following filter results in items with either of the specified listing types being returned:
... <itemFilter> <Name>ListingType</Name> <Value>FixedPrice</Value> <Value>AuctionWithBIN</Value> <itemFilter> ...
For PaymentMethod, a field can occur multiple times, with AND logic applied. Repeating a filter that is not repeatable returns an error. When the following filters are specified, items which accept PayPal and credit cards as payment methods are returned:
<itemFilter> <Name>PaymentMethod</Name> <Value>PayPal</Value> </itemFilter> <itemFilter> <Name> PaymentMethod </Name> <Value>CreditCard</Value> </itemFilter>
In some calls, you can get seller and/or first-page information by providing an outputSelector field in your request.
You retrieve seller information (that applies to an item) using
the SellerInfo value in the outputSelector field. The
information is returned in a sellerInfo container.
First-page data shows some characteristics of items that appear on the first page of
Best Match results, e.g. the ranges of prices and shipping costs. To see all the
characteristics returned by the API for first-page items, use the FirstPageSummary value
in the outputSelector field, in an applicable call. The
information is returned in a firstPageSummary container.
Most calls support the output selector, but the following calls do not:
getVersion, getBestMatchItemDetails, and findBestMatchItemDetailsBySeller.
The findBestMatchItemDetailsByProduct call only supports the SellerInfo value
in the output selector.
In most of the API calls, the entriesPerPage field controls the number of items to return. In the BestMatchItemDetails API, an item is returned in the Featured group (which contains items that users see as featured in search results on the eBay site) and/or the BestMatch group (which contains the general result set of items that users see after doing a search on the eBay site). These groups relate to the value in the itemRankWithinGroup field. The value of this field indicates where an item is ranked among items within the same group. Note that media items have different groups, such as Brand New, Like New, etc. For more information related to groups in Best Match, see the Call Reference.
A single Featured listing and/or a single multi-variation listing can be repeated within
one API call response, so the entriesPerPage field doesn't affect
the number of featured items returned. Therefore, when you use entriesPerPage,
you may want to specify true in the ignoreFeatured field.
The value you provide in siteResultsPerPage determines how many entries to assess for the results returned in the firstPageSummary container. The value you provide in siteResultsPerPage corresponds to the "Items Per Page" option, which is displayed on search results pages on the eBay site (where you can choose to view 25, 50, 100, or 200 items per page).
The value you provide in siteResultsPerPage doesn't affect the number of items returned in an API call.
In the BestMatchItemDetails API, pagination applies only in the findBestMatchItemDetailsBySeller call. This call returns Best Match data about the items listed by the seller you specify.
In findBestMatchItemDetailsBySeller, you can use the two fields in the paginationInput container:
In the findBestMatchItemDetailsBySeller response, the paginationOutput container has the following fields:
You can perform pagination by specifying a page number of 1 in your first call, and then use the response value of the total pages to determine how many subsequent calls to make.
For example, you could specify the following:
<paginationInput> <entriesPerPage>10</entriesPerPage> <pageNumber>1</pageNumber> </paginationInput>
An example of a corresponding response container is the following:
<paginationOutput> <pageNumber>1</pageNumber> <entriesPerPage>10</entriesPerPage> <totalPages>21</totalPages> <totalEntries>207</totalEntries> </paginationOutput>
The number of call requests made after the initial request would be based on the value returned in the totalPages field. And with each call, you would increment the value in the pageNumber field.
The paginationOutput.totalEntries field contains the total number of items that could be returned (by whatever number of calls that would be used). If the value specified in paginationInput.entriesPerPage is less than the value returned in paginationOutput.totalEntries, it will take more than one call to retrieve all of the items.
The BestMatchItemDetails API requires a seller's user token because of the nature of the data returned.
Pass the token in the following HTTP header: X-EBAY-SOA-SECURITY-TOKEN.
For the other required headers, see Making a Call.
The BestMatchItemDetails API is available only for the US site.
The eBay Motors site, global ID EBAY-MOTOR, does not support searching by product.
The BestMatchItemDetails API does not return mature content. All items from categories marked for mature users are filtered out.
See the Call Reference for limitations on specific API calls.
The BestMatchItemDetails Service is not currently supported in the eBay Sandbox environment.
Since the BestMatchItemDetails API does not modify any item or user data, you can safely test your application with calls to the live eBay site. The Production environment has more comprehensive and pertinent data.
Refer to the Call Reference for a list of calls in the BestMatchItemDetails API. The Call Reference includes the following:
You can get more information about the eBay BestMatchItemDetails API at these locations:
Share tips or code samples related to this call or topic. Questions or observations are welcome, too.
eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.
This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.
© 2009–2010 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.