Finding API

Making a Call

This document explains how to make a Finding API call. It provides an overview of the formats and parameters you can use with the Finding API.

Supported Request and Response Formats

The Finding API supports a variety of request and response formats. Here's a list of the supported request formats and the response formats supported by each:

Name-Value Pairs

The HTTP GET call method passes values in the URL using name-value (NV) pairs. The HTTP POST method can also be used with name-value pairs, but the HTTP GET method is often the preferred method for calls that simply retrieve information. If you pass a name-value request using HTTP POST, you must specify the request data format.

Here's an example of a URL-style name-value pair request (wrapped for readability):

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
   &SERVICE-VERSION=1.0.0
   &SECURITY-APPNAME=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD
   &keywords=harry%20potter%20phoenix

By default, the call response for NV requests is in XML format, but you can specify NV or JSON as a response format, if desired.

JSON

JSON requests can be submitted using HTTP POST.

Here's an example of a JSON request that can be submitted via HTTP POST:

{"jsonns.xsi":"http://www.w3.org/2001/XMLSchema-instance",
"jsonns.xs":"http://www.w3.org/2001/XMLSchema",
"jsonns.tns":"http://www.ebay.com/marketplace/search/v1/services",
"tns.findItemsByKeywordsRequest":{"keywords":"harry potter phoenix"}}

By default, the call response for JSON requests is in XML format, but you can specify NV or JSON as a response format, if desired.

XML

The HTTP POST call method supports the use of XML format requests.

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

By default, the call response for XML requests is in XML format, but you can specify NV or JSON as a response format, if desired.

SOAP

The HTTP POST call method also supports the use of SOAP format requests. 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>
      <findItemsByKeywordsRequest>
         <keywords>harry potter phoenix</keywords>
      </findItemsByKeywordsRequest>
   </soap:Body>
</soap:Envelope>

The call response for SOAP requests is in SOAP format only.

Call Structure

Each Finding API call consists of the following elements:

Note: The Developers Program Knowledge Base is a good source of code samples. To find code samples and other useful information for the Finding API, select Finding API from the Search By Product drop-down menu and click Search.

Service Endpoints

Finding API requests may be sent to either the eBay Production API Gateway URI (endpoint) or the eBay Sandbox endpoint. You specify the endpoint in the request.

Production Endpoint:

http://svcs.ebay.com/services/search/FindingService/v1

Sandbox Endpoint:

http://svcs.sandbox.ebay.com/services/search/FindingService/v1

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

Standard URL Parameter or HTTP Header Values

When you make a Finding API call, you choose whether to specify the standard values in URL parameters or in the HTTP header. URL parameters are provided as name-value pairs in the query part of the URI.

Note: If you specify both a URL parameter and an HTTP header for the same value in the same call, the URL parameter takes precedence. In most cases it is easier to use URL parameters rather than HTTP headers. The order of the parameters is not important, however, the values you provide in your call (such as the value for your AppID) are case sensitive.
Note: In the Trading API, SOAP users specify their user credentials in the SOAP header of the request. For the Finding API, no URL parameters or HTTP headers, including X-EBAY-SOA-SECURITY-APPNAME can be specified in the SOAP header.

The following table contains descriptions of the standard Finding API parameters and the corresponding header values:

