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 provides functionality that is similar to the search calls in the Trading Shopping APIs, but it provides more relevant search results, because it uses eBay's next generation search technology.
The APIs provide the following capabilities:
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.
Refer to the eBay Finding API Call Reference for a list of API calls and the associated inputs and outputs for each.
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:
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 subtitle, returning those items in the result set. The value specified in the keywords field can contain one or more keywords and combinations of wildcard characters. 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. Wildcard characters (e.g., "*") are also supported. Be careful when using spaces before or after modifiers and wildcard characters, such as plus signs ("+"), minus signs ("-"), or asterisks ("*").
The following table shows the operators and character punctuation that can be used in keyword queries, and what the effects they have.
| Operator | Description | Example | Returns |
|---|---|---|---|
| Space between words | Applies AND logic to multiple keywords. | baseball cardOR baseball%20card |
Items with both the words "baseball" and "card". |
| Comma between words, no parentheses | Applies AND logic to multiple keywords. | baseball,card |
Items with both the words "baseball" and "card". |
| Comma between words in parentheses | Applies OR logic to multiple keywords. | (baseball,card) |
Items with either the word "baseball" or the word "card". |
| Quoted words | Requires an exact sequence of words. | "baseball card" |
Items with the exact phrase "baseball card". |
| Minus ("-") sign before a word | Specified word cannot be present. | baseball -autograph |
Items that have the word "baseball" but not "autograph". |
| Minus ("-") sign before a group of words in parentheses | 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* |
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". |
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 Trading API GetCategories call.
| Note: With findItemsAdvanced, you can combine a keyword query search for items with a search by category. |
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:
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.
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 ...
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 ...
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.
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.
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:
...
<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>
...
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):
...
<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...
Here's the domain filter, which will further restrict your search results to digital cameras only:
<domainFilter> <domainName>Digital_Cameras</aspectName> </domainFilter>
| 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 Call Reference for details about the call. |
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.
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 Call Reference. The available sort values are the same for all search calls in the Finding API.
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.
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:
...&outputSelector(0)=SellerInfo&outputSelector(1)=StoreInfo...
The histogram data returned by the Finding API provides statistics about the distribution of active items across categories or the distribution of active items associated with specific aspect values.
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:
Histogram data can help you refine search results to better locate relevant items.
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 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 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 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.
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=1234567899&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.
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.
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 in the eBay Shopping API to retrieve the desired eBay Product Reference ID for use as input for the findItemsByProduct call.
See the eBay Shopping API Getting Started Guide and eBay Shopping API Call Reference for more information.
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 Call Reference for more information.
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. However, the GetCategories call in the Trading API can help you access category IDs needed to make your search or histogram calls in the Finding API. Also, the PlaceOffer call in the Trading API allows your buying application to initiate the item purchase flow on eBay.
See the eBay Trading API Guide and eBay Trading API Call Reference for more information.
See the Products page to learn more about eBay Web Services products and upcoming product releases and feature enhancements.
The Finding API is simple and easy to use. This section outlines the fundamentals of how to use the Finding API.
See Making an API Call for information about how to construct and submit a Finding API call. Refer to the Call 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.
The standard call limit for the Finding API is 5000 calls per day per IP address. The call limit can be increased to up to 1.5 million calls per day per IP address by completing the Compatible Application Check, which is a free service that the eBay Developers Program provides to its members.
The eBay Motors site, global ID EBAY-MOTOR, does not support searching by product.
The Ticket Finder and Product Finder capabilities supported in GetSearchResults in the Trading API are not directly supported in the Finding API. However, the search refinement provided by aspect filters provide some of this functionality.
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 not currently 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.
The Finding API provides functionality that is similar to GetSearchResults in the Trading API and FindItemsAdvanced in the Shopping API, but uses the same search technology used to power eBay site searches. The following guides map input and output fields for these calls to corresponding input and output fields in findItemsAdvanced in the Finding API:
Refer to the Call Reference for a list of calls in the Finding API. The Call Reference includes the following information:
You can get more information about the eBay Finding API at these locations:
Share tips or code samples related to this call or topic. Questions or observations are welcome, too.
eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.
© 2008–2009 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.