Users Guide

The Finding API provides programmatic access to the next generation search capabilities on the eBay platform. It lets you search and browse for items listed on eBay, and provides useful metadata to refine searches and enhance the search experience.

Affiliates can use this API to build search and browse capabilities into bidding and buying applications. Sellers need to understand how searching and browsing works so they can optimize their listings for better search visibility.

This Users Guide provides the following information to help you get started with the Finding API:

• Service Overview
• Use Cases
• Working with the Finding API
• Additional Resources

Service Overview

The Finding API has several calls to help buyers and sellers find items on eBay. The Finding API uses eBay's next generation search technology to ensure relevant search results.

The APIs provide the following capabilities:

• Search for items based on a keyword query
• Search for items associated with a specific product
• Browse for items in a specific category or in an eBay store
• Filter search results by item listing details, such as price, condition, listing type, and more
• Refine searches by the characteristics of an item (i.e., aspects), such as brand, style, size, or color
• Retrieve category and aspect metadata
• Get keyword recommendations to improve search results

The Finding API exposes category and aspect information, which is different from existing APIs. Categories, such as shoes or digital cameras, are a buy-side grouping of items. Aspects are item characteristics shared by items in a given category. For example, in the Shoes category, aspects include Style, Color, and Shoe Size. In the Digital Cameras category, aspects include Product Type, Brand, Megapixels, and Optical Zoom. The search calls and the getHistogram call return category and aspect metadata that can be used to refine searches.

Refer to the Finding API API Reference for a list of API calls and the associated inputs and outputs for each.

Back to top

Use Cases

You can use the Finding API to search or browse for items. Each method has its advantages, depending on the experience your users want:

• Searching—when users are looking for something specific, searching helps them find it quickly. Searching requires the use of the keywords field to build a query. By entering two or three descriptive words about the item into a search box, and you receive search results that match those words. Searching also offers sophisticated options and commands that allow you to narrow your search in a variety of ways.
• Browsing—sometimes, users aren't sure what they're looking for, or just want to window-shop or scroll through items. With findItemsByCategory, users can browse items by in specific categories. With findItemsIneBayStores, can browse items by eBay store.

The following use cases are described in this section:

• Searching by Keywords
• Searching and Browsing by Category
• Searching by Product
• Refining a Search with Item Filters
• Refining a Search with Aspect Filters
• Controlling the Way Search Results are Returned
• Retrieving Histogram Metadata
• Affiliate Tracking
• Combining with Other eBay APIs

Searching by Keywords

The keywords field is the basis for item searches. The search calls, such as findItemsByKeywords, search for item listings where the specified keywords are found in the title and, in some cases, the item subtitle or structured item data, returning those matching items in the result set. Queries aren't case-sensitive, so it doesn't matter whether you use uppercase or lowercase letters.

The following search features help you get the most relevant search results possible with your keyword queries:

• Advanced search operators
• Automatic keyword expansions

Advanced Search Operators

The value specified in the keywords field can contain one or more keywords. The words "and" and "or" are treated like any other word. Only use "and," "or," or "the" if you are searching for listings containing these words. You can use AND or OR logic by including certain modifiers. Be careful when using spaces before or after modifiers, such as plus signs ("+") or minus signs ("-").

The following table shows the operators and character punctuation that can be used in keyword queries, and the effects they have.

With the exception of the advanced search operators, punctuation marks, such as hyphens (-), commas followed by spaces (, ), exclamation points (!), question marks (?), slashes (/), and forward slashes (\) are excluded from matching. For example, a search for "3/4 sleeve" (i.e., <keywords>"3/4 sleeve"</keywords>) will match "3-4 sleeve", "3\4 sleeve", "3/4-sleeve", etc.

Automatic Keyword Expansions

Keyword queries always search item titles for words or phrases that match exactly the keywords you specified. In some cases, eBay automatically expands keyword queries to increase the number of relevant results in the response. Keyword searches can be expanded by expanding the query and/or expanding the places in which to search for matching terms. This is why search results may contain items with titles that do not have all the keywords you specified in your query.

Using advanced search operators (e.g., " ", ( ), -, +, *, or @) in your keyword query disables automatic keyword expansions. For example, an exact phrase search, such as <keywords>"baseball card"</keywords> will limit the search results to items with the exact phrase in the title only.

