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 document explains how to make a BestMatchItemDetails API call. It provides details on the call formats supported by the BestMatchItemDetails Service and the parameters available in the API.

This document contains the following sections:


The BestMatchItemDetails API gives you the ability to inspect the properties that influence an item's Best Match ranking in search results. In addition, responses from the API calls provide information on the performance of the items you list. Reviewing the response data can give you insights on the properties that affect your item response rates, and you can use this information to adjust your item listings with the goal of improving their ranking in search results.

The BestMatchItemDetails Service uses the search mechanism found in the Finding Service. If you are familiar with searching for items with the Finding Service, then you're on your way to taking advantage of the BestMatchItemDetails Service.

If you have not used the Finding Service, review the Finding Service Making a Call and User Guide documents to become acquainted with the mechanisms that you can use to search for items.

The remainder of this document is devoted to the details needed to make calls with the BestMatchItemDetails API.

Supported Request and Response Formats

The BestMatchItemDetails API supports HTTP POST calls in the following request and response formats:


The HTTP POST call method supports requests formatted in XML. The response format for XML requests is XML.

<findBestMatchItemDetailsByKeywordsRequest xmlns="">
  <keywords>harry potter phoenix</keywords>


The HTTP POST call method supports requests formatted in SOAP. The response format for SOAP requests is SOAP. SOAP versions 1.1 and 1.2 are both supported.

<soap:Envelope xmlns:soap="" xmlns="">
      <keywords>harry potter phoenix</keywords>

Call Structure

Each BestMatchItemDetails API call consists of the following elements:

Each of these call structures are addressed in detail in the following sections.

Service Endpoints

All BestMatchItemDetails API requests must be sent to the eBay Production API gateway; the BestMatchItemDetails Service is not currently supported in the eBay Sandbox environment.

Production Gateway URI (endpoint)

You must specify the following Production gateway URI in your BestMatchItemDetails requests:

Note: The service endpoint contains the major version for the service (e.g., v1). When updating to subsequent major releases, you must make sure to update the version in the service endpoint.

HTTP Header Values

When making BestMatchItemDetails API calls, you must specify certain values in the HTTP headers. In addition to required HTTP headers, the BestMatchItemDetails Service also supports optional and conditional headers.

The following table lists the BestMatchItemDetails API HTTP header parameters and describes their use:

Header Value Required? Description
CONTENT-TYPE No If you use this header, you must specify the content format exactly as shown, or your call may fail. The allowable values are:
XML text/xml
SOAP11 text/xml (together with the SOAPAction header, for which the value can be anything)
SOAP12 application/soap+xml
X-EBAY-SOA-GLOBAL-ID No The eBay site to which you want to send your request. The unique identifier is a combination of the site, language, and territory. Currently, the BestMatchItemDetails API is available only on the EBAY-US site (the default value for this field).
X-EBAY-SOA-MESSAGE-PROTOCOL Conditionally If you make a SOAP request, you must use this header to specify the SOAP protocol you are using. Allowable values are "SOAP11" for SOAP Version 1.1 and "SOAP12" for SOAP Version 1.2.
X-EBAY-SOA-OPERATION-NAME Yes The name of the API call in your request (for example, findBestMatchItemDetailsAdvanced or getBestMatchItemDetails).
X-EBAY-SOA-SECURITY-TOKEN Yes For authenticated services, the authentication token for the user for whom the call is being made. For more information on tokens, see Getting Tokens.
X-EBAY-SOA-SERVICE-NAME No The name of the eBay API you are using. Specify "BestMatchItemDetailsService" for all BestMatchItemDetails API calls.
X-EBAY-SOA-SERVICE-VERSION No The API version that your application supports (for example, 1.1.0). By default, this value is set to the latest version of the service.

Note: When using the Trading API, SOAP users must specify their user credentials in the SOAP header of the request. This is different in the BestMatchItemDetails Service where you cannot specify any URL parameters or HTTP headers (including X-EBAY-SOA-SECURITY-TOKEN) in the SOAP header.

HTTP Header Examples

The first example shows standard BestMatchItemDetails API headers for an HTTP POST call using an XML request format:

X-EBAY-SOA-SERVICE-NAME: BestMatchItemDetailsService
X-EBAY-SOA-OPERATION-NAME: findBestMatchItemDetailsByKeywords

The following example shows the required BestMatchItemDetails API headers for an HTTP POST call using SOAP. The example includes the following header value, which specifies that you are using SOAP Version 1.2:


Without the X-EBAY-SOA-MESSAGE-PROTOCOL header, the service would expect XML input.

X-EBAY-SOA-OPERATION-NAME: findBestMatchItemDetailsAdvanced

Standard Input Fields

Standard input fields are usually optional fields that you can include in the call to tailor the request to your specific needs. The different calls in the BestMatchItemDetails API share some standard input fields, some of which are the following:

Call-Specific Input Fields

Most calls in the service require certain input fields. For example, many of the calls require that you specify a value on which you want to search, for example, a set of keywords or a category ID.

Refer to the BestMatchItemDetails API Call Reference for each call's required and optional input fields, and their associated response output.


This section details the syntax requirements for the supported request and response formats. In most cases, the syntax for the various formats is standard; only the rules that aren't standard or are potentially tricky are explained.

XML Syntax

The XML request/response format follows standard XML syntax conventions. Please see XML Syntax Rules on for more information.

SOAP Syntax

The SOAP request/response format follows standard SOAP syntax conventions. Please see SOAP Syntax on for more information.

Testing Overview

Because the BestMatchItemDetails Service is not currently supported in the eBay Sandbox environment, you must test your BestMatchItemDetails API calls in the eBay Production environment. Use the following endpoint to access the Production environment:

Although the Production environment has live data, BestMatchItemDetails API calls do not alter item or user data. Because of this, it is safe for you to test your BestMatchItemDetails API calls in the Production environment.

Schema Location

Use the following link to download the latest WSDL for the BestMatchItemDetails API:

Alternatively, you can access a particular version of the BestMatchItemDetails schema using a URL with the following format:

Here, VERSION is the number of the particular schema release you want to download.

For example, access the WSDL schema version 1.1.0 at the following URL:

Back to top

User-Contributed Notes


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.