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 an API 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.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 |
Index of Changed Calls - 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.
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.
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 |
See the Finding System Announcements for bug fixes related to this release.
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.
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:
ConditionHistogram in outputSelector, andCondition in itemFilter (i.e., you have not yet narrowed your search based on specific conditions), andThe 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.
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.
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).
Using the outputSelector values PictureURLSuperSize and PictureURLLarge, you can retrieve URLs for pictures that are 800x800 and 400x400 pixels in size, respectively.
Set the geoTargeting element to 1 to specify that you want the affiliate link returned as a roverized geo-targeted affiliate link.
The return element isMultiVariationListing returns True if the item is a multi-variation listing, otherwise it returns False.
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.
This feature will be available mid-Summer, 2011. Sellers should contact their account manager or Customer Service to see if they qualify for the Strike-Through Pricing program.
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.
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.
None for this release.
Index of Changed Calls - 1.9.0
Documentation Changes and Errata - 1.9.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
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.
| Name | Part of Schema | Type of Change |
|---|---|---|
ItemFilterType.ValueBoxInventory |
Enum | New |
See the Finding System Announcements for bug fixes related to this release.
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.
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.
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.
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.
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.
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 availale to the Finding API search calls.
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 searth 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.
Index of Changed Calls - 1.8.0
Documentation Changes and Errata - 1.8.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
| Name | Part of Schema | Type of Change |
|---|---|---|
SearchItem.returnsAccepted |
Element | New |
ShippingInfo.expeditedShipping |
Element | New |
ShippingInfo.handlingTime |
Element | New |
ShippingInfo.oneDayShippingAvailable |
Element | New |
ItemFilterType.ExpeditedShippingType |
Enum | New |
ItemFilterType.ListedIn |
Enum | New |
ItemFilterType.MaxHandlingTime |
Enum | New |
ItemFilterType.ReturnsAcceptedOnly |
Enum | New |
See the Finding System Announcements for bug fixes related to this release.
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.
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>
None for this release.
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.
Index of Changed Calls - 1.7.0
Documentation Changes and Errata - 1.7.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
No changed calls in this release.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
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>
See the Finding System Announcements for bug fixes related to this release.
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.
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.
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.
| Note: The Trading API includes, GetMyeBaySelling or GetSellerList, either of which can also be used to retrieve a seller's listings. These calls may may be better suited for sellers wishing to track and monitor their listings. |
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>
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.
Index of Changed Calls - 1.6.0
Documentation Changes and Errata - 1.6.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
| Name | Part of Schema | Type of Change |
|---|---|---|
ExtensionType |
Complex type | New |
BaseFindingServiceResponse.extension |
Element | New |
BaseFindingServiceResponse.itemSearchURL |
Element | New |
GetHistogramsResponse.extension |
Element | New |
GetSearchKeywordsRecommendationResponse.extension |
Element | New |
ItemFilterType.CharityOnly |
Enum | New |
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.
See the Finding System Announcements for bug fixes related to this release.
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.
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.
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.
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.
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.)
&itemFilter(0).name=Condition&itemFilter(0).value(0)=New&itemFilter(0).value(1)=2000&itemFilter(0).value(2)=2500
<itemFilter>
<name>Condition</name>
<value>New</value>
<value>2000</value>
<value>2500</value>
</itemFilter>
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.
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 eBay Finding API Making an API Call for more information and samples.
Index of Changed Calls - 1.5.0
Documentation Changes and Errata - 1.5.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
None for this release.
No WSDL is provided for this release. The latest supported version of the WSDL is 1.4.0.
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.
To request enhancements to the API or give us feedback, visit the Developer Product Feedback/Wish List forum.
See the Finding System Announcements for bug fixes related to this release.
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.
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 search results now return an item's condition in some cases:
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.
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.
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.
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.
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.
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.
Removed text that indicated the TopRatedSellerOnly filter could not be used together with either Seller or ExcludeSeller item filters.
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.
The description for the EndTimeFrom item filter has been corrected to indicate that the time provided must be in the future.
Index of Changed Calls - 1.4.0
Documentation Changes and Errata - 1.4.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
| Name | Part of Schema | Type of Change |
|---|---|---|
Condition |
Complex type | New. Reserved for future use. |
ConditionHistogram |
Complex type | New. Reserved for future use. |
ConditionHistogramContainer |
Complex type | New. Reserved for future use. |
Affiliate.delimiter |
Element | New |
Aspect.delimiter |
Element | New |
AspectFilter.delimiter |
Element | New |
AspectHistogramContainer.delimiter |
Element | New |
CategoryHistogram.delimiter |
Element | New |
CategoryHistogramContainer.delimiter |
Element | New |
DomainFilter.delimiter |
Element | New |
FindItemsAdvancedResponse.conditionHistogramContainer |
Element | New. Reserved for future use. |
FindItemsByCategoryResponse.conditionHistogramContainer |
Element | New. Reserved for future use. |
FindItemsByKeywordsResponse.conditionHistogramContainer |
Element | New. Reserved for future use. |
FindItemsByProductResponse.conditionHistogramContainer |
Element | New. Reserved for future use. |
FindItemsIneBayStoresResponse.conditionHistogramContainer |
Element | New. Reserved for future use. |
GetHistogramsResponse.conditionHistogramContainer |
Element | New. Reserved for future use. |
ItemFilter.delimiter |
Element | New |
ListingInfo.delimiter |
Element | New |
PaginationInput.delimiter |
Element | New |
PaginationOutput.delimiter |
Element | New |
SearchItem.condition |
Element | New. Reserved for future use. |
SearchItem.delimiter |
Element | New |
SearchResult.delimiter |
Element | New |
SellerInfo.delimiter |
Element | New |
SellingStatus.delimiter |
Element | New |
ShippingInfo.delimiter |
Element | New |
Storefront.delimiter |
Element | New |
ItemFilterType.BestOfferOnly |
Enum | New |
ItemFilterType.ExcludeCategory |
Enum | New |
ItemFilterType.ModTimeFrom |
Enum | New |
OutputSelectorType.ConditionHistogram |
Enum | New. Reserved for future use. |
SortOrderType.BidCountFewest |
Enum | New |
SortOrderType.BidCountMost |
Enum | New |
SortOrderType.CountryAscending |
Enum | New |
SortOrderType.CountryDescending |
Enum | New |
See the Finding System Announcements for bug fixes related to this release.
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.
New item filters have been added to provide better refinement of search results:
See the ItemFilterType type documentation for more information about the allowed values, usage rules, and dependencies.
New enumeration values have been added to SortOrderType to enable sorting by item bid count or item location:
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.
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.
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.
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.
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:
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 eBay 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.
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 eBay Finding API. The tutorial also shows you how to use item filters in your request. This tutorial uses cURL and SimpleXML.
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 an API Call for the correct endpoint for the Sandbox.
Index of Changed Calls - 1.2.0
Documentation Changes and Errata - 1.2.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
| Name | Part of Schema | Type of Change |
|---|---|---|
GetVersionRequest |
Complex type | New |
GetVersionResponse |
Complex type | New |
searchResult.item.compatibility |
Element | New |
See the Finding System Announcements for bug fixes related to this release.
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.
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 specifed 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 Diammeter, 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.
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).
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.
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.
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.
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:
| Request Payload Format | CONTENT-TYPE Value |
|---|---|
| XML | text/xml |
| SOAP11 | text/xml (together with the SOAPAction header, for which the value can be anything) |
| SOAP12 | application/soap+xml |
See Making An API Call for more information about the call format for the Finding API.
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.
Index of Changed Calls - 1.1.0
Documentation Changes and Errata - 1.1.0
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
| Name | Part of Schema | Type of Change |
|---|---|---|
searchResult.item.galleryPlusPictureURL |
Element | New |
See the Finding System Announcements for bug fixes related to this release.
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.
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 magifying glass icon.
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.
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.
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.
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.
Index of Changed Calls - 1.0.1
Documentation Changes and Errata - 1.0.1
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
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.
No new calls in this release.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
| Name | Part of Schema | Type of Change |
|---|---|---|
searchResult.item.sellerInfo.topRatedSeller |
Element | New |
itemFilter.name.TopRatedSellerOnly |
Enum | New |
See the Finding System Announcements for bug fixes related to this release.
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.
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:
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.
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.
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.
This is the first release of the eBay Finding API.
Note: Watch these release notes for changes.
For a current list of known issues, see eBay Shopping, Finding and Merchandising API Production System Announcements and the Knowledge Base.
These calls are included in the initial release of the eBay Finding API.
Not applicable for initial release.
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.
See the Finding System Announcements for bug fixes related to this release.
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.
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.
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.
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.
The documentation has been updated to reflect the following conditions for when category histograms are returned:
The description for productId in the search results has been updated to correct inaccuracies.
Several call samples have been updated for accuracy and typographic errors.
© 2009–2010 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.