URL Parameter Header Value Required? Description
callback N/A N Applies only in cases where the response data is in JSON format. The response data is wrapped in a call to the specified function, to make the response data easier to use. This parameter specifies the name of the function that is returned. For example, if you use the findItemsByKeywords call and you specify callback=cb_findItemsByKeywords, then the response data will be wrapped in a call to a cb_findItemsByKeywords() function.
N/A 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
SOAP12 application/soap+xml
SOAP11 text/xml (together with SOAPAction header being sent - value can be anything)
GLOBAL-ID X-EBAY-SOA-GLOBAL-ID No The unique identifier for a combination of site, language, and territory. For example, EBAY-US (the default) is the global ID that corresponds to the eBay US site. The global ID you specify must correspond to an eBay site with a valid site ID. Refer to eBay Site ID to Global ID Mapping. In addition, Global ID Values contains a complete list of the eBay global IDs.
MESSAGE-ENCODING X-EBAY-SOA-MESSAGE-ENCODING Conditionally Specifies the message encoding (e.g., ISO-8859-1). The default encoding is UTF-8. When submitting requests in any format other than UTF-8, you must specify the message encoding.
N/A X-EBAY-SOA-MESSAGE-PROTOCOL Conditionally If you make a SOAP request, you must use this header to specify the protocol you are using. Allowable values are "SOAP11" for SOAP Version 1.1 and "SOAP12" for SOAP Version 1.2.
OPERATION-NAME X-EBAY-SOA-OPERATION-NAME Yes The name of the call you are using (for example, findItemsAdvanced or getHistograms).
REQUEST-DATA-FORMAT X-EBAY-SOA-REQUEST-DATA-FORMAT No The Finding API supports NV, JSON, XML, and SOAP request formats with the HTTP POST method. Input can be in the following formats: NV, JSON, or XML (used for XML or SOAP). The default value for HTTP POST requests is XML.
For SOAP requests, you must specify the protocol version in the X-EBAY-SOA-MESSAGE-PROTOCOL header. If you use a URL for an HTTP GET request, REQUEST-DATA-FORMAT is unnecessary because the only valid value is NV (Name-Value Pair).
RESPONSE-DATA-FORMAT X-EBAY-SOA-RESPONSE-DATA-FORMAT No If you use a URL (HTTP GET) request, use this parameter to specify the output format as JSON, XML, or NV (Name-Value Pair). URL requests do not support SOAP responses. If you use a URL, and you do not specify RESPONSE- DATA-FORMAT, the output format will be XML. If you use the HTTP POST method, the output data (response data) will be in the same format as the input data.
REST-PAYLOAD N/A No If you use a URL, use this parameter to separate the payload part of the URL from the standard headers. Requires no value; anything appearing after this header will be considered part of the call payload. This parameter is ignored in HTTP POST requests.
SECURITY-APPNAME X-EBAY-SOA-SECURITY-APPNAME Yes This is the application ID (AppID) for the service consumer. You obtain an AppID by joining the eBay Developers Program.
SERVICE-VERSION X-EBAY-SOA-SERVICE-VERSION No The API version your application supports (e.g., 1.0.0).

URL Parameter Examples

If you are using a URL (and the HTTP GET method), input must be in the NV (Name-Value Pair) format. Use the RESPONSE-DATA-FORMAT header to specify that data is returned in one of the following formats: NV or XML. The following example (wrapped for readability) shows standard Finding API parameters. RESPONSE-DATA-FORMAT specifies XML for XML output.

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
  &SERVICE-NAME=FindingService
  &SERVICE-VERSION=1.0.0
  &GLOBAL-ID=EBAY-US
  &SECURITY-APPNAME=MyAppID
  &RESPONSE-DATA-FORMAT=XML
  &REST-PAYLOAD
  &Standard input fields
  &Call-specific input fields

HTTP Header Examples

The following example shows standard Finding API headers for an HTTP POST call using XML:

X-EBAY-SOA-SERVICE-NAME: FindingService
X-EBAY-SOA-OPERATION-NAME: getHistograms
X-EBAY-SOA-SERVICE-VERSION: 1.0.0
X-EBAY-SOA-GLOBAL-ID: EBAY-US
X-EBAY-SOA-SECURITY-APPNAME: MyAppID
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML

The following example shows standard Finding API headers for an HTTP POST call. In the example, the X-EBAY-SOA-REQUEST-DATA-FORMAT header specifies XML, signaling either XML or SOAP as input. The example also includes X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12, specifying 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-SERVICE-NAME: FindingService
X-EBAY-SOA-OPERATION-NAME: findItemsAdvanced
X-EBAY-SOA-SERVICE-VERSION: 1.0.0
X-EBAY-SOA-GLOBAL-ID: EBAY-US
X-EBAY-SOA-SECURITY-APPNAME: MyAppID
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML
X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12

Standard Input Values

The search calls in the Finding API share some standard input fields, which include:

In addition to these fields in the shared request type, the search calls all support the following fields:

Call-Specific Values

Refer to the Finding API Reference for the input and output fields supported by the Finding API calls.

Syntax

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

Name-value Syntax

Name-value requests/responses follows the syntax rules for the query string part of a URI. The query string is the portion of the URI that follows the endpoint. The query string is separated from the endpint by a question mark ("?"). The query string consists of a series of name-value pairs separated by ampersands ("&"). The name always precedes the value and they are separated by an equals sign ("=").

The following sections outline syntax rules specific to the name-value request/response format.

Using Array Syntax

Some input fields in the API, such as itemFilter or categoryId, are repeatable, and can be submitted as an array. When specifying an array of fields in a name-value request, such as multiple itemFilter entries, you must follow the following array indexing rules:

Starting a multi-element array with a value other than zero or empty parentheses will cause the request to fail. If an array index does not increment by one, in order, from zero, the request will fail. If you split up the array (e.g., insert another field between to array entries), the request will fail.

In the following sample, the first itemFilter has an index value of zero ("0"), the second filter has an index value of one ("1"), and the last filter has an index value of two ("2"). Note that the repeating value fields in the last filter are also indexed.

Indexed array of item filters, including indexed array of ListingType values

...
&itemFilter(0).name=MaxPrice
&itemFilter(0).value=25
&itemFilter(0).paramName=Currency
&itemFilter(0).paramValue=USD
&itemFilter(1).name=FreeShippingOnly
&itemFilter(1).value=true
&itemFilter(2).name=ListingType
&itemFilter(2).value(0)=AuctionWithBIN
&itemFilter(2).value(1)=FixedPrice
&paginationInput.entriesPerPage=2
...

If you have a single element array, such as a single item filter, you are not required to index it. That is, you can leave the parentheses and enumerations off entirely.

Single item filter, no indexing

...
&itemFilter.name=MaxPrice
&itemFilter.value=25
&itemFilter.paramName=Currency
&itemFilter.paramValue=USD
&paginationInput.entriesPerPage=2
...

Indexing a single element array also works, and may make more sense if you are programmatically generating the array.

Single item filter, with indexing

...
&itemFilter(0).name=MaxPrice
&itemFilter(0).value=25
&itemFilter(0).paramName=Currency
&itemFilter(0).paramValue=USD
&paginationInput.entriesPerPage=2
...

Specifying Attributes

Attributes require a special syntax when used in name-value requests. The findItemsByProduct call requires the use of an attribute to specify the product ID (e.g., <productId type=ISBN>1234567890</productId>). In URL/NV requests (and responses) are attributes preceded by an at sign ("@"). For example, the product ID would be specified as in the following example:

...&productId.@type=ISBN&productId=1234567890...

UTF-8 Encoding for Special Characters

All parameter values should be encoded in UTF-8 format. UTF-8 is the default encoding for API requests. For example, if you are searching for USB data cable chargers on the eBay Germany site, you might search for USB datenkabel ladegerät. The a-umlaut (ä), however, is outside of the standard character set and will cause inaccurate search results if it is not UTF-8 encoded. To use these keywords in the API, you must first UTF-8 encode the string.

Once the parameter value is UTF-8 encoded, it should be URL-encoded to take care of spaces and quotation marks (" ") and other characters in the string that are pertinent to the URL request.

The following URL request snippet shows how USB datenkabel ladegerät looks after UTF-8 and URL encoding:

... &keywords=USB+datenkabel+ladeger%C3%A4t...

When submitting requests in any format other than UTF-8, you must specify the message encoding with the MESSAGE-ENCODING URL parameter or the X-EBAY-SOA-MESSAGE-ENCODING HTTP header.

URL Encoding for String Values

Name-value requests must be constructed using the ASCII character-set only. Most ASCII characters (e.g., the numbers from 0-9 and the uppercase and lowercase English letters from A to Z) can be used as-is. Some special characters, however, such as spaces, ampersands ("&") and quotation marks, must be encoded in URL requests when used in string values for fields like keywords or aspectValueName.

Special characters that must be URL-encoded include (but are not limited to) characters used in URL request syntax, such as ampersands ("&"), the equals sign ("="), the pound sign ("#"), the "at" symbol ("@"), or the percent sign ("%"), for that matter.

URL-encoded characters are in the form %HH, where HH is a hexadecimal number. For example, the URL-encoded value for an ampersand is %26 and the URL-encoded value for a space is %20. The plus sign ("+") can also be used in place of spaces. The following sample shows a URL-encoded keywords value that you could use to search for items matching "Bang & Olufsen" (i.e., an exact match, with quotation marks) on eBay:

...&keywords=%22Bang+%26+Olufsen%22...

Many languages provide functions or methods to do the URL encoding for you. For example, PHP provides the rawurlencode function and Java provides URLEncoder class. For more information about URL encoding, see RFC 1738.

JSON Syntax

The JSON request/response format follows standard JSON grammar rules. Please see RFC 4627 for more information.

Specifying Attributes

Attributes follow standard JSON grammar rules, but when an field has both an attribute and a value, the value requires a special representation. For example, the findItemsByProduct call requires the use of an attribute to specify the product ID (e.g., <productId type=ISBN>1234567890</productId>). In JSON requests (and responses) attributes are preceded by an at sign ("@") and the product ID value is represented with a "__value__" name.

Here's an example of how to specify the product ID:

..."productId":{"@type":"ISBN","__value__":"1234567890"}...

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

You can use the Production environment (with the http://www.ebay.com/marketplace/search/v1/services endpoint) to test calls to the Finding API. Although the Production environment has live data, Finding Service calls do not alter item data or user data. The Finding API also works in the Sandbox environment.

Versioning Scheme

The version numbering scheme for the Finding API is different from the scheme used by the eBay Shopping and Trading APIs. The Finding API version consists of three digits (e.g., 1.2.3):

Schema Location

You can download the latest version of the WSDL for the Finding API with the following link:

    http://developer.ebay.com/webservices/Finding/latest/FindingService.wsdl

Alternatively, you can access a particular version of the Finding schema using a URL with the following format (where VERSION is the version identifier of the release):

   http://developer.ebay.com/webservices/Finding/VERSION/FindingService.wsdl

The version identifier is the version number of a particular schema (a release number).

For example, you can access version 1.0.0 of the WSDL version of the schema at the following URL:

    http://developer.ebay.com/webservices/Finding/1.0.0/FindingService.wsdl

Back to top

Error Handling

Your application should implement error handling to provide graceful recovery from error states. Without proper error handling, application execution can be halted suddenly by errors or warnings returned by eBay. Error handling also enables the application to display errors that are more meaningful to the end-user. Moreover, an application can be more easily localized for use in different languages. (If the application's error messages that correspond to the API error messages are stored in something like a string table, then different string tables can readily be substituted for different languages.)

When a problem occurs and a request (or a portion of a request) cannot be executed for some reason, the response includes a list of errors instead of the normal business data. If the request is executed successfully but a minor problem was found or a change was made that you might not expect, the response includes the normal business data accompanied by a list of warnings.

It is important to understand the types of errors and warnings that eBay may return so that you can design your application to handle them gracefully.

Always Check the Ack Value in the Response

Each API response contains an acknowledgement field (e.g., ack or Ack), and the value in this field indicates whether the request was successful or not (e.g., <ack>Success</ack>). The value will be one of the following values:

Both Success and Warning Indicate a Successful Request

Both Success and Warning indicate that the request was successful. However, a value of Warning means that something occurred that may affect your application or the user. For example, eBay may have dropped or changed a value submitted in the request. In this case, eBay returns a normal, successful response and also returns the warning. When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). Depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future.

How to Handle Failure

If the source of the problem is within the application (such as a missing required element), please change the application before you retry the request. If the problem is due to end-user input data, please 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, you can attempt to re-send the request to eBay. If the source of the problem is on eBay's 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.

How to Handle Partial Failures

An ack value of PartialFailure means that eBay successfully processed the parts of 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 inside the Error container and resolve any problems before resubmitting the request.

User-Contributed Notes

 

Copyright © 2009–2014 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.