eBay Finding API

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:

Note: The Finding API uses the same technology used to power the eBay site search. However, due to application logic employed by the eBay site, site search results may not always match identically with the results returned by the API for similar search criteria.

For example, if you enter an ISBN number only as a search query on the eBay site, the application logic for the eBay site will recognize the format and perform a search by product ID. If you make a similar API request (i.e., pass the ISBN in the keywords field of findItemsByKeywords), the search results are not likely to match those from the site search.

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:

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:

The following use cases are described in this section:

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

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 ("-").

Note: If you are using name-value syntax for a REST-style request, input values must be URL-encoded. For example, @1 baseball autograph card +star would be URL-encoded as %401+baseball+autograph+card+%2Bstar and "baseball card" would be URL-encoded as %22baseball+card%22. For more information, see the Name-value Syntax section in Making a Call.

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

Operator Description Example Returns
Space between words Applies AND logic to multiple keywords. baseball card Items with both the words "baseball" and "card".

Note: Keyword queries consisting of keywords separated by spaces only are subject to automatic keyword expansions.

Comma (,) between words, with no parentheses or spaces Requires an exact sequence of words. baseball,card Items with the exact phrase "baseball card" in the title. This is equivalent to specifying the keywords, separated by spaces, in order within quotation marks (e.g., "baseball card").
Comma between words in parentheses with no spaces Applies OR logic to multiple keywords. (baseball,card) Items with either the word "baseball" or the word "card" in the title.
Quoted (" ") words Requires an exact sequence of words. "baseball card" Items with the exact phrase "baseball card" in the title.
Minus ("-") sign before a word Applies NOT logic to a single word. Specified word cannot be present. baseball -autograph Items that have the word "baseball" but not "autograph".

Note: A keyword query cannot consist of excluded words only. You must include one or more search terms in order to use the NOT operator ("-"). For example, "-autograph" is not a valid keywords value on its own, but "baseball -autograph" (i.e., <keywords>baseball -autograph</keywords>) will work.

When excluding words, you must have a space before the minus sign and no space between the minus sign and the word you are excluding.

Minus ("-") sign before a group of words in parentheses Applies NOT logic to a group of words. Specified words cannot be present. baseball -(autograph,card,star) Items with the word "baseball" but not "autograph," "card," or "star".
Asterisk ("*") Substitutes for one or more characters. baseball* This operator is no longer supported. Items starting with the string "baseball". Use with a minimum of 2 characters.
At sign ("@") Search must find two of three words from a list. @1 baseball autograph card Items with two of the three words "baseball," "autograph," and "card". For a "3 out of 4" search, use @2 and a list of four words.
Plus sign ("+") Concatenates a query string using AND logic with another keyword. @1 baseball autograph card +star Items with any two of the three words "baseball," "autograph," or "card" in the title plus the word "star".

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.

Expansion Type Description
Keyword to keyword Modifies your keyword query to search for either your original keywords, or a synonymous keyword from eBay's dictionary, such as a root word or a plural form.
Keyword to category Modifies your query to search for items that have a specific keyword in the title or for items listed in a specific related category.
Keyword to structured item data Modifies your query to search for items that have the keywords from the original query in the title or in the item's structured data, such as item specifics or parts compatibility information.

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.

Note: With findItemsAdvanced, you can combine a keyword query search for items with a search by category.

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:

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.


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


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


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:


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


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.

Note: Starting October 2014, domains will be deprecated.
The Finding calls will continue to accept requests containing references to domains (such as domainFilter) and will continue to return references to domains (such as domainDisplayName).
The behavior will differ, as follows, depending on the fields specified in the request/response.
  • The input field domainFilter will be ignored. Use categoryId for equivalent behavior.
  • In the response for <outputSelector>aspectHistogram</outputSelector>:
    • The aspectHistogramContainer field will show the aspects in the category.
    • The domainDisplayName field will show the category name.
    • The domainName field will show the category name.
  • Everywhere else, "domain" should be considered as analogous to "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.

    <domainDisplayName>Digital Cameras</domainDisplayName>
    <aspect name="Brand">
      <valueHistogram valueName="Canon">
      <valueHistogram valueName="Casio">
      <valueHistogram valueName="Kodak">
      <valueHistogram valueName="Konica">
      <valueHistogram valueName="Konica Minolta">
      <valueHistogram valueName="Minolta">
      <valueHistogram valueName="Mustek">
      <valueHistogram valueName="Nikon">
      <valueHistogram valueName="Olympus">
      <valueHistogram valueName="Panasonic">
      <valueHistogram valueName="Sony">
      <valueHistogram valueName="Not Specified">
    <aspect name="Type">
      <valueHistogram valueName="Point & Shoot">
      <valueHistogram valueName="SLR, Professional">
      <valueHistogram valueName="Spy & Miniature">
      <valueHistogram valueName="Underwater">
      <valueHistogram valueName="Not Specified">

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.

    <domainDisplayName>Digital Cameras</domainDisplayName>
    <aspect name="Type">
      <valueHistogram valueName="Point & Shoot">
      <valueHistogram valueName="Underwater">

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


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

Note: The getHistogram call can also be used to retrieve aspect histograms. Refer to Retrieving Histogram Metadata for more information about the histogram data. Refer to getHistograms in the API Reference for details about the call.

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)


Sample pagination input (HTTP GET)


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)


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:

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


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:

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.

Note: When searching the US eBay Motors site, category histograms may not be available for some parent categories. In these cases, aspect histograms should be used to refine search results. This behavior is consistent with US eBay Motors site search behavior.

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:

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:

eBay Aspects

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


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

Sample Input for Affiliate Tracking (URL)


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


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.


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:

Back to top

Additional Resources

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

Back to top