Searching and Browsing by Category

Item listings can be retrieved for one or more specific categories on an eBay site to create a browsing experience. findItemsByCategory returns item listings for each category specified in the request. The findItemsByCategory response contains details about items in the specified categories.

This call supports item filters (itemFilter) and aspect filters (aspectFilter) to refine your search results. By default, eBay returns a standard set of data for each item in the response. Use outputSelector to specify additional data to include in the response for each item.

By default, results are sorted by Best Match, with the most relevant items first. Use sortOrder to specify different sort order, such as by current price or the listing end time. Use paginationInput to specify how many items to return per response (page) and the specific page of data to return.

To determine valid categories, use the Shopping API GetCategoryInfo call.

Searching by Product

Within the context of eBay, a product is stock information from a catalog. A seller can take this product data and use it to pre-fill some of the details in their listings. (We call this Pre-filled Item Information.) For example, a seller can list a book using the book's ISBN and the listing will automatically include a stock photo of the book, the listing title will include the title of the book and the name of the author, and details about the book will be included in the item specifics.

For example, if you search the eBay site for "harry potter and the chamber of secrets," the site will return matching items. If you click on one of the items and look in the Product Details section of the description, you will see information about the product, such as author, publisher, publication date, and ISBN. This information comes from the Books catalog. The product details page also displays listings that contain data matching the product.

You can use the findItemsByProduct call to search for items that contain data matching a specified product. This call requires a product ID and the ID type. The Finding API supports the following product ID types:

• ReferenceID—a global reference ID for an eBay catalog product
• ISBN—the 10 or 13-digit International Standard Book Number
• UPC—the Universal Product Code, a numeric value associated with barcodes
• EAN—the European Article Number, a numeric value associated with barcodes

If you do not know the product ID, use FindProducts in the Shopping API to retrieve a list of catalog products. Obtain the product ID from one of these products and use it as input to findItemsByProduct to find all items that were listed based on that product.

Refining a Search with Item Filters

Item Filters are constraints applied to search queries, category browsing, or eBay store browsing. Filters provide better control over the search results by narrowing the range of items returned. The itemFilter node contains name/value pairs to describe specific filters. Item filters are optional input parameters.

<itemFilter>
  <Name/>
  <Value/>
</itemFilter>

In the following example, all items with free shipping are returned in the results.

<itemFilter>
  <Name>FreeShippingOnly</Name>
  <Value>true</Value>
</itemFilter>

When using the name/value pairs in the URL message format, an array notation is required for multiple filters, as shown in the following example (line breaks added for readability):

...
&itemFilter(0).name=Condition
&itemFilter(0).value=New
&itemFilter(1).name=MaxPrice
&itemFilter(1).value=50.0
&itemFilter(1).paramName=Currency
&itemFilter(1).paramValue=USD
...

Filters with Multiple Values

Some item filters can support multiple values. The search query applies an OR logic between the filter's multiple values. That is, items matching either criterion will be returned. Not all filters support multiple values. Specifying multiple values for a filter that does not support them returns an error.

The following filter results in items with either of the specified listing types being returned:

...
<itemFilter>
  <Name>ListingType</Name>
  <Value>FixedPrice</Value>
  <Value>AuctionWithBIN</Value>
<itemFilter>
...

When using the name/value pairs in the URL message format, an array notation is required for multiple filter values, as shown in the following example (line breaks added for readability):

...
&itemFilter(0).name=ListingType
&itemFilter(0).value(0)=FixedPrice
&itemFilter(0).value(1)=AuctionWithBIN
...

Refining a Search with Aspect Filters

The search calls, such as findItemsByKeywords and findItemsAdvanced can return aspect metadata that can be used to refine searches. The metadata is returned in the form of a histogram, which contains the name of the category that is most pertinent to your search, and information for all of the aspects (e.g., Brand) used in the category.

To refine a search by category, use findItemsAdvanced and the categoryID field.

Aspects are item characteristics, such as brand, product type, size, which are shared by certain types of items. For example, for Shoes, aspects include Style, Color, and Shoe Size. For Digital Cameras, aspects include Product Type, Brand, Megapixels, and Optical Zoom. These aspect values come from listing properties, such as item specifics, titles, and subtitles. This aspect information can be used to create filters to refine your search results.

