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:

Introduction
Supported Request and Response Formats
Call Structure
Syntax
Testing Overview
Schema Location
User-Contributed Notes

Introduction

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:

XML
SOAP

XML

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

<findBestMatchItemDetailsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <keywords>harry potter phoenix</keywords>
  <siteResultsPerPage>25</siteResultsPerPage>
</findBestMatchItemDetailsByKeywordsRequest>

SOAP

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="http://www.w3.org/2003/05/soap-envelope" xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <soap:Header/>
  <soap:Body>
    <findBestMatchItemDetailsByKeywordsRequest>
      <keywords>harry potter phoenix</keywords>
      <siteResultsPerPage>50</siteResultsPerPage>
    </findBestMatchItemDetailsByKeywordsRequest>
  </soap:Body>
</soap:Envelope>

Call Structure

Each BestMatchItemDetails API call consists of the following elements:

Service Endpoint—All BestMatchItemDetails API requests must be sent to eBay's Production API Gateway (endpoint).
HTTP Headers—Each BestMatchItemDetails API call requires certain HTTP headers. For example, you must specify your authentication token in the X-EBAY-SOA-SECURITY-TOKEN header. Similarly, you must always specify the call name in the X-EBAY-SOA-OPERATION-NAME header. Other header values are either optional or conditionally required.
Standard Input Fields—The finding calls in the BestMatchItemDetails API support several standard input fields. For example, each supports entriesPerPage, which you can use to specify how many items you want returned in the result. There are also fields that you can use to you specify which items to include in the search, and which items to return from the search. Most standard input fields are optional.
Call-specific Input Fields—Some input fields, such as keywords or categoryId, are specific to a particular API call. Most call-specific input fields are required.

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:

https://svcs.ebay.com/services/search/BestMatchItemDetailsService/v1

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

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
X-EBAY-SOA-SECURITY-TOKEN: 123...ABC
X-EBAY-SOA-SERVICE-VERSION: 1.1.0
X-EBAY-SOA-GLOBAL-ID: EBAY-DE

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:

X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12

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

X-EBAY-SOA-OPERATION-NAME: findBestMatchItemDetailsAdvanced
X-EBAY-SOA-SECURITY-TOKEN: 123...ABC
X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12

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:

entriesPerPage—Specifies the number if items to return.
ItemFilter—Item filters use name/value pairs to describe the properties of the items you want returned. For example, you can target items based on their condition, the number of bids, a price range, the listing type, and so on.
outputSelector—Controls the fields you want to include in the response. Each call returns a default set of fields. Specify an output selector to augment the default set of response data with additional fields.
ingoreFeatured—Controls whether or not to include Featured items in the response.
PostSearch filters—Filters the items returned after the search has been completed. These filters provide a way to reduce the data in the response, without affecting the Best Match data returned from the full search specified in the request.
siteResultsPerPage—Specifies how many items to take into account for the First Page Summary analysis. This is a required field for most calls.

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.

Syntax

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
SOAP Syntax

XML Syntax

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

SOAP Syntax

The SOAP request/response format follows standard SOAP syntax conventions. Please see SOAP Syntax on w3schools.com 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:

https://svcs.ebay.com/services/search/BestMatchItemDetailsService/v1

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:

http://developer.ebay.com/webservices/best-match-item-details/latest/BestMatchItemDetailsService.wsdl

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

http://developer.ebay.com/webservices/best-match-item-details/VERSION/BestMatchItemDetailsService.wsdl

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:

http://developer.ebay.com/webservices/best-match-item-details/1.1.0/BestMatchItemDetailsService.wsdl

User-Contributed Notes

This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.

eBay BestMatchItemDetails API Making an API Call