Class FindItemsAdvancedRequestType

Extends AbstractRequestType
class FindItemsAdvancedRequestType
Searches for items based on a variety of input fields. Enables you to specify what item data is returned. Returns detailed information about items.

If you are not using the BestMatch search option, the API search results may not match the search results returned by the eBay website. Summary: Searches for items based on many possible input fields. Detailed information is returned about items. RelatedCalls: FindItems, GetSingleItem

Defined in com/ebay/shoppingservice/FindItemsAdvancedRequestType.js

Property Summary
Number bidCountMax
Limits the results to items with a maximum number of bids.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
Number bidCountMin
Limits the results to items with a minimum number of bids.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
Number categoryHistogramMaxChildren
Maximum number of matching subcategories to return at each level of the category hierarchy below the root level.
Number categoryHistogramMaxParents
Maximum number of matching categories to return at the highest level (root level) of the category hierarchy (level 1).
String categoryID
Specify CategoryID to restrict your query to a specific category.
Array categoryIDExclude
Specify a CategoryIDExclude value in your request if you want search results to be filtered so that the items returned do not include items that belong to the specified category.
Number charityID
Limits results to items that support the specified nonprofit charity organization.
ItemConditionCodeType condition
Limits the results to new OR used items (exclusive, not both), plus items that have no condition specified.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
CurrencyCodeType currency
Limits the result set to just those items with a specified currency.
Boolean descriptionSearch
Specifies whether you want to include the item's description in a search.
Date endTimeFrom
Limits the results to items ending within a time range.
Date endTimeTo
Limits the results to items ending within a time range.
Array excludeFlag
Excludes items with the specified flag from the search.
Number feedbackScoreMax
Specifies the maximum feedback score of a seller whose items can be included in the response.
Number feedbackScoreMin
Specifies the mininum feedback score of a seller whose items can be included in the response.
Number groupMaxEntries
GroupMaxEntries is used when you specify that BestMatch search results are grouped by category (by using BestMatchCategoryGroup in the ItemSort field.) In GroupMaxEntries, you specify the maximum number of entries per group that you want in the search results.
Number groupsMax
GroupsMax is used when you specify that BestMatch search results are grouped by category (by using BestMatchCategoryGroup in the ItemSort field.) In GroupsMax, you specify the maximum number of groups that you want in the search results.
Boolean hideDuplicateItems
Specifies whether or not to remove duplicate items from search results.
String includeSelector
Defines standard subsets of fields to return within the response.

If you don't specify this field, a default set of fields is returned.
ItemLocationRegionCodeType itemLocationRegion
Allows you to search for items in a specified region.
SimpleItemSortCodeType itemSort
Sorts search results based on the value you specify.
ItemTypeCodeType itemType
Filters items based on criteria related to the listing type of items.
CountryCodeType itemsAvailableTo
Limits the result set to just those items available to the specified country.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
CountryCodeType itemsLocatedIn
Limits the result set to just those items located in the specified country.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
Number maxDistance
The maximum distance from the postal code specified in the PostalCode field.
Number maxEntries
Specifies the maximum number of entries to be returned in a single call.
Date modTimeFrom
Limits the results to active items whose status has changed since the specified time.
Number pageNumber
Specifies the number of the page of data to return in the current call.
PaymentMethodSearchCodeType paymentMethod
Limits results to items that accept a specific payment method or methods.
String postalCode
The postal code where the buyer is located.
PreferredLocationCodeType preferredLocation
Specifies the criteria for filtering search results by site, where site is determined by the site ID in the request.
AmountType priceMax
Specifies the maximum current price an item can have to be included in the response.
AmountType priceMin
Specifies the minimum current price an item listing can have to be included in the searches result set.
ProductIDType productID
You can use this input field to search by ISBN, UPC, EAN, or eBay Product Reference ID, as in the following examples.
Number quantity
Limits the results to listings that offer a certain number of items matching the query.
QuantityOperatorCodeType quantityOperator
Limits the results to listings with quantities greater than, equal to, or less than the value you specify in Quantity.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
String queryKeywords
A query that specifies a string for searching titles of items on eBay.
Array searchFlag
Search for charity listings, free-shipping listings, and listings with other features.
SellerBusinessCodeType sellerBusinessType
Limits the results to those of a particular seller business type such as commercial or private.
Array sellerID
The ID of a specific seller.
Array sellerIDExclude
Specify this value if you want search results to be filtered so that the items returned do not include items sold by a specific seller or by specific sellers.
CountryCodeType shippingLocation
ShippingLocation should be used together with PostalCode for shipping cost calculations.
String shippingPostalCode
This postal code is for international shipping cost calculations.
SortOrderCodeType sortOrder
Sorts search results in ascending or descending order, in conjunction with the value you specify in ItemSort.
String storeName
The name of the eBay Store in which the item is listed.
StoreSearchCodeType storeSearch
Specifies the type of store search used for filtering results.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

