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?

Announcement

New WatchCountDecreaseSort SortOrder Value Now available

When you set SortOrder to WatchCountDecreaseSort, items are sorted by their watch count value in descending order (highest to lowest count). The watch count represents the number of users that have added the item to their watch list and is an indicator of how much interest there is in this item. This is supported only in the findItemsAdvanced call. Note: The watch count value of an item is not retuned in the response.

Version 1.13.0

Index of Changed Calls - 1.13.0

Schema Changes - 1.13.0

Announcements - 1.13.0

New Features - 1.13.0

Changed Functionality - 1.13.0

Documentation Changes and Errata - 1.13.0

For a current list of known issues, see Site Status Updates and the Knowledge Base.

Index of Changed Calls - 1.13.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

• findCompletedItems
• findItemsAdvanced
• findItemsByCategory
• findItemsByImage
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.13.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.

Announcements - 1.13.0

Over time the difference between domain, which is a grouping of items, and category, which is also a grouping of items, has become negligible. Filtering by category provides the same results. To support new features, eBay is deprecating domains. An analysis of the domainFilter field usage was conducted. The result was the usage of this field was very low, and of the apps that were using this field most were also using the categoryID field. So in Oct. 2014, the domainFilter field will be deprecated.

However, there is no need to worry. Calls that use the domainFilter field will not fail, but the field will be ignored and a warning will be returned. Apps that use only domainFilter should remove the field and add the categoryID field. Apps that use both domainFilter and categoryID, we recommend you remove domainFilter at your earliest convenience.

With this change the aspectHistogramContainer field will show the aspects of a category and the domainDisplayName and the domainName fields will contain a category name.

Change Requests

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

New Features - 1.13.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.13.0.

New eekStatus Field Added

The new eekStatus field was added to return the energy efficiency rating of an item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only. Rating values are of the form A+++, A++, A+, A, B, C, D, E, F, or G. This field is only returned if the seller has specified the energy efficiency rating in the item specifics. Note: This is applicable only to the eBay Germany site (EBAY-DE).

Changed Functionality - 1.13.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.13.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.13.0 and Changed Functionality - 1.13.0.

None for this release.

Back to top

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 API Call Limits page 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

• findCompletedItems
• findItemsAdvanced
• findItemsByCategory
• findItemsByImage
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

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 API Call Limits page 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

• findCompletedItems
• findItemsByImage

Changed Calls

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

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.

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:

• You pass ConditionHistogram in outputSelector, and
• You don't pass Condition in itemFilter (i.e., you have not yet narrowed your search based on specific conditions), and
• You are not searching eBay US Motors, India, Malaysia, or Philippines, and
• The items found include conditionId (i.e., the seller has specified a condition).

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 categories.

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

• WorldWide
• North America
• European

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:

• A new code sample and a description of its scenario have been added to the documentation of this call.
• An update of the description of the findCompletedItems call to explain that the Best Match sort is not supported by this call.
• The availability of a new enumeration value, SoldItemsOnly, for an ItemFilter. This enum value only applies to the findCompletedItems call. This enum value is not used by any other Finding API call.

Back to top

Version 1.9.0

Index of Changed Calls - 1.9.0

Schema Changes - 1.9.0

Announcements - 1.9.0

New Features - 1.9.0

Changed Functionality - 1.9.0

Documentation Changes and Errata - 1.9.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.9.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

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.9.0

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

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.

Announcements - 1.9.0

Change Requests

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

New Features - 1.9.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.9.0.

New Item Filter for ValueBox Items

The ValueBoxInventory item filter is made available to the Finding API calls. When used along with the sort order PricePlusShippingLowest, this filter returns items meeting eBay Value Box criteria (listed by an eBay Top Seller, BuyItNow price, competitively priced) with the lowest price item at the top of the returned list.

Changed Functionality - 1.9.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.9.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.9.0 and Changed Functionality - 1.9.0.

buyItNowAvailable Applies to Auctions Only

The buyItNowAvailable output field (searchResult.item.listingInfo.buyItNowAvailable) applies only to auction listings that were listed with a Buy It Now price. The only situation in which buyItNowAvailable returns "true" is when the listing type (searchResult.item.listingInfo.listingType) is "AuctionWithBIN" and no bids that meet or exceed the reserve price have been placed on the item.

buyItNowAvailable will return "false" if the listing type (searchResult.item.listingInfo.listingType) is anything but "AuctionWithBIN". Please ignore buyItNowAvailable for fixed-price listings.

