Finding API

Finding API Release Notes

You can find links to the Finding API documentation in the top navigation bar. Information about the schema location is in the Schema Location section of the "Making a Call" topic.

Are you just getting started with the Finding API? The following describes how to join the eBay Developers Program:

Version Release Date  
1.12.0 2012-05-16  
1.11.0 2011-06-07  
1.10.0 (no documentation updates) 2011-02-16  
1.9.0 2010-12-08  
1.8.0 2010-10-06  
1.7.0 2010-09-01  
1.6.0 2010-07-07  
1.5.0 2010-06-09  
1.4.0 2010-03-31  
1.2.0 2010-01-20  
1.1.0 2009-11-11  
1.0.1 2009-09-29  
1.0.0 (documentation updates) 2009-09-10  
1.0.0 2009-06-24  

Version 1.12.0

Index of Changed Calls - 1.12.0

Schema Changes - 1.12.0

Announcements - 1.12.0

New Features - 1.12.0

Changed Functionality - 1.12.0

Documentation Changes and Errata - 1.12.0


For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.

Index of Changed Calls - 1.12.0

These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.

New Calls

No new calls in this release.

Changed Calls

Schema Changes - 1.12.0

None for this release.

Announcements - 1.12.0

Change Requests

See the Site Status for bug fixes related to this release.

New Features - 1.12.0

This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.

For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1.12.0.

None for this release.

Changed Functionality - 1.12.0

This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.

None for this release.

Documentation Changes and Errata - 1.12.0

This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1.12.0 and Changed Functionality - 1.12.0.

The following documentation changes comprise the total changes in calls for this release.

topRatedListing Functionality Clarified

In the API Reference documentation, topRatedListing had appeared erroneously under searchResult.item.sellerInfo. It now appears in its correct location under searchResult.item, with an updated description.

unitPrice Functionality Clarified

In the API Reference documentation, unitPrice had appeared erroneously under searchResult.item.sellerInfo. It now appears in its correct location under searchResult.item, with an updated description. The unitPrice container and its child fields, quantity and type, are returned only if the value of outputSelector is UnitPriceInfo.

shippingInfo Functionality Clarified

Three shippingInfo fields (expeditedShipping, handlingTime and oneDayShippingAvailable) are returned only for items listed on the eBay US site. This was not previously made clear in the field descriptions.

itemFilter Functionality Clarified

The itemFilter container provides the specifications for limiting the number of items returned by a find request. Use itemFilter to specify name/value pairs. The itemFilter.name field (ItemFilterType) provides the names of filters that can be used to limit the number of items returned by a find request. Each name must be accompanied by a corresponding itemFilter.value field. See the ItemFilterType reference page for descriptions of the available filters.

outputSelector and aspectFilter Functionality Clarified

If a call that specifies an outputSelector value of AspectHistogram returns aspectHistogramContainer.domainName, this is a sign that aspect histogram data might not be returned if you also specify an aspectFilter in the next call. To ensure that aspect histogram data is returned for the next call, add a domainFilter to the call as well.

Back to top

Version 1.11.0

Index of Changed Calls - 1.11.0

Schema Changes - 1.11.0

Announcements - 1.11.0

New Features - 1.11.0

Changed Functionality - 1.11.0

Documentation Changes and Errata - 1.11.0


For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.

Index of Changed Calls - 1.11.0

These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.

New Calls

Changed Calls

Schema Changes - 1.11.0

Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.

Name Part of Schema Type of Change
Affiliate.geoTargeting Element New
BaseFindingServiceRequest.affiliate Element Removed
BaseFindingServiceRequest.buyerPostalCode Element Removed
BaseFindingServiceRequest.paginationInput Element Removed
BestMatchFindingServiceRequest Complex type New
DiscountPriceInfo Complex type Reserved for future use
FindItemsByImageRequest Complex type New
FindItemsByImageResponse Complex type New
FindItemsByImageResponse.aspectHistogramContainer Element New
FindItemsByImageResponse.categoryHistogramContainer Element New
FindItemsByImageResponse.conditionHistogramContainer Element New
GalleryInfoContainer Complex type New
GallerySizeEnum Enumerated type New
GalleryURL Complex type New
MapExposureEnum Enumerated type Reserved for future use
OutputSelectorType.GalleryInfo Enum New
OutputSelectorType.PictureURLLarge Enum New
OutputSelectorType.PictureURLSuperSize Enum New
PriceTreatmentEnum Enumerated type Reserved for future use
SearchItem.discountPriceInfo Element Reserved for future use
SearchItem.galleryInfoContainer Element New
SearchItem.isMultiVariationListing Element New
SearchItem.pictureURLLarge Element New
SearchItem.pictureURLSuperSize Element New