Retrieving Aspect Histograms with Search Results

When you search for items with one of the finding calls in the Finding API, you can optionally request an aspect histogram (e.g., outputSelector=AspectHistogram). The histogram provides information you can use to refine your search. The histogram lists all the aspects (e.g., Brand or Size) used in the category. For each aspect, all aspect values (e.g., brand names) are listed with the number of active listings that match a given aspect value. Aspect filters consist of an aspect name, and one or more aspect value names. An aspect value is returned only if there are active listings associated with the value.

Not all searches will return an aspect histogram. Searching for items in categories that do not support aspects, such as antiques, will not return an aspect histogram. Also, if your search is too broad, it may not return an aspect histogram. For example, searching with just "ipod" in your keywords may not return a histogram, but "ipod nano" will.

Aspect data varies by category. For example, although the category for women's dresses and the category for wedding dresses may have some similar aspects, such as size, many aspects differ between the two categories. When the response does contain an aspect histogram, it is returned for the category that is most pertinent to your search. Note that aspect data is based on information from currently active items only. You should not store and reuse the aspect data.

If you search the eBay site for digital cameras, you may get an aspect histogram that looks like the following sample:

Note: In the following example, the domainDisplayName field returns the category name and the domainName field returns the category name.

...
  <aspectHistogramContainer>
    <domainName>Digital_Cameras</domainName>
    <domainDisplayName>Digital Cameras</domainDisplayName>
    <aspect name="Brand">
      <valueHistogram valueName="Canon">
        <count>198</count>
      </valueHistogram>
      <valueHistogram valueName="Casio">
        <count>2</count>
      </valueHistogram>
      <valueHistogram valueName="Kodak">
        <count>12</count>
      </valueHistogram>
      <valueHistogram valueName="Konica">
        <count>14</count>
      </valueHistogram>
      <valueHistogram valueName="Konica Minolta">
        <count>12</count>
      </valueHistogram>
      <valueHistogram valueName="Minolta">
        <count>2</count>
      </valueHistogram>
      <valueHistogram valueName="Mustek">
        <count>1</count>
      </valueHistogram>
      <valueHistogram valueName="Nikon">
        <count>26</count>
      </valueHistogram>
      <valueHistogram valueName="Olympus">
        <count>15</count>
      </valueHistogram>
      <valueHistogram valueName="Panasonic">
        <count>579</count>
      </valueHistogram>
      <valueHistogram valueName="Sony">
        <count>105</count>
      </valueHistogram>
      <valueHistogram valueName="Not Specified">
        <count>66</count>
      </valueHistogram>
    </aspect>
    <aspect name="Type">
      <valueHistogram valueName="Point & Shoot">
        <count>710</count>
      </valueHistogram>
      <valueHistogram valueName="SLR, Professional">
        <count>17</count>
      </valueHistogram>
      <valueHistogram valueName="Spy & Miniature">
        <count>2</count>
      </valueHistogram>
      <valueHistogram valueName="Underwater">
        <count>22</count>
      </valueHistogram>
      <valueHistogram valueName="Not Specified">
        <count>282</count>
      </valueHistogram>
    </aspect>
    ...
  </aspectHistogramContainer>
...

Constructing Filters

Aspect filters are constructed from data in the aspect histogram. For example, highlighted data in the following histogram can be used to create an aspect filter to refine your digital camera search to return only underwater cameras (of which there are 22):

Note: In the following example, the domainDisplayName field returns the category name and the domainName field returns the category name.

...
  <aspectHistogramContainer>
    <domainName>Digital_Cameras</domainName>
    <domainDisplayName>Digital Cameras</domainDisplayName>
	  ...
    <aspect name="Type">
      <valueHistogram valueName="Point & Shoot">
        <count>710</count>
      </valueHistogram>
	  ...
      <valueHistogram valueName="Underwater">
        <count>22</count>
      </valueHistogram>
	  ...
    </aspect>
    ...
  </aspectHistogramContainer>
...

Here's the corresponding aspect filter, which limits your search to underwater cameras only:

<aspectFilter>
  <aspectName>Type</aspectName>
  <aspectValueName>Underwater</aspectValueName>
</aspectFilter>

In a URL request, the same filter will look like this:

...&aspectFilter.aspectName=Type&aspectFilter.aspectValueName=Underwater...

Controlling the Way Search Results are Returned

In addition to filters, you can specify certain properties to control the way data is returned. These do not control which data is returned, but rather how it is sorted and the volume of the response.

Sorting Search Results

Use the sortOrder field in search requests (e.g., findItemsByKeywords) to specify the order in which the returned items are sorted. For example, you can specify a value of PricePlusShippingAsc to sort results by the combined cost of item price plus shipping cost, with the lowest priced items first. Or, you could use a value of EndTime to sort auctions by their end times, with those ending soonest first. Sorting has no affect upon the quantity of results returned.

The default sort order is by best match (BestMatch), which sorts items by relevancy to your search. Relevancy is based upon community buying activity and other relevance-based factors.

For more information, including available sort values, see the sortOrder input field in the API Reference. The available sort values are the same for all search calls in the Finding API.

Paginating Search Results

Use paginationInput and its child elements to break the items matching the search criteria down into smaller subsets, or "pages" of data. The paginationInput.entriesPerPage field specifies the maximum number of items to return for any given request. The paginationInput.pageNumber field specifies which "page" of data to return in the current call.

Sample pagination input (XML)

<paginationInput>
  <entriesPerPage>10</entriesPerPage>
  <pageNumber>2</pageNumber>
</paginationInput>

Sample pagination input (HTTP GET)

...&paginationInput.entriesPerPage=10&paginationInput.pageNumber=2...

There are corresponding fields in the response for paginating data. The paginationOutput.totalEntries field indicates the total number of items matching the input search criteria that could be returned (with one or multiple calls). If the value specified in paginationInput.entriesPerPage is less than that returned in paginationOutput.totalEntries, then it will take more than one call to retrieve all of the matching items. The paginationOutput.totalPages property indicates the total number of calls that would be required to retrieve all of the matching items. The value specified in the paginationInput.pageNumber field of search requests indicates where in the sequence of multiple calls the application is, relative to the number returned in paginationInput.totalPages.

Sample pagination output (XML)

<paginationOutput>
  <pageNumber>2</pageNumber>
  <entriesPerPage>10</entriesPerPage>
  <totalPages>21</totalPages>
  <totalEntries>207</totalEntries>
</paginationOutput>

The paginationOutput.entriesPerPage field indicates the maximum number of items that can be returned in a response. The count attribute for the searchResult field indicates the actual number of items returned in the response. The count value will typically match the entriesPerPage value, except when your search returns fewer results than the value specified in entriesPerPage or when retrieving the last page of results.

Selecting Additional Data to Return in Search Results

In the search results, searchResult.item contains a default set of data for items matching your request. If you want more data than the default data, you can use one or more outputSelector fields, as follows:

• SellerInfo—Include information about the seller in the response.
• StoreInfo—Include information about the seller's eBay store in the response.
• AspectHistogram—Include an AspectHistogram container with information about aspects from the category that is most relevant to your search.
• CategoryHistogram—Include a CategoryHistogram container with information about categories that match your search.

To use multiple outputSelector fields in a URL, an array notation is required, as shown in the following example:

...&outputSelector(0)=SellerInfo&outputSelector(1)=StoreInfo...

Retrieving Histogram Metadata

The histogram data returned by the Finding API provides statistics about the distribution of active items across categories and/or the distribution of active items associated with specific aspect values or item conditions.

Histogram data can help you refine search results to better locate relevant items.

Category Histograms

Category histograms return statistics for categories that match your search query or for a specified eBay category. You can retrieve a category histogram with the getHistograms call, or you can retrieve it with any of the search calls (e.g., findItemsByKeywords) by setting the outputSelector to CategoryHistogram. The histogram information consists of the following data for the specified category or category that best matches your search query, as well as for the immediate children categories:

• Category ID
• Category name
• Item count

For getHistograms and finding calls that take categoryId as input (i.e., findItemsByCategory, findItemsAdvanced, and findItemsIneBayStore), category histograms are typically returned for non-leaf categories only. For example, the category IDs returned for items in search results are for the leaf categories in which the items are listed. If you use these category IDs as input for finding calls or getHistograms, the response will not return a category histogram.

Aspect Histograms