Best Match in API Differs from Best Match on eBay Site

eBay site search results sorted by Best Match may not match the API search results sorted by Best Match. The site Best Match algorithm takes into account additional factors that are not available to the API. See sortOrder for information about sorting options available to the Finding API search calls.

Automatic Search Expansion

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.

The Searching by Keywords section in the Finding API Users Guide has been updated to document automatic keyword expansions and describe the behavior of search operators more accurately.

Back to top

Version 1.8.0

Index of Changed Calls - 1.8.0

Schema Changes - 1.8.0

Announcements - 1.8.0

New Features - 1.8.0

Changed Functionality - 1.8.0

Documentation Changes and Errata - 1.8.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.8.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

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.8.0

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

Announcements - 1.8.0

Change Requests

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

New Features - 1.8.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.8.0.

New Item Filters for Gifting, Holiday or other Similar Events

Starting in late November 2010 on the US, UK, and DE sites, a new set of item filters will be available to help buyers locate items for which expedited shipping is available, returns accepted, and for which a specified maximum handling time is available. Each of these filters can be used individually, or they can be combined to produce the desired results.

ExpeditedShippingType is used together with the MaxHandlingTime and ReturnsAcceptedOnly filters to filter items for certain kinds of gifting events such as birthdays or holidays where the items must be delivered by a certain date.

If you wish to mimic the behavior of the eBay holiday filters, you would use ExpeditedShippingType set to either Expedited or OneDayShipping, MaxHandlingTime to 1, ReturnsAcceptedOnly set to true, and for the Germany site, set PaymentMethod to PayPal. (The holiday filters may not always be available in the eBay UI, depending on the season; however, the equivalent filter behavior continues to be available in the API.)

The following example shows how you might construct a findItemsAdvanced request using these new item filters to get items appropriate for gifting in a scenario where the buyer needs the item quickly. Because the items are desired for a gift, we use the ReturnsAcceptedOnly filter. Because we are getting close to the event (birthday, Christmas, etc.) we want only those items that ship within one day from the seller (one day handling), and we want only items that provide expedited shipping.

<findItemsAdvancedRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <paginationInput>
      <entriesPerPage> 2
      </entriesPerPage>
   </paginationInput>
   <keywords>Potter</keywords>
   <itemFilter>
      <name>ExpeditedShippingType</name>
      <value>Expedited</value>
   </itemFilter>
   <itemFilter>
      <name>ReturnsAcceptedOnly</name>
      <value>true</value>
   </itemFilter>
   <itemFilter>
      <name>MaxHandlingTime</name>
      <value>1</value>
   </itemFilter>
   <itemFilter>
      <name>ListedIn</name>
      <value>EBAY-US</value>
   </itemFilter>
   <itemFilter>
     <name>LocatedIn </name>
     <value>US </value>
   </itemFilter>
</findItemsAdvancedRequest>

Changed Functionality - 1.8.0

None for this release.

Documentation Changes and Errata - 1.8.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.8.0 and Changed Functionality - 1.8.0.

None for this release.

Back to top

Version 1.7.0

Index of Changed Calls - 1.7.0

Schema Changes - 1.7.0

Announcements - 1.7.0

New Features - 1.7.0

Changed Functionality - 1.7.0

Documentation Changes and Errata - 1.7.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.7.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

No changed calls in this release.

Schema Changes - 1.7.0

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

Announcements - 1.7.0

Item Condition ID Changes

Item condition ID value 3000, Like New, will be deprecated around the end of September 2010 for media categories, such as Books or DVDs & Movies. It will be replaced by item condition ID value 2750. eBay will update existing items listed with condition ID value 3000 to use condition ID value 2750, but there may be a transition period of up to a month.

When the Condition item filter is applied with the text value "Used", the search results will include all types of used items, including "Like New" items, regardless of the condition ID value.

<itemFilter>
   <name>Condition</name>
   <value>Used</value>
</itemFilter>

Change Requests

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

New Features - 1.7.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.7.0.

None for this release.

Changed Functionality - 1.7.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.

Retrieving All Active Items for a Seller

You can use findItemsAdvanced with the Seller item filter to retrieve all active listings for a specific seller up to 10,000 listings (i.e., 100 pages of 100 entries per page). Although keywords and/or categoryId are normally required for a findItemsAdvanced request, the Seller item filter (itemFilter.name.Seller) can be used without these fields to retrieve a seller's active listings. See the Retrieve All Active Listings for a Seller findItemsAdvanced call sample for an example.

