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:
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 Finding API exposes domain and aspect information, which is different from existing APIs. Domains, such as shoes or digital cameras, are a buy-side grouping of items. A domain can span many eBay categories. Aspects are item characteristics shared by items in a given domain. For example, in the Shoes domain, aspects include Style, Color, and Shoe Size. In the Digital Cameras domain, aspects include Product Type, Brand, Megapixels, and Optical Zoom. The search calls and the getHistogram call return domain and aspect metadata that can be used to refine searches.
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 search features help you get the most relevant search results possible with your keyword queries:
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.
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.
|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.
See Search Expansion in the eBay Site help pages for examples and additional 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), aspect filters (aspectFilter), and domain filters (domainFilter) 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 some product matches in addition to matching items. If you follow one of the book links to a product details page, 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.
The following link will open the product details page for the hard cover edition of Harry Potter and the Chamber of Secrets.
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.
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 and Domain Filters
The search calls, such as findItemsByKeywords and findItemsAdvanced can return domain and 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 domain that is most pertinent to your search, and information for all of the aspects (e.g., Brand) used in the domain.
What are Domains and Filters?
Domains are a buy-side grouping of items, such as women's dresses, wristwatches, men's shoes, or digital cameras. Categories, on the other hand, are containers sellers use to list their items (for information on finding items in categories, see Searching and Browsing by Category). Domains are like departments in a department store (e.g., 3rd floor, Women's Dresses, Women's Shoes, and Women's Handbags, Bags).
A domain can span many eBay categories and some categories may be included in more than one domain. For example, a pair of men's baseball cleats in the Men's Athletic Footwear domain might be listed in the Sporting Goods category or in the Clothing Shoes & Accessories category. A men's dive watch may also be listed in Sporting Goods, but it is in the Wristwatches domain.
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 given domain. 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 domain. For example, although the domain for women's dresses and the domain for wedding dresses may have some similar aspects, such as size, many aspects differ between the two domains. When the response does contain an aspect histogram, it is returned for the domain 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:
<valueHistogram valueName="Konica Minolta">
<valueHistogram valueName="Not Specified">
<valueHistogram valueName="Point & Shoot">
<valueHistogram valueName="SLR, Professional">
<valueHistogram valueName="Spy & Miniature">
<valueHistogram valueName="Not Specified">
Aspect and domain 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):
<valueHistogram valueName="Point & Shoot">
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:
Here's the domain filter, which will further restrict your search results to digital cameras only:
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.
|Note: In general, when you are not searching within Stores, Store Inventory listings are returned after auctions, basic Fixed Price, and other listing types.
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:
- 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 domain 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:
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 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.
|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 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 domain that is most pertinent to your search.
Along with the domain name, the aspect histogram information consists of the following data for each aspect in the domain:
- Aspect name (e.g., Brand)
- Aspect value name (e.g., Canon)
- Item count associated with a given aspect value
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 categories that have been mapped to domains only. In most cases, just leaf categories are mapped to domains, but there are exceptions. For example, the Binoculars category (cagtegory ID 38880) is not a leaf category, but it does return an aspect histogram.
The aspect and domain metadata can also be used to create aspect and domain filters to further refine your search results. See Refining a Search with Aspect and Domain Filters for details.
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.
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 ti 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 Products page to learn more about eBay APIs products and upcoming product releases and feature enhancements.
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.
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.
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.
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
You can get more information about the Finding API at these locations:
Back to top
Copyright © 2009–2013 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.