Aspect histograms return statistics about aspects that match your search query or for a specified eBay category. Aspects are well-known, standardized characteristics of an item. For example, "Screen Size," "Processor Type," and "Processor Speed" could be aspects of Laptop PCs. Aspects can vary for different kinds of items. For example, the aspects of Laptop PCs are different from those of Women's Dresses (aspects for Women's Dresses might include "Sleeve Style," "Dress Length," and "Size"). Aspect histograms are returned for the category that is most pertinent to your search.

Along with the category name, the aspect histogram information consists of the following data for each aspect in the category:

• Aspect name (e.g., Brand)
• Aspect value name (e.g., Canon)
• Item count associated with a given aspect value

Note: The domainDisplayName and domainName fields returns the category name.

Aspect histogram information, such as the aspectHistogramContainer.domainName value, the value of the name attribute of aspectHistogramContainer.aspect, the value of the valueName attribute of aspectHistogramContainer.aspect.valueHistogram, and associated counts can be used in the user interface, just as eBay does in the left panel of search pages:

For getHistograms and finding calls that take categoryId as input (i.e., findItemsByCategory, findItemsAdvanced, and findItemsIneBayStore), aspect histograms are returned for those categories only.

The aspect and category metadata can also be used to create aspect and category filters to further refine your search results. See Refining a Search with Aspect Filters for details.

Condition Histograms

Condition histograms return statistics about the condition of the items that match your search query. That is, they indicate how many items are new, used, refurbished, or in some other condition.

For users who are only interested in new items, condition histograms can provide a useful view of the number of brand new, "new other (see details)", and "like new" items available. For users who are curious about used items, condition histograms can provide a quick view of the range of used items available.

You retrieve a condition histogram with any of the search calls (e.g., findItemsByKeywords) by setting the outputSelector to ConditionHistogram, or by using the getHistograms call. The histogram information consists of the following data for each condition:

• Condition ID (e.g., 1000)
• Condition display name (e.g., "Brand new")
• Item count

Condition histograms only count items that have condition IDs. Condition histograms are supported on all eBay sites except US eBay Motors, India (IN), Malaysia (MY), and Philippines (PH). This support depends on the site you search (not on the site where the items are listed). For example, international and US eBay Motors items (with condition IDs) that are available in eBay US search results are counted in condition histograms on the US site.

Condition histograms are not returned in search calls when you use Condition as an item filter to narrow your search based on specific conditions. That is, they are only available before you have chosen to filter items based on condition.

Affiliate Tracking

Affiliates earn money from eBay for driving traffic to eBay. For more information, see eBay Partner Network.

eBay knows that a sale came from your application because you include your affiliate ID in your API calls. Affiliate tracking is enabled for all of the search calls in the Finding API.

Affiliate-related fields, which are included in a call request using the affiliate container, enable the tracking of user activity. The affiliate container has the following fields: networkId, trackingId, and customId. If you are registered with eBay Partner Network, the networkId is 9 and the trackingId is the Campaign ID. The Campaign ID is given to you by eBay Partner Network.

The networkId specifies the third party who is your tracking partner. When specifying affiliate details, this field is required. Not all partners are valid for all sites.

The trackingId specifies an ID to identify you to your tracking partner. The value you specify is obtained from your tracking partner. For eBay Partner Network, the trackingId is the Campaign ID ("campid") provided by eBay Partner Network. A Campaign ID is a 10-digit, unique number to be used for associating traffic. A Campaign ID is valid across all programs to which you have been accepted.

The customId need not be specified. You can define a customId (up to 256 characters) if you want to leverage it to better monitor your marketing efforts. If you are using the eBay Partner Network, and you provide a customId, it will be contained in the tracking URL returned by eBay Partner Network.

The following example shows sample input with the affiliate container:

Sample Input for Affiliate Tracking (XML)

...
<affiliate>
  <trackingId>1234567899</trackingId>
  <networkId>9</networkId>
  <customId>234</<customId>
</AffiliateTrackingDetails>
...

The following example shows how to specify your affiliate tracking details in a URL:

Sample Input for Affiliate Tracking (URL)

...&affiliate.trackingId=1********9&affiliate.networkId=9&affiliate.customId=234...

When you use the AffiliateTrackingDetails container, a URL is returned that includes information for tracking user activity.