EndItemFrom and EndItemTo No Longer Mutually Exclusive

The EndItemFrom and EndItemTo item filters can now be used together to create a date range for retrieving listings based on end time.

<itemFilter>
   <name>EndTimeFrom</name>
   <value>2010-09-24T21:21:56.963Z</value>
</itemFilter>
<itemFilter>
   <name>EndTimeTo</name>
   <value>2010-09-24T21:31:56.963Z</value>
</itemFilter>

Documentation Changes and Errata - 1.7.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.7.0 and Changed Functionality - 1.7.0.

None for this release.

Back to top

Version 1.6.0

Index of Changed Calls - 1.6.0

Schema Changes - 1.6.0

Announcements - 1.6.0

New Features - 1.6.0

Changed Functionality - 1.6.0

Documentation Changes and Errata - 1.6.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.6.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

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.6.0

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

Announcements - 1.6.0

eBay URL Formats

eBay URLs returned in fields, such as viewItemURL, are subject to syntax and other changes without notice. To avoid problems in your application when eBay alters the URL format, we advise you to avoid parsing eBay URLs programmatically. We strive to ensure that other fields in the response contain all the information that is encoded in the URL, and more.

Change Requests

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

New Features - 1.6.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.6.0.

Viewing API Search Results on the eBay Site

The itemSearchURL field in the response of the item search calls provides a URL for viewing the search results on the eBay site. All search criteria (e.g., filters or keywords) and pagination settings are carried over to the site search page.

Charity Item Listing Filter

The CharityOnly item filter (...&itemFilter.name=CharityOnly&itemFilter.value=true...) restricts the search results to only items for which all or part of the proceeds are given to a charity. Each item in the response will have a charity ID (searchResult.item.charityId) eBay has assigned to a specific non-profit charity organization.

Changed Functionality - 1.6.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.

Item Condition Filter Supports Mixing Text and ID-Based Values

In the Condition item filter, you can now combine text and ID values. eBay processes the values using OR logic.

For example, to find all flavors of new items (e.g., Brand New, New other (see details), etc.) plus manufacturer or seller refurbished items (but not used items), you can pass the filter with values of New, 2000, and 2500 in the same request. (The order of the values has no effect. That is, the results are the same if you pass the values in this order: 2500, New, 2000.)

URL Example

&itemFilter(0).name=Condition&itemFilter(0).value(0)=New&itemFilter(0).value(1)=2000&itemFilter(0).value(2)=2500

XML Example

<itemFilter>
   <name>Condition</name>
   <value>New</value>
   <value>2000</value>
   <value>2500</value>
</itemFilter>

Documentation Changes and Errata - 1.6.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.6.0 and Changed Functionality - 1.6.0.

Array Indexing Clarifications for URL Requests

When more than one instance of a repeatable field, such as itemFilter, is used in a name-value pair (URL-style) request, the instances make up an array. The syntax rules for arrays in name-value requests have been updated to clarify proper indexing practices.

See the Name-value Syntax section in the Finding API Making a Call for more information and samples.

Back to top

Version 1.5.0

Index of Changed Calls - 1.5.0

Schema Changes - 1.5.0

Announcements - 1.5.0

New Features - 1.5.0

Changed Functionality - 1.5.0

Documentation Changes and Errata - 1.5.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.5.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

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.5.0

None for this release.

No WSDL is provided for this release. The latest supported version of the WSDL is 1.4.0.

Announcements - 1.5.0

eBay URL Formats

eBay URLs returned in fields, such as viewItemURL, are subject to syntax and other changes without notice. To avoid problems in your application when eBay alters the URL format, we advise you to avoid parsing eBay URLs programmatically. We strive to ensure that other fields in the response contain all the information that is encoded in the URL, and more.

Change Requests

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

New Features - 1.5.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.5.0.

None for this release.

Changed Functionality - 1.5.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.

Filter by Condition ID Values

Item search results now return an item's condition in some cases:

• If the seller entered the condition by using item specifics, the results include conditionDisplayName.
• If the seller entered the condition by using eBay's newer, more detailed conditions, the results include conditionDisplayName and conditionId.

In addition, new item filter values have been added to enable you to refine the results based on the item condition. Previously, you could filter against text values (New, Used, Unspecified). Now you can also use eBay's newer condition IDs. For example, you can specify "1000" and "2000" in the Condition filter to only return brand new and manufacturer-refurbished listings.

See the ItemFilterType type documentation for more information about the allowed filter values, usage rules, and dependencies.

