Skip to main content

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.

Support 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:

URL Parameters

The HTTP GET call method passes values in the URL using query parameters. The HTTP POST method can also be used with query parameters, but the HTTP GET method is often the preferred method for calls that simply retrieve information. If you pass in query parameters using HTTP POST, you must specify the request data format.

Here's an example of a URL-style request :

https://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 Finding API call responses are in XML format, but you can specify NV or JSON as a response format, if desired.

For more information on the URL parameters used here, see the Standard URL Parameter or HTTPS Header Values table.

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":"https://www.w3.org/2001/XMLSchema-instance",
   "jsonns.xs":"https://www.w3.org/2001/XMLSchema",
   "jsonns.tns":"https://www.ebay.com/marketplace/search/v1/services",
   "tns.findItemsByKeywordsRequest":{
      "keywords":"harry potter phoenix"
   }
}

By default, the Finding API 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="https://www.ebay.com/marketplace/search/v1/services">
  <keywords>harry potter phoenix</keywords>
</findItemsByKeywordsRequest>

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="https://www.w3.org/2003/05/soap-envelope" xmlns="https://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:

  • Service Endpoint. Finding API requests can be sent to either the Production API Gateway (endpoint) or the Sandbox endpoint for the Finding API.

  • HTTPS Headers or URL Parameters. Each Finding API call requires certain HTTPS headers or URL parameters. For example, you must specify your AppID in the X-EBAY-SOA-SECURITY-APPNAME header or Security-AppName URL parameter. Similarly, you must always specify the call name in the X-EBAY-SOA-OPERATION-NAME header or Operation-Name URL parameter. Other headers are optional or conditionally required.

  • Standard Input Fields. The calls in the Finding API support several standard input fields. For example, each call supports the affiliate field and related fields for specifying affiliate information. The standard input fields are optional.

  • Call-specific Fields. Some input fields, such as keywords or categoryId, are specific to a particular API call.

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:

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

Sandbox Endpoint:

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

Standard URL Parameters or HTTPS Header Values

When you make a Finding API call, you choose whether to specify request data through URL parameters or through HTTP header.

Note: When using SOAP with Finding API requests, standard and call-specific parameters and headers cannot be passed in through the SOAP Header section in the request.

The following table contains descriptions of the standard Finding API URL parameters and the corresponding HTTP Headers:

URL Parameter HTTP Header Required? Description
N/A CONTENT-TYPE No

This header sets the data format that will be used in the request payload. Example values are shown below:

For XML (default)
CONTENT-TYPE: text/xml

For SOAP 1.2
CONTENT-TYPE: application/soap+XML

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 call-specific payload part of the URL from the standard URL parameters. 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).

Standard Input Values

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

  • affiliate. Container for specifying affiliate details. eBay uses the specified affiliate information to build a View Item URL and Product URL string with correctly formatted affiliate tracking information, which it returns in the response.

  • buyerPostalCode. The postal code of the buyer. This is used as the basis for proximity searches as well as local searches.

  • paginationInput. Controls the pagination of the result set.

  • sortOrder. Specifies the order in which returned items are sorted, such as by price or by listing end time.

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

  • itemFilter. Use name/value pairs to describe specific filters for item properties, such as item condition, number of bids, price range, listing type, and so on.

  • aspectFilter. Refines search results based on aspects, which are well-known, standardized characteristics of an item.

  • outputSelector. Defines what data to return in a response, in addition to the default set of data. Additional seller or store information can be included for each item in the response. You can also retrieve category or aspect histograms for the search results.

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 endpoint 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:

  • Use parenthetic notation to enumerate the entries in the array

  • Start the array index with zero ("0") for the first array entry

  • Increment each subsequent array entry by one

  • Keep all array entries together (i.e., do not insert other fields between array entries)

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 HTTPS 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, see w3schools.com HTML URL Encoding Reference.

JSON Syntax

The JSON request/response format follows standard JSON rules. For more information, see Introducing JSON.

Specifying Attributes

Attributes follow standard JSON rules, but when a 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__":"1********0"}...

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. For more information, see XML SOAP on w3schools.com.

Testing Overview

You can use the Production environment (with the https://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 Shopping API and Trading API. The Finding API version consists of three digits (e.g., 1.2.3):

  • The first digit indicates the major release version.

    • Major releases are not backward compatible. The service endpoints and target namespace include the major version of the service.

  • The second digit indicates the minor release version.

    • Minor releases consist of feature additions or behavior changes that are backward compatible.

  • The third digit indicates the maintenance, or micro, release version.

    • Maintenance releases are used to correct minor problems. Maintenance releases have minimal impact on the features or functionality of the API. These changes may or may not have associated schema changes.

Schema Location

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

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

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:

  • Success

  • Warning

  • Failure

  • PartialFailure

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 a 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, file a ticket with 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.