The following example shows a sample URL returned after you specified a TrackingPartnerCode of 9 in the AffiliateTrackingDetails container:

Sample Output URL For Affiliate Tracking

<viewItemURL>
  http://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=1234567899&customid=234&toolid=0&mpre=http%3A%2F%2F
  cgi.ebay.com%2FWhite-Apple-iPod-M9245LL-A_W0QQitemZ170001978557QQcmdZViewItemQQptZLH_DefaultDomain_0%3Fhash%3D
  item170001978557
</viewItemURL>

For more information about the Affiliate Program, see eBay Partner Network.

Combining with Other eBay APIs

The Finding API can be used in conjunction with any of the eBay APIs. We recommend you try using the Finding API together with one or more of the following APIs.

eBay Shopping API

The Shopping API can be used to augment the Finding API to create a rich buy-side application. The Shopping API provides calls to search for products and reviews, user info, and popular items and searches. It also provides data that can be used by the Finding API. For example, you can use FindProducts to retrieve the eBay Product Reference ID for use as input for the findItemsByProduct call or use GetCategoryInfo to retrieve the eBay category ID numbers for use with findItemsByCategory.

See the eBay Shopping API Getting Started Guide and eBay Shopping API Reference for more information.

eBay Merchandising API

If you are using the Finding API to build a buying application, you may want to consider using it in conjunction with the Merchandising API. The Merchandising API provides item and product recommendations that can be used to cross-sell and up-sell eBay items to buyers. With the Merchandising API, buying applications can provide suggested products or item listings based on buyers' searching or selection activity.

See the eBay Merchandising API Users Guide and eBay Merchandising API Reference for more information.

eBay Trading API

eBay Trading API offer authenticated access to eBay data. Much of the Trading API is geared toward helping sellers list items, retrieve seller sales status, manage post-transaction fulfillment, and accessing private user information such as My eBay and Feedback details. If you are familiar with the Trading API, it can be used to retrieve additional details about users, items, or categories. For example, the GetCategoryFeatures call in the Trading API can help you to programmatically download details about the supported condition IDs per category and site. Also, the PlaceOffer call in the Trading API allows your buying application to initiate the item purchase flow on eBay.

See the eBay Features Guide and eBay Trading API Reference for more information.

Additional eBay APIs

See the API Documentation page to learn more about eBay APIs.

Back to top

Working with the Finding API

The Finding API is simple and easy to use. This section outlines the fundamentals of how to use the Finding API.

See Making a Call for information about how to construct and submit a Finding API call. Refer to the API Reference for details about the API structure and logic.

Authentication

All that is required to use the Finding API is an AppID. If you already have an AppID for use with another eBay API, such as the Shopping or Merchandising APIs, it will work for the Finding API, as well. You must specify your AppID in the X-EBAY-SOA-SECURITY-APPNAME HTTP header (or SECURITY-APPNAME URL parameter) of every request.

API Call Limits

Please refer to the API Call Limits page on the eBay Developers Program site for current default call limits and call limits for applications that have completed the Compatible Application Check, which is a free service that the eBay Developers Program provides to its members.

Limitations and Restrictions

eBay Motors Searches

The eBay Motors site, global ID EBAY-MOTOR, does not support searching by product.

Ticket and Product Searches

The search refinement provided by aspect filters are especially useful in searches for tickets and products.

Mature Content

The Finding API does not return mature content in the response. All items from categories marked for mature users are filtered out and not returned in the response.

Sandbox Environment

The Finding Service is supported in the eBay Sandbox environment, but the Production environment is preferred for testing. Since the Finding API does not modify any item or user data, you can safely test your application with calls to the live eBay site. The Production environment also has more comprehensive and pertinent data.

For more information about testing, refer to Testing Overview in the Making a Finding API Call document.

API Reference

Refer to the API Reference for a list of calls in the Finding API. The API Reference includes the following information:

• Prototypes of the request and response structure for each call
• Comprehensive list of inputs and outputs supported by each call and descriptions of their meaning and behavior
• Call samples (request and response)
• Index of schema elements (types, fields, enumerations)
• Change history information for each call

Back to top

Additional Resources

You can get more information about the Finding API at these locations:

• Making a Call
• API Reference
• Release Notes

Back to top