Documentation Changes and Errata - 1.5.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.5.0 and Changed Functionality - 1.5.0.

Sort by Bid Count Site Restrictions

Sorting by bid count is supported on the eBay US (global ID EBAY-US), eBay Germany (global ID EBAY-DE), and eBay Australia (global ID EBAY-AU) sites only. To sort by bid count, you must specify a listing type filter to limit results to auction listings only (e.g., & itemFilter.name=ListingType&itemFilter.value=Auction).

This site restriction has been called out in the sortOrder documentation.

Item Condition Filter by Text Values

The item condition filter accepts multiple text values. Previously, the documentation had incorrectly said the Condition item filter accepted a single value only. When multiple text values (e.g., New and Unspecified) are specified, they use an OR logic. That is, the response excludes items with used, refurbished, or for parts conditions.

Site Search Results May Differ from API Search Results

A note has been added to the beginning of the Finding API Users Guide to clarify that the site search and API search may not return identical results 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.

MaxDistance Constraints

The MaxDistance description has been revised to indicate the practical minimum value (5) and the behavior for rounding up values that aren't in increments of 5 (for sites with distance units in miles) or 10 (for sites with distance units in kilometers). The maximum value restriction has been removed from the documentation.

Removed text that indicated the LocalSearchOnly item filter was required to use the MaxDistance filter.

TopRatedSellerOnly Constraints

Removed text that indicated the TopRatedSellerOnly filter could not be used together with either Seller or ExcludeSeller item filters.

ListingType Constraints

AdFormat has been removed from list of valid ListingType filter values. The description for the Classified filter value now says it returns AdFormat listings, too. AdFormat remains as a valid value for listingType field in the search results.

EndTimeFrom Constraints

The description for the EndTimeFrom item filter has been corrected to indicate that the time provided must be in the future.

Back to top

Version 1.4.0

Index of Changed Calls - 1.4.0

Schema Changes - 1.4.0

Announcements - 1.4.0

New Features - 1.4.0

Changed Functionality - 1.4.0

Documentation Changes and Errata - 1.4.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.4.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

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.4.0

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

Announcements - 1.4.0

Change Requests

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

New Features - 1.4.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.4.0.

Added Item Filters

New item filters have been added to provide better refinement of search results:

• BestOfferOnly limits search results to only fixed-price items that have Best Offer enabled.
• ExcludeCategory excludes listings within the specified categories from the search results. Up to 25 categories can be specified.
• ModTimeFrom limits the results to active items whose status has changed since the specified time.

See the ItemFilterType type documentation for more information about the allowed values, usage rules, and dependencies.

Added Results Sorting Options

New enumeration values have been added to SortOrderType to enable sorting by item bid count or item location:

• BidCountFewest and BidCountMost sort items by the number of bids they have received, with either items with the fewest bids first or items with the most bids first.
• CountryAscending and CountryDescending sort items available on the given site by the country in which they are located.

  For CountryAscending, items located in the country most closely associated with the site appear first, followed by items in related countries, and then items from other countries. For CountryDescending, items are sorted in reverse order of CountryAscending.

  Sorting by country applies to the following sites only: Austria (EBAY-AT), Belgium-French (EBAY-FRBE), Belgium-Netherlands (EBAY-NLBE), Germany (EBAY-DE), Ireland (EBAY-IE), Netherlands (EBAY-NL), Poland (EBAY-PL), Spain (EBAY-ES), and Switzerland (EBAY-CH).

See sortOrder for more information.

Schema Changes to Support UPA Constraints

The xs:any wildcard in existing complex types in the WSDL has been replaced by an optional sequence containing a delimiter element and an xs:any wildcard. This makes the schema structure deterministic, in accordance with XML rules and standards, which improves the compatibility of the WSDL with development tools.

The delimiter elements are purely for structural framing within complex types. If you pass the delimiter field in a request, any data it contains will be ignored. If they are returned in a response, they will be empty. This schema change will not affect existing applications. Because the nested sequence is optional, the delimiter fields are optional, as well.

Changed Functionality - 1.4.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.4.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.4.0 and Changed Functionality - 1.4.0.

Getting Started Tutorials Added

Two new Getting Started tutorials have been added for the Finding API. In addition to the existing Getting Started tutorial for PHP, which shows you how to make a REST-style request and parse an XML response, the following tutorials have been added:

• JavaScript (URL/JSON): Getting Started with the Finding API: Finding Items by Keywords

  In this tutorial you use JavaScript to write and submit a REST-style findItemsByKeywords call to search for eBay listings based on a keyword. You specify that the response to your call is in JavaScript Object Notation (JSON) format. This tutorial shows how easy it is to use the Finding API. The tutorial utilizes a single JavaScript function for displaying the results in a browser. The tutorial also shows you how to use item filters in your request.

• PHP (XML/XML): Getting Started with the Finding API: Finding Items by Keywords

  In this tutorial, you use PHP to write and submit a findItemsByKeywords call via HTTP POST to search for eBay listings based on a keyword. You specify that the response to your call is in XML format. This tutorial shows how easy it is to use the Finding API. The tutorial also shows you how to use item filters in your request. This tutorial uses cURL and SimpleXML.

Sandbox Support

When the Finding API was initially released, it was not supported in the Sandbox Environment. Support for the Sandbox Environment has been added subsequently. The documentation has been updated reflect this change. Refer to Making a Call for the correct endpoint for the Sandbox.

Back to top

Version 1.2.0

Index of Changed Calls - 1.2.0

Schema Changes - 1.2.0

Announcements - 1.2.0

New Features - 1.2.0

Changed Functionality - 1.2.0

Documentation Changes and Errata - 1.2.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.2.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

• getVersion

Changed Calls

• findItemsAdvanced
• findItemsByKeywords
• findItemsIneBayStores

Schema Changes - 1.2.0

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

Announcements - 1.2.0

Change Requests

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

New Features - 1.2.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.2.0.

Keyword Search Support for Parts Compatibility

Parts compatibility is an eBay feature that uses structured data to associate assemblies (compatible applications) with parts and accessories listed on eBay. Starting in March 2010, parts compatibility will be supported in limited Parts & Accessories categories for eBay Motors in the Production environment. For these categories, a compatible application will always be a vehicle, which is a specific combination of make, model, and year. Optionally, trim and engine data may also be specified for a compatible application. For example, parts compatibility enables sellers to specify accurately and comprehensively the vehicles on which a side mirror or a rim fit. Parts compatibility improves search relevancy and frees up item titles and descriptions for more useful descriptions of the part.

Parts compatibility can be specified by application or by specification. With parts compatibility by application, the seller specifies the application (e.g., year, make, and model of a specific vehicle) with which the part or accessory is compatible. With parts compatibility by specification, the seller specifies the dimensions and characteristics of the part or accessory (e.g., Section Width, Aspect Ratio, Rim Diameter, Load Index, and Speed Rating values for a tire).

When parts compatibility (sometimes called fitment) data is available for items, keywords queries in the Finding API will search this structured data, in addition to other listing information.

Searching By Application

To search for items listed with compatibility information by application, include vehicle details, such as make and model (e.g., Honda Accord), in the keywords in addition to terms for the part or accessory. When there are matches, and the item was listed with compatibility information by application, the compatibility field in the response returns terms from the query that match values in one of the item's compatible applications (vehicles). If the query matches more than one compatible application for an item, the compatibility field returns "Two or more of your vehicles" to indicate multiple matches.

For example, if the query contains "Honda Accord" and a matching item has a 2007 Honda Accord (any trim or engine) specified as a compatible application, the compatibility field will return the matching terms from the query (i.e., Honda Accord).

Searching By Specification

To search for items listed with compatibility information by specification, include the part specifications, such as a tire's section width and aspect ratio (e.g., 225 45), in the keywords in addition to other terms for the part or accessory. The compatibility field is not returned for items listed with compatibility by specification.

New getVersion Call

The getVersion call was added with this release. This simple call can be used to monitor the service for availability. This call has no input parameters and the response contains only the standard output fields.

Changed Functionality - 1.2.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.

Optional CONTENT-TYPE Header Must Have Correct Value

As of January 15, 2010, eBay evaluates the CONTENT-TYPE header against the request payload format. If the CONTENT-TYPE value is incorrect for the payload, the request will fail. Previously, eBay did not validate the CONTENT-TYPE header in requests.

This HTTP header is optional. If you do not submit the CONTENT-TYPE header with your request, eBay will determine the content type from the payload.

The following table lists the correct CONTENT-TYPE header values for HTTP POST request formats:

See Making a Call for more information about the call format for the Finding API.

Documentation Changes and Errata - 1.2.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.2.0 and Changed Functionality - 1.2.0.

None for this release.

Back to top

Version 1.1.0

Index of Changed Calls - 1.1.0

Schema Changes - 1.1.0

Announcements - 1.1.0

New Features - 1.1.0

