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.

What's Different

The Finding API provides search functions that are very similar to the functions provided by FindItemsAdvanced in the Shopping API and GetSearchResults in the Trading API. If you are familiar with these APIs, the Finding API has a few differences worth noting:

Service Endpoints—The Finding API has a unique gateway URL (service endpoint) for Production. The Finding API s not supported in the Sandbox. The service endpoint includes the service version (e.g., v1). When updating to a new major version of the service, you must update to a new service endpoint, as well.
HTTP headers and URL parameters—The Finding API uses eBay's Service Oriented Architecture (SOA) framework, which requires a new set of HTTP headers and URL parameters. For example, although you can use the same AppID you use with the Shopping or Trading APIs, the header (X-EBAY-SOA-SECURITY-APPNAME) or URL parameter (SECURITY-APPNAME) you use is different.
Schema and data type changes—The Finding API does not share schema or data types with other eBay APIs. In the API, you will find the following differences from other eBay APIs:
- No site ID! Instead, we provide globalId, a unique identifier for a combination of site, language, and territory. See the Global ID Values table for a list of global IDs that map to site IDs. The global ID you use must map to an eBay site with a site ID.
- XML namespace is versioned. To prevent type collisions associated with backward incompatible service changes, the XML namespace is versioned. As with the service endpoint, when updating to a new major version of the service, note that the XML namespace will change, as well.
- New types (such as SearchItem) contain standard content such as item ID, title, pricing information, time left, and a View Item page URL. Although the types and fields are slightly different, the eBay data is the same.
- Completely new types, such as the ErrorMessage type, a completely new structure for error information.
- New listing type, AuctionWithBIN, added to simplify the search experience. This listing type value is not available in other APIs. For FindItemsAdvanced in the Shopping API, you would need to set ListingType to Auction and FixedPricedItem to retrieve auction items with Buy It Now enabled, and the listing type for matching items will be Auction. Note that the AuctionWithBIN listing type is subject to change. That is, if a buyer places a bid on an AuctionWithBIN item, the listing type changes to Auction.
- Greater use of xs:token for enumeration values. Many elements that take enumeration values use type=xs:token instead of specifying the enumerations in a simple type. For example, the listing type (searchResult.item.listingInfo.listingType) or payment method (searchResult.item.paymentMethod) values are not specified in a type. Developers must determine the allowed values from the documentation, instead of the schema. New values will be documented, but eBay will not return CustomCode when new enumerations are added. It is the responsibility of the developers using this API to write their applications to be able to handle new enumeration values.
Naming conventions—The naming conventions for the Finding API are slightly different. Most notably, call names and fields in the Finding API begin with lowercase letters.
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):
- The first digit indicates the major release version.
  Major releases are not backward compatible. eBay supports the two most recent major versions of the service. 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.

Note: The following guides map input and output fields for FindItemsAdvanced in the Shopping API and GetSearchResults in the Trading API to corresponding input and output fields in findItemsAdvanced in 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 the 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. Name-value requests using the HTTP GET (URL) method support responses in JSON format. JSON format requests are supported via HTTP POST, as well.

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. The default response format for XML requests is also XML.

<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. The default response format for SOAP requests is also 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>
      <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—All Finding API requests must be sent to eBay's Production API Gateway (endpoint)
HTTP Headers or URL Parameters—Each Finding API call requires certain HTTP 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 X-EBAY-SOA-OPERATION-NAME URL parameter. Other headers are optional or conditionally required.
Standard Input Fields—The finding calls in the Finding API support several standard input fields. For example, each finding 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

All Finding API requests must be sent to the eBay Production API Gateway. You specify the gateway URI in the request.

The Finding Service is not currently supported in the eBay Sandbox environment.

Production Gateway URI (endpoint):

http://svcs.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
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.
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.
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).
OPERATION-NAME	X-EBAY-SOA-OPERATION-NAME	Yes	The name of the call you are using (for example, findItemsAdvanced or getHistograms).
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-API-REQUEST-ENCODING 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:

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 Call 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
JSON Syntax
XML Syntax
SOAP Syntax

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

When specifying an array of fields in a name-value request, such as multiple itemFilter entries, you must use parenthetic notation to enumerate the entries in the array.

...
&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
&itemFilter(2).value(2)=StoreInventory
...

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...

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 ampersands ("&"), 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 following sample shows a URL-encoded keywords value that you could use to search for items matching "Bang & Olufsen" on eBay:

...&keywords="Bang%20%26%20Olufsen"...

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 Service is not currently supported in the eBay Sandbox environment.

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

User-Contributed Notes

eBay Finding API Making an API Call

What's Different

Supported Request and Response Formats

Name-Value Pairs

JSON

XML

SOAP

Call Structure

Service Endpoints

Standard URL Parameter or HTTP Header Values

URL Parameter Examples

HTTP Header Examples

Standard Input Values

Call-Specific Values

Syntax

Name-value Syntax

Using Array Syntax

Specifying Attributes

URL Encoding for String Values

JSON Syntax

Specifying Attributes

XML Syntax

SOAP Syntax

Testing Overview

Schema Location

User-Contributed Notes

eBay Finding API
Making an API Call