Properties inherited from AbstractRequestType
messageID

Constructor Summary
FindItemsAdvancedRequestType(Object props)

Property Details

property Number bidCountMax

Limits the results to items with a maximum number of bids.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property Number bidCountMin

Limits the results to items with a minimum number of bids.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property Number categoryHistogramMaxChildren

Maximum number of matching subcategories to return at each level of the category hierarchy below the root level. If you specify this field along with a category ID, then the response will contain child categories of the category ID you specify and subcategories for each child category.

property Number categoryHistogramMaxParents

Maximum number of matching categories to return at the highest level (root level) of the category hierarchy (level 1). If you specify this field along with a category ID, then the response will contain child categories of the category ID you specify and subcategories for each child category.

property String categoryID

Specify CategoryID to restrict your query to a specific category.

If the specified category ID doesn't match an existing category for the site, an invalid-category error message is returned. To determine valid categories:
Use the CategoryHistogram value in the IncludeSelector field to retrieve matching categories. Then make another FindItemsAdvanced call with the ID of a matching category.

FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID. CategoryID can be used in combination with QueryKeywords. If you pass CategoryID without QueryKeywords, CategoryID must be a leaf category ID. That is, it cannot be a root-level ID.

property Array categoryIDExclude

Specify a CategoryIDExclude value in your request if you want search results to be filtered so that the items returned do not include items that belong to the specified category.

CategoryIDExclude is an unbounded field. If you are using a URL, you can separate multiple values with a comma. For example, if you want to specify Records and SuperAudio CDs, specify CategoryIDExclude=306,46354.

If you use CategoryIDExclude, it must be used along with either QueryKeywords, CategoryID, ProductID, or SellerID. You do not need to use the CategoryIDExclude input field every time you use the CategoryID input field.

property Number charityID

Limits results to items that support the specified nonprofit charity organization.

property ItemConditionCodeType condition

Limits the results to new OR used items (exclusive, not both), plus items that have no condition specified.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
Matches the new or used condition that the seller specified in the Item Specifics section of the listing. (That is, this won't specifically match on items where the seller only put the word "New" in the listing's title.)

Only applicable to the following sites: United Kingdom (UK, site ID 3), Australia (AU, site ID 15), Germany (DE, site ID 77), and India (IN, site ID 203).

property CurrencyCodeType currency

Limits the result set to just those items with a specified currency.

property Boolean descriptionSearch

Specifies whether you want to include the item's description in a search. Searching the text of the description can take longer than searching without the description. If true, the text of the item's description will be included in the search. If false, the item's description will be excluded from the search.

property Date endTimeFrom

Limits the results to items ending within a time range. EndTimeFrom specifies the beginning of the time range. Specify a time in the future. If you specify a time in the past, the current time is used. If specified, EndTimeTo must also be specified (with a value equal to or later than EndTimeFrom). Specify the time in GMT. Cannot be used with the ModTimeFrom filter.

property Date endTimeTo

Limits the results to items ending within a time range. EndTimeTo specifies the end of the time range. If specified, EndTimeFrom must also be specified (with a value equal to or earlier than EndTimeTo). Specify the time in GMT. Cannot be used with the ModTimeFrom filter.

property Array excludeFlag

Excludes items with the specified flag from the search.

property Number feedbackScoreMax

Specifies the maximum feedback score of a seller whose items can be included in the response.

property Number feedbackScoreMin

Specifies the mininum feedback score of a seller whose items can be included in the response.

property Number groupMaxEntries

GroupMaxEntries is used when you specify that BestMatch search results are grouped by category (by using BestMatchCategoryGroup in the ItemSort field.) In GroupMaxEntries, you specify the maximum number of entries per group that you want in the search results. There is not a direct correlation between the number of items returned in a regular sort (or in a BestMatch sort) and the number of items that are returned when you specify BestMatchCategoryGroup in the ItemSort field. When you specify BestMatchCategoryGroup in the ItemSort field, not more than 2 pages of results are returned. When you specify GroupMaxEntries, specify GroupsMax.

property Number groupsMax

GroupsMax is used when you specify that BestMatch search results are grouped by category (by using BestMatchCategoryGroup in the ItemSort field.) In GroupsMax, you specify the maximum number of groups that you want in the search results. There is not a direct correlation between the number of items returned in a regular sort (or in a BestMatch sort) and the number of items that are returned when you specify BestMatchCategoryGroup in the ItemSort field. When you specify BestMatchCategoryGroup in the ItemSort field, not more than 2 pages of results are returned. When you specify GroupsMax, specify GroupMaxEntries.

property Boolean hideDuplicateItems

Specifies whether or not to remove duplicate items from search results. When set to true, and there are duplicate items for an item in the search results, the subsequent duplicates will not appear in the results. Item listings are considered duplicates in the following conditions:

For Auctions, items must also have the same price and number of bids to be considered duplicates.
Filtering of duplicate item listings is not supported on all sites.

property String includeSelector

Defines standard subsets of fields to return within the response.

If you don't specify this field, a default set of fields is returned. Click "Detail Controls" below and see "none" for the default fields. If you specify this field, then the set of fields returned includes the default fields. If you specify this field, the additional fields returned can affect the call's response time (performance), including in the case of feedback data.

Applicable values:

•   Details

Include most available fields in the response (except fields that significantly affect the call's performance).

•   SearchDetails

Include additional item information in the response. (This can affect the call's performance.)

•   SellerInfo

Include information about the seller in the response.

•   ItemSpecifics

Include ItemSpecifics in the response. This only returns Item Specifics (if any) that are applicable to search results (not all of a listing's Item Specifics).

•   ExpansionItemCount

Include the counts of items that would be returned with expansions.

•   CategoryHistogram

Include a CategoryHistogram container with information about categories that match your search (up to 2 levels).


Use a comma to specify multiple values. (In this case, the results are cumulative.) See "FindItemAdvanced Samples" for an example of how to use this field.

See "Detail Controls" for a complete list of fields that can be returned for each selector. IncludePictureURL, return all picture URLs of the items, 12 at maximum.

property ItemLocationRegionCodeType itemLocationRegion

Allows you to search for items in a specified region.

property SimpleItemSortCodeType itemSort

Sorts search results based on the value you specify. See the SortOrder field for values for specifying that results are returned in ascending or descending order. (By default, results are returned in descending order.)

property ItemTypeCodeType itemType

Filters items based on criteria related to the listing type of items.

property CountryCodeType itemsAvailableTo

Limits the result set to just those items available to the specified country.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property CountryCodeType itemsLocatedIn

Limits the result set to just those items located in the specified country.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property Number maxDistance

The maximum distance from the postal code specified in the PostalCode field. (The PostalCode field contains the postal code of the buyer.) The MaxDistance unit (miles or kilometers) varies by site. If the country whose site you are searching, e.g. India, uses kilometers, then the MaxDistance unit is kilometers. Otherwise, e.g. if the country is US or UK, The search behavior depends on the following combination of MaxDistance and Postal Code values:

If MaxDistance is set to a value other than 0, and a postal code is entered, the search will retrieve items at the specified distance from the postal code entry (this is the default behavior).

If MaxDistance is set to 0, and no postal code is entered, the postal code search location criteria will be ignored.

If MaxDistance is set to 0, and one postal code is entered, only items within the limits of that postal code will be returned.

If MaxDistance is set to 0, and several postal codes are entered, items within any of the postal codes will be returned, but only the first postal code entered will be used to calculate shipping cost and to sort by distance.

property Number maxEntries

Specifies the maximum number of entries to be returned in a single call. If the number of available items is less than the value you specify, the lower number is returned. If you want the response to contain only the total number of items matching the query, specify a MaxEntries value of 0. Note that if a query normally would return more than 10,000 items, only the first 10,000 items are returned. This limit is independent of the value you specify in the MaxEntries field.

property Date modTimeFrom

Limits the results to active items whose status has changed since the specified time. Specify a time in the past. Time must be in GMT. Cannot be used with the EndTime filters.

property Number pageNumber

Specifies the number of the page of data to return in the current call. Specify a positive value equal to or lower than the number of pages available (which you determine by examining the results of your initial request).

property PaymentMethodSearchCodeType paymentMethod

Limits results to items that accept a specific payment method or methods.

property String postalCode

The postal code where the buyer is located. The search behavior depends on the combination of MaxDistance and Postal Code values. See MaxDistance element for details.

property PreferredLocationCodeType preferredLocation

Specifies the criteria for filtering search results by site, where site is determined by the site ID in the request.

property AmountType priceMax

Specifies the maximum current price an item can have to be included in the response. If the request is made using a URL, must include a Value field, as specified in the following URL snippet: PriceMax.Value=500. Optionally, you can also specify a currency ID, e.g., as part of a URL, PriceMax.currencyID=EUR. Use PriceMax to specify a maximum price or use PriceMax with PriceMin to specify a price range.

property AmountType priceMin

Specifies the minimum current price an item listing can have to be included in the searches result set. Use alone to specify a minimum price or with MaxPrice to define a range the items' prices must be. If the request is made using a URL, must include a Value field, as specified in the following URL snippet: PriceMin.Value=400. Optionally, you can also specify a currency ID, e.g., as part of a URL, PriceMin.currencyID=EUR.

property ProductIDType productID

You can use this input field to search by ISBN, UPC, EAN, or eBay Product Reference ID, as in the following examples. To search using an ISBN, specify ProductID.Type=ISBN and set ProductID.Value to an ISBN value. To search using an eBay Product Reference ID, specify ProductID.Type=Reference and set ProductID.Value to an eBay Product Reference ID value. If you do not know the eBay Product Reference ID of a product, use FindProducts to retrieve the desired eBay Product Reference ID. FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID. If you use the ProductID field, do not use QueryKeywords, CategoryID, or SellerID.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property Number quantity

Limits the results to listings that offer a certain number of items matching the query. The Quantity field is used with QuantityOperator to specify that you are seeking listings with quantities greater than, equal to, or less than the value you specify in Quantity.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property QuantityOperatorCodeType quantityOperator

Limits the results to listings with quantities greater than, equal to, or less than the value you specify in Quantity.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property String queryKeywords

A query that specifies a string for searching titles of items on eBay. If you are using a URL, then to search for multiple words, use "%20". For example, use Harry%20Potter to search for items containing those words in any order. You can incorporate wildcards into a multi-word search, as in the following: ap*%20ip*. The words "and" and "or" are treated like any other word. Only use "and", "or", or "the" if you are searching for listings containing these words. FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID.

property Array searchFlag

Search for charity listings, free-shipping listings, and listings with other features.

property SellerBusinessCodeType sellerBusinessType

Limits the results to those of a particular seller business type such as commercial or private. Applies only to the following sites: UK, France, and Germany. Thus, this input filter is only available for sites that have business seller features enabled.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property Array sellerID

The ID of a specific seller. Specify this value if you want search results to be filtered so that the items returned are only items sold by a specific seller or by specific sellers. SellerID is an unbounded field. If you are using a URL, and you want to specify multiple values, use a comma. For example, to specify FavSellerBlue and FavSellerGreen, specify SellerID=FavSellerBlue,FavSellerGreen. FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID. If you want Store Inventory format (StoresFixedPrice) items to be returned, you must also specify the AllItemTypes value in the ItemType field. The value you specify in SellerID is ignored if it is invalid. You can specify a maximum of 100 sellers.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property Array sellerIDExclude

Specify this value if you want search results to be filtered so that the items returned do not include items sold by a specific seller or by specific sellers. The SellerIDExclude input field need not be used if you specified the SellerID input field. SellerIDExclude is an unbounded field. If you are using a URL, and you want to specify multiple values, use a comma. For example, if you want to specify FavSellerBlue and FavSellerGreen, specify SellerIDExclude=FavSellerBlue,FavSellerGreen. You can specify a maximum of 100 sellers.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property CountryCodeType shippingLocation

ShippingLocation should be used together with PostalCode for shipping cost calculations. The items returned are within the specified postal code.

property String shippingPostalCode

This postal code is for international shipping cost calculations. This should be a valid code within the country specified as the ShippingLocation.

property SortOrderCodeType sortOrder

Sorts search results in ascending or descending order, in conjunction with the value you specify in ItemSort. The default is descending order. For example, for the ItemSort value of BestMatch (the default), the most relevant items are returned first, because the default SortOrder value is Descending. Please note that in the case of an ItemSort value of EndTime (to sort items by end time), you must specify a SortOrder value of Ascending. These parameters result in a sort of items by those ending soonest (from the time of the call), before those ending later.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

property String storeName

The name of the eBay Store in which the item is listed.

Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

Note: Store names are case sensitive. Also, if the store name contains an ampersand (&), you must use the character entity reference (&) in its place.

property StoreSearchCodeType storeSearch

Specifies the type of store search used for filtering results.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

Constructor Details

constructor FindItemsAdvancedRequestType

FindItemsAdvancedRequestType(Object props)

Parameters:
props