Changed Functionality - 1.1.0

Documentation Changes and Errata - 1.1.0

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.1.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

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.1.0

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

Announcements - 1.1.0

Change Requests

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

New Features - 1.1.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.1.0.

Gallery Plus Pictures

The search calls now return galleryPlusPictureURL for matching items that have been upgraded to use the Gallery Plus feature. Gallery Plus images are larger than standard gallery images. In site search results, you can view the Gallery Plus image by hovering over or clicking the Enlarge link or magnifying glass icon.

Changed Functionality - 1.1.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.1.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.1.0 and Changed Functionality - 1.1.0.

Updated Value for SellerBusinessType Item Filter

The documentation for the SellerBusinessType item filter has been updated to list the correct filter value, Business, for sellers registered as a business on eBay.

Added Value for Condition Item Filter

The documentation for the Condition item filter has been updated to include the filter value, Unspecified, for restricting search results to listings for which item condition was not specified.

Back to top

Version 1.0.1

Index of Changed Calls - 1.0.1

Schema Changes - 1.0.1

Announcements - 1.0.1

New Features - 1.0.1

Changed Functionality - 1.0.1

Documentation Changes and Errata - 1.0.1

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.0.1

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

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores

Schema Changes - 1.0.1

Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.

Announcements - 1.0.1

Change Requests

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

New Features - 1.0.1

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.0.1.

eBay Top-rated Seller

With the launch of the Top-rated Sellers program, buyers can find items listed by the highest quality sellers on eBay based on the feedback of other buyers. The sellerInfo node in the search results (searchResult.item.sellerInfo) for the "findItems" calls now includes the topRatedSeller field to indicate (true or false) whether the seller of an item qualifies as an eBay Top-rated Seller. Additionally, a new TopRatedSellerOnly item filter has been added to limit search results to items listed by Top-rated Sellers only.

Note the following site restrictions:

• The searchResult.SellerInfo.topRatedSeller field in the response for the finding calls is supported for the following sites only: US (EBAY-US), Motors (EBAY-MOTOR), DE (EBAY-DE), AT (EBAY-AT), and CH (EBAY-CH).
• The TopRatedSellerOnly item filter is supported for the following sites only: US (EBAY-US), Motors (EBAY-MOTOR), UK (EBAY-GB), IE (EBAY-IE), DE (EBAY-DE), AT (EBAY-AT), and CH (EBAY-CH).

Top-rated sellers consistently receive highest buyers' ratings, ship items quickly, and have earned a track record of excellent service. eBay regularly reviews the performance of these sellers to confirm they continue to meet the program's requirements. See the Top-rated Sellers page on the eBay site for more information.

Changed Functionality - 1.0.1

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.0.1

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

None for this release.

Back to top

Version 1.0.0

This is the first release of the Finding API.

Note: Watch these release notes for changes.

For a current list of known issues, see API Call Limits page and the Knowledge Base.

Index of Changed Calls - 1.0.0

These calls are included in the initial release of the Finding API.

New Calls

• findItemsAdvanced
• findItemsByCategory
• findItemsByKeywords
• findItemsByProduct
• findItemsIneBayStores
• getHistograms
• getSearchKeywordsRecommendation

Schema Changes - 1.0.0

Not applicable for initial release.

Announcements - 1.0.0

WSDL Updates to Resolve .NET Compilation Errors

An "xs:any" element has been added to the DomainFilter type in the Finding Service WSDL. This corrects a problem that caused compilation errors for .NET clients.

Change Requests

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

New Features - 1.0.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.0.0.

None for this release.

Changed Functionality - 1.0.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.0.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.0.0 and Changed Functionality - 1.0.0.

Aspect Histograms

The documentation has been updated to indicate the conditions for which aspect histograms are returned. Aspect histograms are returned only for categories that have been mapped to domains. In most cases, just leaf categories are mapped to domains, but there are exceptions. So, if you provide a parent category as input to getHistograms or you restrict a finding call search to a parent category, you may not get an aspect histogram in the response.

Category Histograms

The documentation has been updated to reflect the following conditions for when category histograms are returned:

• getHistograms does not return a category histogram when a leaf category (i.e., a category with no child categories) is specified in the request
• Finding calls do not return a category histogram when the query is restricted to a single leaf category
• On the eBay Motors site, category histograms may not be available for some parent categories

Product ID Values in Responses

The description for productId in the search results has been updated to correct inaccuracies.

Sample Updates

Several call samples have been updated for accuracy and typographic errors.