Announcements - 1.11.0

Wildcard Searches on eBay are Deprecated

eBay is deprecating wildcard (*) queries from all search tools and functions, including Web and mobile search, saved searches, and searches made through API calls. For more information, refer to the Wildcards in eBay Searches deprecated product update page.

Change Requests

See the Site Status Updates page for the status of any system-wide issues that may affect this API.

New Features - 1.11.0

This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.

For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1.11.0.

Condition Histograms

When you search for items, you can now also retrieve histograms that show the distribution of item results based on their condition (e.g., the number of items that are new vs. used). Condition histograms are supported on all eBay sites except US eBay Motors, India (IN), Malaysia (MY), and Philippines (PH).

The getHistograms call returns condition histograms when items in the specified category include conditionId (i.e., the seller has specified a condition), and you are searching a site other than the four listed above.

The item search calls (e.g., findItemsAdvanced) return condition histograms when all of the following are true:

New Call: findItemsByImage

The new findItemsByImage call lets you search for items on eBay with images that match or have similar characteristics of the image of another specific eBay item. The matching criteria for this call includes image characteristics, such as color, texture, and shape, as well as item characteristics, such as title.

Use this call to find matching clothing, shoes, or accessories for a given eBay item listed in Clothing, Shoes & Accessories catgories.

This call is restricted to items listed in Clothing, Shoes & Accessories (parent category ID 11450 on the US site) categories only. The specified item, whose image is used for matching, must be listed in a Clothing, Shoes & Accessories category, and the results will contain items from Clothing, Shoes & Accessories categories only.

This call is supported on the eBay US site (global ID EBAY-US), eBay UK site (global ID EBAY-GB), and the eBay Germany site (global ID EBAY-DE) only, currently.

New Call: findCompletedItems

The new findCompletedItems call gives you the ability to retrieve items whose listings are completed and are no longer available for sale on eBay.

There is a 5,000 limit on the number of findCompletedItems calls an application can make in a single day (even if the application has completed an app check). Be aware that it is possible to use this call in such a way as to violate the terms and conditions of your API License Agreement. Ensure that you do not store the results retrieved from this call or use the results for market research purposes.

Added Item Image Thumbnails

When you search for items, you can now request the inclusion of an array of item image thumbnail URLs for various standard sizes in the response. When you set outputSelector to GalleryInfo, the image thumbnail URLs are returned for each item in the GalleryInfoContainer node.

Each galleryInfoContainer node contains three thumbnail image URLs for different sizes: large (up to 140 pixels on the longest side), medium (up to 96 pixels on the longest side), and small (up to 80 pixels on the longest side).

Added the Ability to Retrieve Large Images

Using the outputSelector values PictureURLSuperSize and PictureURLLarge, you can retrieve URLs for pictures that are 800x800 and 400x400 pixels in size, respectively.

Updated the Returned Affiliate/Roveriezed URL Addresses

Set the geoTargeting element to 1 to specify that you want the affiliate link returned as a roverized geo-targeted affiliate link.

Added the Ability to see if an Item is a Multi-Variation Listing

The return element isMultiVariationListing returns True if the item is a multi-variation listing, otherwise it returns False.

Discount Pricing Information Enables You To Create Special Price Display Treatments

Sellers can specify discount pricing values for an item to give the item either a Strike-Through Pricing (STP) or Minimum Advertised Price (MAP) display treatment. This feature is available to qualified sellers (and their associated developers) who participate in the Discount Pricing program. Once qualified, sellers can apply Discount Pricing to both MSKU and Non-MSKU items. STP is available on the US, UK, and DE sites while MAP is available only on the US site. For more information, see: Displaying Discount Pricing Information to Buyers.

Support for World-wide Searches

In addition to country codes, the LocatedIn item filter supports the following region values for broader searches (note capitalization and spaces):

Changed Functionality - 1.11.0

This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.

AvailableTo and LocatedIn Can Be Used Together

In prior releases, the AvailableTo and LocatedIn item filters were mutually exclusive. These filters can now be used together. For example, you can use the following filter to find items located in Germany that are available to the United States:

   <itemFilter>
      <name>LocatedIn</name>
      <value>DE</value>
   </itemFilter>
   <itemFilter>
      <name>AvailableTo</name>
      <value>US</value>
   </itemFilter>

Documentation Changes and Errata - 1.11.0

This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1.11.0 and Changed Functionality - 1.11.0.

Updates to the Documentation for findCompletedItems

The information for this call has been revised to include the following topics: