eBay Shopping API
|
FindItemsAdvanced enables you to search for items on eBay based on many possible input fields and filters. Detailed information is returned about items.
The response to this call is in the form of an array whose size and contents you specify. You can filter the item listings returned using such criteria as the listing category and listing type.
On input, you specify keywords (including wildcards) or other criteria. Additionally, you can specify values to determine what item data is returned and how items are sorted.
You can choose how many items are returned in the response (for the maximum allowed, see MaxEntries). Based on the values in the TotalPages and TotalItems fields in the first call-response you receive, you can use the MaxEntries and PageNumber input fields to specify the item-sets returned in your second, third, etc. call-responses.
You can include or exclude sellers by specifying SellerID or SellerIDExclude; to use SellerID or SellerIDExclude, see Specifying Arrays in Requests.
For information about specifying the numeric value for the eBay site with the items you want information about, see Standard URL Parameters and HTTP Header Values. For information about specifying affiliate parameters, see Affiliate URL Parameters and HTTP Header Values.
FindItemsAdvanced requires that you specify at least one of the following fields: QueryKeywords, CategoryID, ProductID, or SellerID.
The FindItemsAdvanced response contains a default set of data about items matching your request. If you want more data than the default data, you can use one or more IncludeSelector fields, as follows.
To use multiple IncludeSelector fields in a URL, separate them using a comma, for
example: IncludeSelector=Details, SellerInfo
FindItemsAdvanced enables you to use many criteria for searches, including the following. For more information, see the Input and Output sections below.
Note that if you are not using the BestMatch search option, the API search results may not match the search results returned by the eBay website.
You can use the ProductID input field to search by ISBN, UPC, EAN, or eBay Product Reference ID. For example, to search using an eBay Product Reference ID (obtained with a FindProducts call), specify ProductID.Type=Reference and set ProductID.Value to an eBay Product Reference ID value.
You can use the SearchFlag input field to search for charity listings, items with free shipping, and other features.
Use a ModTimeFrom value to limit the results to active items whose status has changed since the specified time. Specify a time in the past. Time must be in GMT; see ModTimeFrom and click the dateTime link for more information.
Specify CategoryID to restrict your query to a specific category ID. When you include a CategoryID element in your request but you do not include a QueryKeyword value, you change the request mode to 'listing mode'. In listing mode, some elements will be available for you to use in a request that containts a CategoryID without a QueryKeyword, while other elements are not supported. When you make a FindItemsAdvanced call using CategoryID without a QueryKeyword, the other elements that you can use in your call are: ItemType, MaxDistance, PaymentMethod, PostalCode, PreferredLocation, PriceMax, PriceMin, EndTimeFrom,EndTimeTo, CharityID, FeedbackScoreMax, and FeedbackScoreMin. When using CategoryID in your call, you can only use the following sort options (and associated values): ItemSort with BestMatchCategoryGroup, BestMatch, Distance, PricePlusShipping, CurrentBid, BestMatchPlusEndTime, and BestMatchPlusPrice; SearchFlag with FreeShipping, GetItFast, and AutoPay; and Currency.
Using values in the ItemSort and SortOrder input fields, you can specify one of many sort options. These options include BestMatch, BidCount, and others.
To retrieve BestMatch results grouped by category, specify a value of BestMatchCategoryGroup in the ItemSort field. BestMatch results are based on community buying activity and other relevance-based factors. Optionally, specify a value in GroupMaxEntries (maximum number of entries per group) and in GroupsMax (maximum number of groups).
To retrieve the number of items by matching category, specify CategoryHistogram in the IncludeSelector field. If you want to specify a maximum number of matching categories at the highest category level (that is, at the level of Art, etc.), specify a value in the CategoryHistogramMaxParents field. If you want to specify a maximum number of matching categories at the subcategory level (that is, at the level below the level of Art, etc.), specify a value in the CategoryHistogramMaxChildren field.
If you are familiar with the GetSearchResults call in the Trading API, please see the mapping of GetSearchResults to FindItemsAdvanced.
See:
Searching for Items by Using a Query for related information (applies primarily to the eBay Trading API)
Searching for Matching Categories for information about finding listings in categories (applies primarily to the eBay Trading API)
Related calls:
| Output Detail Controls Samples Change History User Notes |
The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).
See also Samples.
See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.
<?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <!-- Standard Input Fields --> <MessageID> string </MessageID> <!-- Call-specific Input Fields --> <BidCountMax> int </BidCountMax> <BidCountMin> int </BidCountMin> <CategoryHistogramMaxChildren> int </CategoryHistogramMaxChildren> <CategoryHistogramMaxParents> int </CategoryHistogramMaxParents> <CategoryID> string </CategoryID> <CategoryIDExclude> string </CategoryIDExclude> <!-- ... more CategoryIDExclude nodes here ... --> <CharityID> int </CharityID> <Condition> ItemConditionCodeType </Condition> <Currency> CurrencyCodeType </Currency> <DescriptionSearch> boolean </DescriptionSearch> <EndTimeFrom> dateTime </EndTimeFrom> <EndTimeTo> dateTime </EndTimeTo> <ExcludeFlag> ExcludeFlagCodeType </ExcludeFlag> <!-- ... more ExcludeFlag nodes here ... --> <FeedbackScoreMax> int </FeedbackScoreMax> <FeedbackScoreMin> int </FeedbackScoreMin> <GroupMaxEntries> int </GroupMaxEntries> <GroupsMax> int </GroupsMax> <HideDuplicateItems> boolean </HideDuplicateItems> <IncludeSelector> string </IncludeSelector> <ItemLocationRegion> ItemLocationRegionCodeType </ItemLocationRegion> <ItemsAvailableTo> CountryCodeType </ItemsAvailableTo> <ItemsLocatedIn> CountryCodeType </ItemsLocatedIn> <ItemSort> SimpleItemSortCodeType </ItemSort> <ItemType> ItemTypeCodeType </ItemType> <MaxDistance> int </MaxDistance> <MaxEntries> int </MaxEntries> <ModTimeFrom> dateTime </ModTimeFrom> <PageNumber> int </PageNumber> <PaymentMethod> PaymentMethodSearchCodeType </PaymentMethod> <PostalCode> string </PostalCode> <PreferredLocation> PreferredLocationCodeType </PreferredLocation> <PriceMax currencyID="CurrencyCodeType"> AmountType (double) </PriceMax> <PriceMin currencyID="CurrencyCodeType"> AmountType (double) </PriceMin> <ProductID type="ProductIDCodeType"> ProductIDType (string) </ProductID> <Quantity> int </Quantity> <QuantityOperator> QuantityOperatorCodeType </QuantityOperator> <QueryKeywords> string </QueryKeywords> <SearchFlag> SearchFlagCodeType </SearchFlag> <!-- ... more SearchFlag nodes here ... --> <SellerBusinessType> SellerBusinessCodeType </SellerBusinessType> <SellerID> string </SellerID> <!-- ... more SellerID nodes here ... --> <SellerIDExclude> string </SellerIDExclude> <!-- ... more SellerIDExclude nodes here ... --> <ShippingLocation> CountryCodeType </ShippingLocation> <ShippingPostalCode> string </ShippingPostalCode> <SortOrder> SortOrderCodeType </SortOrder> <StoreName> string </StoreName> <StoreSearch> StoreSearchCodeType </StoreSearch> </FindItemsAdvancedRequest>
| Argument | Type | Occurrence | Meaning |
|---|---|---|---|
| Standard Input Fields [Jump to call-specific fields] | |||
| MessageID | string | Optional | If you pass a value in MessageID in a request, we'll return the same value in CorrelationID in the response. If you're making a lot of calls, you can use this for tracking that a response is returned for every request and to match particular responses to particular requests. (In this case, specify a different value for each request.) You can specify any value that is useful to you. |
| Call-specific Input Fields | |||
| BidCountMax | int | Optional |
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. |
| BidCountMin | int | Optional |
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. |
| CategoryHistogramMaxChildren | int | Optional |
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. Max: 10. Default: 3. |
| CategoryHistogramMaxParents | int | Optional |
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. Max: 10. Default: 3. |
| CategoryID | string | Conditional |
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. Max length: 10. See Searching by Category ID for related information (applies primarily to the eBay Trading API). |
| CategoryIDExclude | string | Optional,
repeatable: [0..*] |
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. |
| CharityID | int | Optional | Limits results to items that support the specified nonprofit charity organization. |
| Condition | ItemConditionCodeType | Optional |
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). Applicable values: • CustomCode (in) Reserved for internal or future use. • New (in) The seller specified the Item Condition as New, or did not specify a condition. (Excludes items that the seller listed as Used.) • Used (in) The seller specified the Item Condition as Used, or did not specify a condition. (Excludes items that the seller listed as New.) |
| Currency | CurrencyCodeType | Optional |
Limits the result set to just those items with a specified currency.
Applicable values: See Currency. |
| DescriptionSearch | boolean | Optional | 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. |
| EndTimeFrom | dateTime | Conditional | 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. |
| EndTimeTo | dateTime | Conditional | 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. |
| ExcludeFlag | ExcludeFlagCodeType | Optional,
repeatable: [0..*] |
Excludes items with the specified flag from the search.
Applicable values: • AutoPay (in) Exclude AutoPay item listings from the search results. |
| FeedbackScoreMax | int | Optional | Specifies the maximum feedback score of a seller whose items can be included in the response. |
| FeedbackScoreMin | int | Optional | Specifies the mininum feedback score of a seller whose items can be included in the response. |
| GroupMaxEntries | int | Optional | 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. |
| GroupsMax | int | Optional | 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. |
| HideDuplicateItems | boolean | Optional |
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. Default: false. |
| IncludeSelector | string | Optional |
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. |
| ItemLocationRegion | ItemLocationRegionCodeType | Optional |
Allows you to search for items in a specified region.
Applicable values: • Canada (in) Search for items in Canada. You can only specify this search option from the Canada (French) - CAFR (210) site. • CanadaFrench (in) Search for items in French Canada (Quebec). You can only use this option with FindItemsAdvanced.PreferredLocation filter. You can only specify this search option from the Canada (French) - CAFR (210) site. • CustomCode (in) Reserved for internal or future use. • Europe (in) Search for items in Europe. You can only specify this search option from the United Kingdom - UK (3), Austria - AT (16), Belgium (French) - BEFR (23), France - FR (71), Germany - DE (77), Italy - IT (101), Belgium (Dutch) - BENL (123), Netherlands - NL (146), Spain - ES (186), Ireland - IE (205) and Poland - PL (212) sites. • NorthAmerica (in) Search for items in North America. You can only specify this search option from the United States - US (0) and Canada - CA (2) sites. • UKIreland (in) Search for items in UK and Ireland. You can only specify this search option from the Ireland - IE (205) site. • Worldwide (in) Search for items world-wide. You can only specify this search option from the United Status - US (0), Canada - CA (2), United Kingdom - UK (3), Australia - AU (15), Austria - AT (16), Belgium (French) - BEFR (23), France - FR (71), Germany - DE (77), Italy - IT (101), Belgium (Dutch) - BENL (123), Netherlands - NL (146), Spain - ES (186), Ireland - IE (205) and Poland - PL (212) sites. |
| ItemsAvailableTo | CountryCodeType | Optional |
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. Applicable values: See ItemsAvailableTo. |
| ItemsLocatedIn | CountryCodeType | Optional |
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. Applicable values: See ItemsLocatedIn. |
| ItemSort | SimpleItemSortCodeType | Optional |
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.) Default: BestMatch. Applicable values: • BestMatch (in) Sorts items by Best Match, and no sort order applies. If specified, then Best Match sort also applies to CategoryHistogram. • BestMatchCategoryGroup (in) Sort by BestMatchCategoryGroup, so results are grouped by Best Match within a category. If you specify BestMatchCategoryGroup, and you want to specify a value for MaxEntries, the MaxEntries value can be 50 or less. • BestMatchPlusEndTime (in) Support Relevance (BestMatch) Filter as first pass and then sorts the result set by end time in ascending or descending order. • BestMatchPlusPrice (in) Support Relevance (BestMatch) Filter as first pass and then sorts the result set by Price in ascending or descending order. • BidCount (in) Sort by number of bids on the item in ascending or descending order. • Country (in) Sort by country; no sort order can be specified. • CurrentBid (in) Sort by current bid on the item in ascending or descending order. • CustomCode (in) Placeholder value. See token. • Distance (in) Sort by distance, ascending order only. • EndTime (in) Sorts items by end time. If you specify EndTime, then for SortOrder, you must specify a value of Ascending. The following is not functional: specifying a value of EndTime with a SortOrder of Descending. • PricePlusShipping (in) This value is part of the Price Plus Shipping Sort feature, available for the following sites: US (site ID 0), Germany (77), Canada (2), and Australia (15). The Price Plus Shipping Sort feature causes item sorting to consider shipping costs. Specify PricePlusShippingAsc to sort items by lowest cost first, as follows: Lowest-total-cost (for items where shipping was properly specified), then freight-shipping items, then items for which shipping was not specified (sorted by price). • StartDate (in) Sort by start date, recently-listed first. |
| ItemType | ItemTypeCodeType | Optional |
Filters items based on criteria related to the listing type of items.
Applicable values: • AdFormat (in) Restricts listings to return only items that have the Ad Format feature. • AllFixedPriceItemTypes (in) Retrieves fixed-price items. Whether StoresFixedPrice items are retrieved does not depend on the site default. The StoresFixedPrice items are retrieved after the basic fixed price items. Items are retrieved whether or not listing type is set to StoresFixedPrice. Does not retrieve items for which listing type is AdType or Live. Does not retrieve auction items for which BuyItNowEnabled is false. • AllItems (in) Returns all listing types (the default for FindItemsAdvanced). It is recommended that you use AllItemTypes instead of AllItems. Whether StoresFixedPrice items are retrieved depends on the site default. • AllItemTypes (in) Retrieves listings whether or not listing type is set to StoresFixedPrice; include auction items. In searches for items, you must specify the AllItemTypes value if you want Store Inventory format (StoresFixedPrice) items to be returned. • AuctionItemsOnly (in) Only retrieve listings eligible for competitive bidding at auction. That is, only retrieve listings for which ListingType is Chinese (single-item auction), regardless of the BuyItNowEnabled value. Items with any of the following listing types are not retrieved: StoresFixedPrice, FixedPriceItem, and AdType. • ClassifiedItemsOnly (in) Only retrieves Classified Ad format listings. • CustomCode (in) Reserved for internal or future use. • ExcludeStoreInventory (in) Excludes listings that have listing type set to StoresFixedPrice. • FixedPricedItem (in) Only retrieves listings that can be purchased at a fixed price. That is, only retrieves listings for which listing type is StoresFixedPrice or FixedPriceItem. Whether StoresFixedPrice items are retrieved depends on the site default. If StoresFixedPrice items are retrieved, they are returned after the other retrieved items. Also retrieves Chinese (single item) auction listings for which BuyItNowEnabled is true. Does not retrieve listings for which listing type is AdType, and does not retrieve auction listings for which BuyItNowEnabled is false. • FixedPriceExcludeStoreInventory (in) Excludes listings that have listing type set to StoresFixedPrice. Excludes listings that have listing type set to AdType. Excludes auction listings in which BuyItNowEnabled is false. • StoreInventoryOnly (in) Only retrieves listings for which the listing type is StoresFixedPrice. |
| MaxDistance | int | Optional |
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. |
| MaxEntries | int | Optional |
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. Max: 100. Default: 20. |
| ModTimeFrom | dateTime | Optional | 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. |
| PageNumber | int | Optional |
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). Default: 1. |
| PaymentMethod | PaymentMethodSearchCodeType | Optional |
Limits results to items that accept a specific payment method or methods.
Applicable values: • CustomCode (in) Reserved for internal or future use. • PaisaPay (in) PaisaPay payment method. The PaisaPay payment method is only for the India site (site ID 203). • PaisaPayEscrowEMI (in) PaisaPayEscrow EMI (Equal Monthly Installment) payment method. The PaisaPayEscrowEMI payment method is only for the India site (site ID 203). • PayPal (in) PayPal payment method. • PayPalOrPaisaPay (in) Either the PayPal or the PaisaPay payment method. The PaisaPay payment method is only for the India site (site ID 203). |
| PostalCode | string | Optional | 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. |
| PreferredLocation | PreferredLocationCodeType | Optional |
Specifies the criteria for filtering search results by site, where site is determined by the site ID in the request.
Applicable values: • AvailableInCountryImplied (in) Items available to the country implied by the site specified in the request. For the US site, this implies listings from ALL English-language countries that are available to the US. • BelgiumListing (in) Items located in Belgium or listed on one of the two Belgian sites. • CustomCode (in) Reserved for internal or future use. • ListedInCurrencyImplied (in) Items listed in the currency implied by the site specified in the request. • LocatedInCountryImplied (in) Items located in the country implied by the site specified in the request. • SiteImplied (in) Returns only items listed on the site specified in the request, regardless of the listing currency. |
| PriceMax | AmountType (double) | Optional | 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. |
| PriceMax [ attribute currencyID ] |
CurrencyCodeType | Optional |
Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType. |
| PriceMin | AmountType (double) | Optional | 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. |
| PriceMin [ attribute currencyID ] |
CurrencyCodeType | Optional |
Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType. |
| ProductID | ProductIDType (string) | Optional |
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. |
| ProductID [ attribute type ] |
ProductIDCodeType | Conditional |
The nature of identifier being used. For FindHalfProducts, FindProducts, FindItemsAdvanced, and FindReviewsAndGuides, only Reference, ISBN, UPC, and EAN are supported. Required when ProductID is specified. For a list of possible enumeration values, see ProductIDCodeType. |
| Quantity | int | Optional |
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. |
| QuantityOperator | QuantityOperatorCodeType | Optional |
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. Applicable values: • CustomCode (in) Reserved for internal or future use. • Equal (in) Specifies quantities equal to Quantity. • GreaterThan (in) Specifies quantities greater than Quantity. • GreaterThanOrEqual (in) Specifies quantities greater than or equal to Quantity. • LessThan (in) Used by QuantityOperator to specify that you are seeking quantities less than Quantity. • LessThanOrEqual (in) Specifies quantities less than or equal to Quantity. |
| QueryKeywords | string | Conditional |
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. Max length: 350 (characters). See:
|
| SearchFlag | SearchFlagCodeType | Optional,
repeatable: [0..*] |
Search for charity listings, free-shipping listings, and listings with other features.
Applicable values: • AutoPay (in) Return only AutoPay item listings. • BestOffer (in) Search with BestOffer. • Charity (in) Return only charity item listings. • CustomCode (in) Reserved for internal or future use. • Featured (in) Return only featured item listings. • FreeShipping (in) If specified, only items with free shipping for the user's location are returned. The user's location is determined from the site ID specified in the request. If false, no filtering is done via this attribute. A listing is not considered a free shipping listing if it requires insurance or requires pick up or requires a shipping surcharge. • Gallery (in) Return Gallery items only. • GermanMotorsSearchable (in) Limits the results based on each item's eligibility to appear on the mobile.de site. If specified, queries for eligible items only. If not specified, the search results are not affected. Only applicable for items listed on the eBay Germany site (site ID 77) in subcategories of mobile.de search-enabled categories. • GetItFast (in) Limits the results to Get It Fast listings. • Gift (in) Return only gift items. • LocalSearch (in) Performs a search for listings with Local Inventory Listing Options (LILO). • Lot (in) Limits the results to only those listings for which lot size is 2 or greater. • NowAndNew Deprecated as of version 601.
• Picture (in) Picture. • SuperFeatured (in) Return only super-featured item listings. • WorldOfGood (in) Returns items that are also listed on the WorldOfGood.com website. (The Item IDs are the same on both websites.) (Not all values in SearchFlagCodeType apply to this field.) |
| SellerBusinessType | SellerBusinessCodeType | Optional |
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. Applicable values: • Commercial (in/out) Commercial seller account. • CustomCode (in/out) Reserved for internal or future use. • Private (in/out) Private seller account. • Undefined (in/out) Type of seller account not defined. |
| SellerID | string | Optional,
repeatable: [0..*] |
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. |
| SellerIDExclude | string | Optional,
repeatable: [0..*] |
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. |
| ShippingLocation | CountryCodeType | Optional |
ShippingLocation should be used together with PostalCode for shipping cost calculations. The items returned are within the specified postal code.
Applicable values: See ShippingLocation. |
| ShippingPostalCode | string | Optional | This postal code is for international shipping cost calculations. This should be a valid code within the country specified as the ShippingLocation. |
| SortOrder | SortOrderCodeType | Optional |
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. Default: Descending. Applicable values: • Ascending (in) Sorts results in ascending (low to high) order. • CustomCode (in) Placeholder value. See token. • Descending (in) Sorts results in descending (high to low) order. |
| StoreName | string | Optional |
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. |
| StoreSearch | StoreSearchCodeType | Optional |
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. Applicable values: • AllItemsInTheStore (in) Within a single store for all items (specify a store in the appropriate input field). • AuctionItemsInTheStore (in) Within a single store for auction items (specify a store in the appropriate input field). • BuyItNowItemsInAllStores (in) Across all stores for basic fixed price items, Store Inventory format items, and auction items with Buy It Now. • BuyItNowItemsInTheStore (in) Within a single store for basic fixed price items, Store Inventory format items, and auction items with Buy It Now (specify a store in the appropriate input field). • CustomCode (in) Reserved for internal or future use. |
| Input Detail Controls Samples Change History User Notes |
The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).
See also Samples.
See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).
<?xml version="1.0" encoding="utf-8"?>
<FindItemsAdvancedResponse xmlns="urn:ebay:apis:eBLBaseComponents">
<!-- Standard Output Fields -->
<Ack> AckCodeType </Ack>
<Build> string </Build>
<CorrelationID> string </CorrelationID>
<Errors> ErrorType
<ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
<ErrorCode> token </ErrorCode>
<ErrorParameters ParamID="string"> ErrorParameterType
<Value> string </Value>
</ErrorParameters>
<!-- ... more ErrorParameters nodes here ... -->
<LongMessage> string </LongMessage>
<SeverityCode> SeverityCodeType </SeverityCode>
<ShortMessage> string </ShortMessage>
</Errors>
<!-- ... more Errors nodes here ... -->
<Timestamp> dateTime </Timestamp>
<Version> string </Version>
<!-- Call-specific Output Fields -->
<CategoryHistogram> CategoryArrayType
<Category> CategoryType
<CategoryID> string </CategoryID>
<CategoryLevel> int </CategoryLevel>
<CategoryName> string </CategoryName>
<CategoryParentID> string </CategoryParentID>
<CategoryParentName> string </CategoryParentName>
<ItemCount> int </ItemCount>
</Category>
<!-- ... more Category nodes here ... -->
</CategoryHistogram>
<DuplicateItems> boolean </DuplicateItems>
<ItemSearchURL> anyURI </ItemSearchURL>
<PageNumber> int </PageNumber>
<SearchResult> SearchResultType
<CategoryGroupIDPath> string </CategoryGroupIDPath>
<CategoryGroupItemCount> int </CategoryGroupItemCount>
<CategoryGroupNamePath> string </CategoryGroupNamePath>
<ItemArray> SimpleItemArrayType
<Item> SimpleItemType
<AutoPay> boolean </AutoPay>
<BestOfferEnabled> boolean </BestOfferEnabled>
<BidCount> int </BidCount>
<BuyItNowAvailable> boolean </BuyItNowAvailable>
<BuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </BuyItNowPrice>
<Charity> CharityType
<CharityID> string </CharityID>
</Charity>
<ConvertedBuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedBuyItNowPrice>
<ConvertedCurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedCurrentPrice>
<Country> CountryCodeType </Country>
<CurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </CurrentPrice>
<DistanceFromBuyer> DistanceType (double) </DistanceFromBuyer>
<EndTime> dateTime </EndTime>
<GalleryURL> anyURI </GalleryURL>
<GermanMotorsSearchable> boolean </GermanMotorsSearchable>
<GetItFast> boolean </GetItFast>
<Gift> boolean </Gift>
<IntegratedMerchantCreditCardEnabled> boolean </IntegratedMerchantCreditCardEnabled>
<ItemID> string </ItemID>
<ItemSpecifics> NameValueListArrayType
<NameValueList> NameValueListType
<Name> string </Name>
<Value> string </Value>
<!-- ... more Value nodes here ... -->
</NameValueList>
<!-- ... more NameValueList nodes here ... -->
</ItemSpecifics>
<ListingStatus> ListingStatusCodeType </ListingStatus>
<ListingType> ListingTypeCodeType </ListingType>
<Location> string </Location>
<PaymentMethods> BuyerPaymentMethodCodeType </PaymentMethods>
<!-- ... more PaymentMethods nodes here ... -->
<PictureExists> boolean </PictureExists>
<PictureURL> anyURI </PictureURL>
<!-- ... more PictureURL nodes here ... -->
<PostalCode> string </PostalCode>
<PrimaryCategoryID> string </PrimaryCategoryID>
<PrimaryCategoryName> string </PrimaryCategoryName>
<RecentListing> boolean </RecentListing>
<SecondaryCategoryID> string </SecondaryCategoryID>
<SecondaryCategoryName> string </SecondaryCategoryName>
<Seller> SimpleUserType
<FeedbackPrivate> boolean </FeedbackPrivate>
<FeedbackRatingStar> FeedbackRatingStarCodeType </FeedbackRatingStar>
<FeedbackScore> int </FeedbackScore>
<PositiveFeedbackPercent> float </PositiveFeedbackPercent>
<UserID> string </UserID>
</Seller>
<ShippingCostSummary> ShippingCostSummaryType
<ShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceCost>
<ShippingType> ShippingTypeCodeType </ShippingType>
</ShippingCostSummary>
<ShipToLocations> string </ShipToLocations>
<!-- ... more ShipToLocations nodes here ... -->
<Site> SiteCodeType </Site>
<StartTime> dateTime </StartTime>
<Storefront> StorefrontType
<StoreName> string </StoreName>
<StoreURL> anyURI </StoreURL>
</Storefront>
<Subtitle> string </Subtitle>
<TimeLeft> duration </TimeLeft>
<Title> string </Title>
<ViewItemURLForNaturalSearch> anyURI </ViewItemURLForNaturalSearch>
</Item>
<!-- ... more Item nodes here ... -->
</ItemArray>
</SearchResult>
<!-- ... more SearchResult nodes here ... -->
<TotalInternationalExpansionItems> int </TotalInternationalExpansionItems>
<TotalItems> int </TotalItems>
<TotalPages> int </TotalPages>
<TotalStoresExpansionItems> int </TotalStoresExpansionItems>
</FindItemsAdvancedResponse>
| Return Value | Type | Occurrence | Meaning |
|---|---|---|---|
| Standard Output Fields [Jump to call-specific fields] | |||
| Ack | AckCodeType | Always |
Indicates whether the call was successfully processed by eBay.
Applicable values: • CustomCode (out) Reserved for internal or future use. • Failure (out) Request processing failed • Success (out) Request processing succeeded • Warning (out) Request processing completed with warning information being included in the response message (Not all values in AckCodeType apply to this field.) |
| Build | string | Always | This refers to the particular software build that eBay used when processing the request and generating the response. This includes the version number plus additional information. eBay Developer Support may request the build information when helping you resolve technical issues. |
| CorrelationID | string | Conditionally | If you pass a value in MessageID in a request, we will return the same value in CorrelationID in the response. You can use this for tracking that a response is returned for every request and to match particular responses to particular requests. Only returned if MessageID was used. |
| Errors | ErrorType | Conditionally,
repeatable: [0..*] |
A list of application-level errors or warnings (if any) that were raised when eBay processed the request. Application-level errors occur due to problems with business-level data on the client side or on the eBay server side. For example, an error would occur if the request contains an invalid combination of fields, or it is missing a required field, or the value of the field is not recognized. An error could also occur if eBay encountered a problem in our internal business logic while processing the request. Only returned if there were warnings or errors. |
| Errors.ErrorClassification | ErrorClassificationCodeType | Conditionally |
API errors are divided between two classes: system errors and request errors.
Applicable values: • CustomCode (out) Reserved for internal or future use. • RequestError (out) An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data. • SystemError (out) Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. See Errors by Number. |
| Errors.ErrorCode | token | Conditionally |
A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.
See Errors by Number. |
| Errors.ErrorParameters | ErrorParameterType | Conditionally,
repeatable: [0..*] |
Some warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error. You can usually predict where these will occur by looking at the "replaceable_value" indicators in our Errors by Number page.
See Errors by Number. |
| Errors.ErrorParameters [ attribute ParamID ] |
string | Conditionally | The index of the parameter in the error. |
| Errors.ErrorParameters.Value | string | Conditionally | The value of the variable. |
| Errors.LongMessage | string | Conditionally |
A more detailed description of the condition that raised the error.
See Errors by Number. |
| Errors.SeverityCode | SeverityCodeType | Conditionally |
Indicates whether the error caused the request to fail. If the request fails and the source of the problem is within the application (such as a missing required element), please change the application before you retry the request. If the problem is due to end-user input data, please alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, you can attempt to re-send the request to eBay. If the source of the problem is on eBay's side, you can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). However, depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future. Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data. • Warning (out) The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning. See:
|
| Errors.ShortMessage | string | Conditionally |
A brief description of the condition that raised the error.
See Errors by Number. |
| Timestamp | dateTime | Always | This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone. |
| Version | string | Always |
The release version that eBay used to process the request. Note: This is usually the latest release version, as specified in the release notes. (eBay releases the API to international sites about a week after we release it to the US site.) If a field in the response returns the token "CustomCode", it usually means that the field is a code type (a token or enumeration), and that in your request URL (or HTTP header) you specified a version that is older than the version in which the token was added to the call. |
| Call-specific Output Fields | |||
| CategoryHistogram | CategoryArrayType | Always |
Statistical (histogram) information about categories that contain items that match the query, if any. For categories associated with specific items, see items returned in each search result. Shows the distribution of items across each category. Not returned if there is no match.
IncludeSelector: CategoryHistogram. |
| CategoryHistogram.Category | CategoryType | Always,
repeatable: [1..*] |
Contains details about a category.
IncludeSelector: CategoryHistogram. |
|
CategoryHistogram.Category .CategoryID |
string | Always |
The numeric ID of a category on eBay. Use an ID of -1 to retrieve the root category and the top-level (level 1) meta categories. You can determine other CategoryIDs from the response from this call, or from a specific item (retrieved from another call like FindItemsAdvanced or GetSingleItem), or from the eBay website. IncludeSelector: CategoryHistogram. |
|
CategoryHistogram.Category .CategoryLevel |
int | Always |
The level where the category fits in the site's category hierarchy. For example, if this field has a value of 2, then the category is 2 levels below the root category. Note that the value of CategoryLevel will always be 1 level below the level of the requested category. To retrieve a category's children, pass its CategoryID back into the request. In the FindItemsAdvanced response, ItemCount indicates the total quantity of matching items in the category. In the FindItemsAdvanced response, sibling categories (i.e., matching categories at the same level) are sorted by ItemCount, descending order. IncludeSelector: CategoryHistogram. |
|
CategoryHistogram.Category .CategoryName |
string | Always |
Display name of the category as it would appear on the eBay Web site.
IncludeSelector: CategoryHistogram. |
|
CategoryHistogram.Category .CategoryParentID |
string | Always |
Category ID identifying a category that is an ancestor of the category indicated in CategoryID.
IncludeSelector: CategoryHistogram. |
|
CategoryHistogram.Category .CategoryParentName |
string | Always |
Display name of the category indicated in CategoryParentID.
IncludeSelector: CategoryHistogram. |
|
CategoryHistogram.Category .ItemCount |
int | Always |
The total quantity of matching items in the category. In the FindItemsAdvanced response, matching categories at the same level (i.e., sibling categories) are sorted by ItemCount. That is, if the request specifies that fewer categories or subcategories should be returned, the ones with the most matching items are returned first.
IncludeSelector: CategoryHistogram. |
| DuplicateItems | boolean | Conditionally |
Indicates whether there are duplicated items not returned by this response when HideDuplicateItems is true in the request.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
| ItemSearchURL | anyURI | Always |
A URL for search results that corresponds to your search request.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
| PageNumber | int | Always |
Indicates the page of data returned by the current call. For instance, for the first set of items returned, this field has a value of 1.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
| SearchResult | SearchResultType | Always,
repeatable: [1..*] |
Contains the returned item listings, if any. The data for each listing is returned in an Item container.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult .CategoryGroupIDPath |
string | Conditionally |
Category ID breadcrumb. Returned when the request has BestMatchCategoryGroup specified as the ItemSort value. Used in building a category-browsing path, i.e. a path of "breadcrumbs" (e.g., 58058 > 3516 > 3522).
IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult .CategoryGroupItemCount |
int | Conditionally |
Item count of the category. Returned when the request has BestMatchCategoryGroup specified as the ItemSort value.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult .CategoryGroupNamePath |
string | Conditionally |
Category name breadcrumb. Returned when the request has BestMatchCategoryGroup specified as the ItemSort value. Used in building a category-browsing path, i.e. a path of "breadcrumbs" (e.g., Computers & Networking > Technology Books > Certification).
IncludeSelector: Returned if IncludeSelector is not provided on input. |
| SearchResult.ItemArray | SimpleItemArrayType | Always |
Array of simple items.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
| SearchResult.ItemArray.Item | SimpleItemType | Always,
repeatable: [1..*] |
Contains data for an item listing.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .AutoPay |
boolean | Always |
If true, the seller requests immediate payment for the item. If false or not specified, immediate payment is not requested. (In responses, does not indicate whether the item is actually still a candidate for purchase via immediate payment.) Only applicable to items listed on PayPal-enabled sites in categories that support immediate payment (see AutoPayEnabled in GetCategories), when seller has a Premier or Business PayPal account (see PayPalAccountType in Getuser). If true, the seller must also accept PayPal as a payment method for the item (see Item.PaymentMethods). Required for digitally delivered goods (see Item.DigitalDeliveryDetails). Not supported if ThirdPartyCheckout is true. See the eBay Web Services guide section on Immediate Payment for additional requirements and dependencies. Also see the section on working with the eBay Motors site for additional rules. Not applicable to Half.com. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .BestOfferEnabled |
boolean | Always |
Whether the seller will accept a best offer for this item. This feature enables a buyer to make a lower-priced binding offer on a fixed price item. Buyers can't see how many offers have been made (only the seller can see this information). To make a best offer on a listing, use the eBay Web site.
IncludeSelector: Details. See:
|
|
SearchResult.ItemArray.Item .BidCount |
int | Always |
The number of bids that have been placed on the item. On most sites, the Buy It Now Option becomes unavailable once an auction has a valid bid. Note that the bid must be above any reserve price. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .BuyItNowAvailable |
boolean | Conditionally |
Indicates whether the item has an active Buy It Now option. On most sites, the Buy It Now option is disabled once a valid bid for the item has been accepted. To see if the item was listed with a Buy It Now option, see if the response includes Item.BuyItNowPrice. This field is returned only if the value is true. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .BuyItNowPrice |
AmountType (double) | Conditionally |
The Buy It Now price of the item, returned in the currency of the site on which the item was listed. For Chinese auctions (competitive bidding online auctions), Buy It Now lets a user purchase the item at a fixed price and end the auction immediately. On most sites, after a Chinese auction has bids, the listing is no longer eligible for Buy It Now. However, calls like FindItems will return BuyItNowPrice if the seller originally listed the item with a Buy It Now option. Use the Item.BidCount field to determine whether an auction with Buy It Now has bids or not, and use Item.BuyItNowAvailable to see if the Buy It Now option is still available. Price fields are returned as doubles, not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. Some eBay sites also support multi-item Buy It Now items, where you can buy multiple items from the same listing at a fixed price (instead of bidding). Note: As of version 619, Dutch-style (multi-item) competitive-bid auctions are deprecated. eBay throws an error if you submit a Dutch item listing with AddItem or VerifyAddItem. If you use RelistItem to update a Dutch auction listing, eBay generates a warning and resets the Quantity value to 1. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Returned only if an item was listed with a Buy It Now option. IncludeSelector: Details. See:
|
| SearchResult.ItemArray.Item .BuyItNowPrice [ attribute currencyID ] |
CurrencyCodeType | Conditionally |
Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType. |
|
SearchResult.ItemArray.Item .Charity |
CharityType | Conditionally |
Identifier for a Giving Works listing and the benefiting nonprofit charity organization.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .Charity.CharityID |
string | Conditionally |
A unique identification number assigned by eBay to registered nonprofit charity organizations.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .ConvertedBuyItNowPrice |
AmountType (double) | Conditionally |
The listing's Buy It Now Price (if any), converted into the currency of the site to which you sent this request. Price fields are returned as doubles, not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. Some eBay sites also support multi-item Buy It Now auctions, where you can buy multiple items from the same listing at a fixed price. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Returned only if an item was listed with a Buy It Now option. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). IncludeSelector: Returned if IncludeSelector is not provided on input. See:
|
| SearchResult.ItemArray.Item .ConvertedBuyItNowPrice [ attribute currencyID ] |
CurrencyCodeType | Conditionally |
Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType. |
|
SearchResult.ItemArray.Item .ConvertedCurrentPrice |
AmountType (double) | Always |
The listing's Buy It Now Price (if any), converted into the currency of the site to which you sent this request. Price fields are returned as doubles, not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. Some eBay sites also support multi-item Buy It Now auctions, where you can buy multiple items from the same listing at a fixed price. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Returned only if an item was listed with a Buy It Now option. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). IncludeSelector: Returned if IncludeSelector is not provided on input. See:
|
| SearchResult.ItemArray.Item .ConvertedCurrentPrice [ attribute currencyID ] |
CurrencyCodeType | Conditionally |
Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType. |
|
SearchResult.ItemArray.Item .Country |
CountryCodeType | Always |
Two-letter ISO 3166 country code to indicate the country where the item is located.
Applicable values: See Country. IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .CurrentPrice |
AmountType (double) | Always |
The current price of the item in the currency of the site on which the item was listed. That is, CurrentPrice is in the original listing currency. For competitive-bidding auction listings, this is the current minimum bid price (if the listing has no bids) or the current high bid (if the listing has bids). This does not reflect the BuyItNow price. For Basic Fixed-Price (FixedPriceItem), Store Inventory (StoresFixedPrice), and Ad format (AdType) listings, this is the current fixed price. IncludeSelector: Details. |
| SearchResult.ItemArray.Item .CurrentPrice [ attribute currencyID ] |
CurrencyCodeType | Conditionally |
Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType. |
|
SearchResult.ItemArray.Item .DistanceFromBuyer |
DistanceType (double) | Conditionally |
The distance of the item from the buyer. The DistanceFromBuyer unit (miles or kilometers) varies by site. If the country whose site you are searching, e.g. India, uses kilometers, then the DistanceFromBuyer unit is kilometers. Otherwise, e.g. if the country is US or UK, then the DistanceFromBuyer unit is miles. DistanceFromBuyer is returned if a value for PostalCode is supplied in the request.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .EndTime |
dateTime | Always |
Time stamp (in GMT) of when the listing is scheduled to end, or time stamp of the actual end time (if the item ended). In FindItemsAdvanced and FindItems, for StoresFixedPrice items which are "Good Till Canceled," this value is 5 minutes later than the actual end time of the item. The discrepancy is intended to facilitate renewal every 30 days of such items' end times. In search results (like the FindItemsAdvanced response), the same EndTime may be returned for multiple results if the results are variations from the same multi-variation listing. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .GalleryURL |
anyURI | Conditionally |
URL for a picture used as the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .GermanMotorsSearchable |
boolean | Conditionally |
The item is featured in eBay search results on the mobile.de partner site. Applicable to eBay Germany.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .GetItFast |
boolean | Conditionally |
A Get It Fast listing.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .Gift |
boolean | Conditionally |
If true, a generic gift icon displays next the listing's title in search and browse pages.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .IntegratedMerchantCreditCardEnabled |
boolean | Always |
Indicates whether the item can be paid for through a payment gateway account. If IntegratedMerchantCreditCardEnabled is true, then integrated merchant credit card is enabled for credit cards because the seller has a payment gateway account. Therefore, if IntegratedMerchantCreditCardEnabled is true, and AmEx, Discover, or VisaMC is returned for an item, then on checkout, an online credit-card payment is processed through a payment gateway account.
IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .ItemID |
string | Always |
The ID that uniquely identifies the item listing. eBay generates this ID when an item is listed. This ID is unique across all eBay sites. In search results (like the FindItemsAdvanced response), the same ItemID may be returned for multiple results if the results are variations from the same multi-variation listing. Max length: 19 (Note: The eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits). IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .ItemSpecifics |
NameValueListArrayType | Conditionally |
Category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic Name/Value structure. The field names are usually very well known within the category. For example, a book's item specifics might include a field like Publication Year=2007 (where Publication Year is returned in Name, and 2007 is returned in Value), and a field like Format=Hardcover. But a car's item specifics would be different from a book's, with fields like Make= Toyota and Model=Prius. And a ticket's item specifics would be different from those of books and cars, with fields like EventType=Concerts and Venue=The Fillmore. One of the most common uses for item specifics is the item condition. Only returned if the seller included Item Specifics in the listing. IncludeSelector: ItemSpecifics. |
|
SearchResult.ItemArray.Item .ItemSpecifics.NameValueList |
NameValueListType | Conditionally,
repeatable: [0..*] |
This list is an array of Item Specifics, which are category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic name/value structure. For example, Item Specifics for a car might include a field like Make=Toyota (where Make is returned in Name, and Toyota is returned in Value) and Model=Prius (where Model is returned in Name, and Prius is returned in Value). In multi-variation listings, the same name cannot appear in both the VariationSpecifics node and in the ItemSpecifics node. For FindProducts, this can also be an Item Specific that is defined for a product. That is, Item Specifics can be returned both for items and products in FindProducts. IncludeSelector: ItemSpecifics. |
|
SearchResult.ItemArray.Item .ItemSpecifics.NameValueList .Name |
string | Conditionally |
The name of the item specific. This field is returned only in responses if the seller included an item specific Name in the listing. However, if the seller didn't also include a corresponding value for the item specific, it is best to not display the name to name to avoid confusing users. For the item condition, this usually includes the word "Condition" for eBay US, UK, Australia, and India listings; and "Artikelzustand" for eBay Germany, Austria, and Switzerland listings. Note: Ignore item specifics with SIFFTAS in the name. These are for internal use by eBay and aren't meaningful to users. IncludeSelector: ItemSpecifics. |
|
SearchResult.ItemArray.Item .ItemSpecifics.NameValueList .Value |
string | Conditionally,
repeatable: [0..*] |
A value for the item specific. This field is only returned in responses if the seller included a value for an item specific. In the GetSingleItem response, this field is always returned for each item specific that is returned (if any). However, if the seller didn't select a value for the item specific, this field may return empty, or it may return a value like "-", "Not Selected", or "Unspecified" (or the equivalent in the language of the site). For the item condition, this usually includes the word "New" or "Used" for eBay US, UK, Australia, and India listings; and "Neu" or "Gebraucht" for eBay Germany, Austria, and Switzerland listings. IncludeSelector: ItemSpecifics. |
|
SearchResult.ItemArray.Item .ListingStatus |
ListingStatusCodeType | Always |
Specifies a listing's status in eBay's processing workflow. If an item's EndTime is in the past, but no details about the buyer or high bidder are shown (and the user is not anonymous), use this listing status information to determine whether eBay has finished processing the listing.
Applicable values: • Active (out) The listing is still live, or it has recently ended but eBay has not completed processing the listing (e.g., we're still determining the high bidder). A multi-item listing is considered active until all items have winning bids or purchases or the listing's end time has passed. (That is, if the listing has a Quantity of 10, the sale of 1 of those items doesn't end the listing.) If the listing has ended but this Active status is returned, please allow several minutes for eBay to finish processing the listing. • Completed (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder. You can think of Completed and Ended as essentially equivalent. (The difference is only meaningful to the seller of the item, as Completed indicates whether eBay has finished calculating certain selling fees.) • CustomCode (out) Placeholder value. See token. • Ended (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .ListingType |
ListingTypeCodeType | Always |
The format of the listing, such as online auction, fixed price, or advertisement format.
Applicable values: • AdType (out) Advertisement to solicit inquiries on listings such as real estate. Permits no bidding on that item, service, or property. To express interest, a buyer fills out a contact form that eBay forwards to the the seller as a lead. This format does not enable buyers and sellers to transact online through eBay, and eBay Feedback is not available for ad format listings. • Chinese (out) Single-quantity online auction format. A Chinese auction has a Quantity of 1. Buyers engage in competitive bidding, although Buy It Now may be offered as long as no bids have been placed. Online auctions are listed on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • CustomCode (out) Placeholder value. See token. • Dutch Deprecated as of version 611.
• Express Deprecated as of version 561.
• FixedPriceItem (out) A basic fixed-price listing with a Quantity of 1. Allows no auction-style bidding. Also known as Buy It Now Only on some sites, this should not to be confused with the BuyItNow option that is available for competitive-bid auctions. Fixed-price listings appear on eBay.com. They are also listed in a seller's eBay Store if the seller is a Store owner. • LeadGeneration (out) Lead Generation format (advertisement-style listing to solicit inquiries or offers, no bidding or fixed price, listed on eBay). • Live (out) Live auction, on-site auction that can include non-eBay bidders. Live auctions are listed on the eBay Live Auctions site, in live auction categories. They can also appear on eBay if the seller lists the lot in a secondary, eBay category. • PersonalOffer (out) Second chance offer made to a non-winning bidder on an ended listing. A seller can make an offer to a non-winning bidder when either the winning bidder has failed to pay for an item or the seller has a duplicate of the item. Second- chance offer items are on eBay, but they do not appear when browsing or searching listings. You need to already know the item ID in order to retrieve a second-chance offer. • StoresFixedPrice (out) A fixed-price format for eBay Store sellers. Store Inventory listings appear after other listings in regular browse and search item lists on eBay. They have a lower Insertion Fee and longer listing durations. This item type can only be specified by sellers who have an eBay Store. Store Inventory listings are listed on eBay.com as well as in the seller's eBay Store. • Unknown (out) Unknown auction type. (This is not normally used.) (Not all values in ListingTypeCodeType apply to this field.) IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .Location |
string | Always |
Physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.)
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .PaymentMethods |
BuyerPaymentMethodCodeType | Always,
repeatable: [1..*] |
Identifies the payment method (such as PayPal) the seller will accept when the buyer pays for the item. Note: If the seller only accepts PayPal, the buyer can still pay with a credit card. PayPal supports major credit cards. Payment methods are not applicable to eBay Real Estate advertisement listings, or other Classified Ad format listings. Applicable values: See PaymentMethods. IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .PictureExists |
boolean | Conditionally |
Returns true if the item has an associated picture. Not returned if value is false.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .PictureURL |
anyURI | Conditionally,
repeatable: [0..24] |
Contains the URL for an image associated with the item, if any. Returned only if the seller included at least one picture in their listing. Note that this element does not return the URLs of pictures that the seller included in the Description via HTML IMG tags. Items listed the main eBay site can have a maximum of 12 picture URLs hosted by eBay Picture Services, or a maximum of 6 picture URLs hosted by a third party (such as the a photo site). Note that a listing can have up to 24 picture URLs on the US eBay Motors site (for all vehicle listings), and on the eBay Canada Motors site. eBay uses the seller's first picture at the top of the listing's View Item page. Max length: 150. IncludeSelector: IncludePictureURL. |
|
SearchResult.ItemArray.Item .PostalCode |
string | Always |
Postal code indicating the physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.)
IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .PrimaryCategoryID |
string | Always |
Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.)
IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .PrimaryCategoryName |
string | Always |
Display name of the first (or only) category in which the item is listed. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks).
IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .RecentListing |
boolean | Conditionally |
Returns true if the item listing is no more than one day old. Not returned if value is false.
IncludeSelector: SearchDetails. |
|
SearchResult.ItemArray.Item .SecondaryCategoryID |
string | Conditionally |
ID of the second category in which the item is listed. Returned only if the seller listed a second category.
IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .SecondaryCategoryName |
string | Conditionally |
Name of the second category in which the item is listed. Returned only if the seller listed a second category.
IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .Seller |
SimpleUserType | Always |
Container for information about this listing's seller.
IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Seller.FeedbackPrivate |
boolean | Always |
Indicates whether the user has chosen to make their feedback score and feedback details private (hidden from other users). Note that the percentage of positive feedback can still be returned, even if other feedback details are private. If a bidder's user information is made anonymous, the value -99 is returned.
IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Seller.FeedbackRatingStar |
FeedbackRatingStarCodeType | Always |
Visual indicator of user's feedback score.
Applicable values: • Blue (out) Blue Star, feedback score 50-99. • CustomCode (out) Placeholder value. See token. • Green (out) Green Star, feedback score 5,000-9,999. • GreenShooting (out) Green Shooting Star, feedback score 500,000-900,000. • None (out) No graphic displayed, feedback score 0-9. • Purple (out) Purple Star, feedback score 500-999. • PurpleShooting (out) Purple Shooting Star, feedback score 50,000-99,999. • Red (out) Red Star, feedback score 1,000-4,999 • RedShooting (out) Red Shooting Star, feedback score 100,000-499,999. • SilverShooting (out) Silver Shooting Star, feedback score 1,000,000 and above. • Turquoise (out) Turquoise Star, feedback score 100-499. • TurquoiseShooting (out) Turquoise Shooting Star, feedback score 25,000-49,999. • Yellow (out) Yellow Star, feedback score 10-49. • YellowShooting (out) Yellow Shooting Star, feedback score 10,000-24,999. IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Seller.FeedbackScore |
int | Always |
The aggregate feedback score of a user. A user's feedback score is the net positive feedback minus the net negative feedback left for the user. Feedback scores are a quantitative expression of the desirability of dealing with a user as a buyer or a seller in transactions. Each transaction can result in one feedback entry for a given user. (The buyer can leave feedback for the seller, and the seller can leave feedback for the buyer.) That one feedback can be positive, negative, or neutral. The aggregate feedback score of a user represents that user's overall feedback score (referred to as a "feedback rating" on the eBay site). If the user has chosen to make their feedback private, then FeedbackScore is not returned and FeedbackPrivate is returned with a value of true. If a bidder's user information is made anonymous, the value -99 is returned. IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Seller .PositiveFeedbackPercent |
float | Always |
The percentage value of a user's positive feedback.
IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Seller.UserID |
string | Always |
The user's unique eBay user ID. When reporting UserIDs in bidding situations (such was when listing the high bidder in an auction), eBay replaces the UserID value with an anonymous bidder name value, such as "a***o". IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .ShippingCostSummary |
ShippingCostSummaryType | Always |
Contains basic shipping-related costs for the item. If Item.Quantity is greater than 1, this is the shipping cost for one item. If the seller offers a choice of more than one shipping service (such as UPS Ground and USPS Media mail), this is the cost of the "first" shipping option (usually the lowest cost option). If a listing has shipping costs, use GetShippingCosts if you want to get more details about the services and costs that the seller is offering. IncludeSelector: Returned if IncludeSelector is not provided on input. See GetShippingCosts. |
|
SearchResult.ItemArray.Item .ShippingCostSummary .ShippingServiceCost |
AmountType (double) | Always |
The basic shipping cost of the item. If multiple items were purchased, this includes the ShippingServiceAdditionalCost. In GetSingleItem, this is always returned when ShippingCostSummary is returned, except for when the ShippingType is Freight. IncludeSelector: Returned if IncludeSelector is not provided on input. |
| SearchResult.ItemArray.Item .ShippingCostSummary .ShippingServiceCost [ attribute currencyID ] |
CurrencyCodeType | Conditionally |
Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType. |
|
SearchResult.ItemArray.Item .ShippingCostSummary .ShippingType |
ShippingTypeCodeType | Always |
How the seller stated that cost of shipping is to be determined, such as flat rate or calculated.
Applicable values: • Calculated (out) The calculated shipping model: the posted cost of shipping is based on the seller-offered and buyer-selected shipping service, where the shipping costs are calculated by eBay and the shipping carrier based on the buyer's address, and any packaging/handling costs established by the seller are automatically rolled into the total. • CalculatedDomesticFlatInternational (out) The seller specified one or more calculated domestic shipping services and one or more flat international shipping services. • CustomCode (out) Placeholder value. See token. • Flat (out) The flat rate shipping model: the seller establishes the cost of shipping and cost of shipping insurance, regardless of what any buyer-selected shipping service might charge the seller. • FlatDomesticCalculatedInternational (out) The seller specified one or more flat domestic shipping services and one or more calculated international shipping services. • Free (out) Free is used when the seller is declaring that shipping is free for the buyer. Since Free cannot be selected via API, the seller has two options for signifying that shipping is free when listing an item: • Freight (out) The freight shipping model: the cost of shipping is determined by a third party, FreightQuote.com, based on the item location (zip code). Currently, Freight can only be specified on input via eBay Web site, not via API. • NotSpecified (out) The seller did not specify the shipping type. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .ShipToLocations |
string | Always,
repeatable: [1..*] |
An international location or region to which the seller is willing to ship this item. Returned only for items that have ShipToLocations specified. Applicable values: • Americas (North, South, or Latin America) • Asia • Caribbean • Europe • EuropeanUnion • LatinAmerica • MiddleEast • NorthAmerica • Oceania (Pacific region other than Asia) • SouthAmerica • WillNotShip (No shipping, buyer must pick up the item) • Worldwide (Seller will ship worldwide) • 2-letter country identifier (See CountryCodeType for values) IncludeSelector: Details. See CountryCodeType. |
|
SearchResult.ItemArray.Item .Site |
SiteCodeType | Always |
The name of the eBay site on which the item was originally listed. For example, if the item is listed on the eBay US site, the value would be US. If it's listed on the eBay Germany site, the value would be Germany. The listing's original site can affect the values of converted (localized) prices (when your request specifies a site that is different from the listing's site). Applicable values: See Site. IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .StartTime |
dateTime | Always |
Time stamp (in GMT) that eBay recorded as the moment that the listing was made available. The start time returned by a search call may vary from the value returned by GetSingleItem.
IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .Storefront |
StorefrontType | Conditionally |
Returns the seller's store information if the seller has an eBay store. Returns a blank store if the seller does not have an eBay storefront.
IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Storefront.StoreName |
string | Conditionally |
The name of the seller's eBay Store. Not returned if the seller does not have an eBay store. Max length: 200. IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Storefront.StoreURL |
anyURI | Conditionally |
The URL of the seller's eBay Store page. Not returned if the seller does not have an eBay store. IncludeSelector: SellerInfo. |
|
SearchResult.ItemArray.Item .Subtitle |
string | Conditionally |
Subtitle of the item. Only returned if the seller included a subtitle for the listing. For US eBay Motors passenger vehicle, motorcycle, and "other vehicle" categories or listings in CA eBay Motors passenger vehicle and motorcycle categories, the seller's subtitle is only available in the Item.ItemSpecifics node. Call GetSingleItem with IncludeSelector=ItemSpecifics to retrieve a listing's Item Specifics. IncludeSelector: Details. |
|
SearchResult.ItemArray.Item .TimeLeft |
duration | Always |
Time left before the listing ends. The duration is represented in the ISO 8601 duration format (PnYnMnDTnHnMnS). For ended listings, the time left is PT0S (zero seconds). In search results (like the FindItemsAdvanced response), the same TimeLeft may be returned for multiple results if the results are variations from the same multi-variation listing. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .Title |
string | Always |
Name of the item as it appears in the listing or in search and browse results. For US eBay Motors vehicles only: In item-retrieval calls (like GetSingleItem and GetMultipleItems), this value shows the vehicle Make and Model (e.g., "Buick : Skylark"). In finding calls (like FindItemsAdvanced), this value concatenates several Item Specifics: The Make (e.g., "Buick"), Model (e.g., Skylark), Submodel (e.g., Limited), and the seller's customized subtitle (e.g., "Great deal!"). Call GetSingleItem with IncludeSelector=ItemSpecifics to see the individual Item Specifics (in Item.ItemSpecifics). Note: GetSingleItem and FindItemsAdvanced do not return the same Item.Title value for US eBay Motors listings. Here's why: In general, GetSingleItem maps to eBay's View Item page. The eBay Motors Web site's View Item page shows two vehicle titles in the title bar: One title is a label based on the Year, Make, Model, and Submodel (e.g., "1996 Buick Skylark Limited"). The model is included unless it's "Other" or unspecified. The submodel is included if the seller specified a submodel. The other title is a path based on the Make and Model (e.g., "Buick : Skylark"). The Item.Title value in GetSingleItem maps to this path. In general, FindItemsAdvanced maps to eBay's advanced search functionality. The Item.Title value described above for FindItemsAdvanced maps to the item's search result title in the eBay Motors search results page. IncludeSelector: Returned if IncludeSelector is not provided on input. |
|
SearchResult.ItemArray.Item .ViewItemURLForNaturalSearch |
anyURI | Always |
The URL to view this listing on eBay. This URL is optimized to support natural search. That is, this URL is designed to make items on eBay easier to find via popular Internet search engines. For example, this URL specifies the item title, and it is optimized for natural search: "_W0QQ" is like "?" (question mark), "QQ" is like "&" (ampersand), and "Z" is like "=" (equals sign). You shouldn't modify the query syntax in your application. For example, eBay won't recognize the URL if you change QQ to ?. In the Sandbox environment and on the Hong Kong site (site ID 201), the data returned in this field by FindItemsAdvanced is a standard ViewItem URL, rather than the ViewItem URL for natural search that generally is returned in the Production environment. In search results (like the FindItemsAdvanced response),if the result is a variation from a multi-variation listing, this link to the View Item page is configured to select the applicable variation. IncludeSelector: Returned if IncludeSelector is not provided on input. |
| TotalInternationalExpansionItems | int | Conditionally |
Total item count for an international expansion of the search.
IncludeSelector: ExpansionItemCount. |
| TotalItems | int | Always |
Indicates the total number of items that could be returned by repeated requests. Returned with a value of 0 if no items match your search request.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
| TotalPages | int | Always |
Indicates the total number of pages of data that could be returned by repeated requests. Returned with a value of 0 if no pages are available.
IncludeSelector: Returned if IncludeSelector is not provided on input. |
| TotalStoresExpansionItems | int | Conditionally |
Total item count for a store expansion of the search.
IncludeSelector: ExpansionItemCount. |
| Input Output Samples Change History User Notes |
The IncludeSelector input field influences which call-specific fields may be returned. (All standard output fields are returned regardless of IncludeSelector.)
The none column indicates the fields that are returned when you do not specify an IncludeSelector.
| Y | The field is always returned. |
| (Y) | The field is conditionally returned. See the field description for clarification of conditions. |
| - | The field is not returned. |
| Input Output Detail Controls Change History User Notes |
New to making API calls? Please see Making an API Call.
Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.
Available samples:
Retrieves the set of items related to the specified keyword ("harry original"). The default set of item fields is returned with each item.
Input
This example uses a keyword get a set of associated items. The default set of item information is returned for each item in the response.
URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML,
specify a different value for responseencoding. http://open.api.ebay.com/shopping?callname=FindItemsAdvanced
&responseencoding=XML
&appid=YourAppIDHere
&siteid=0
&version=525
&QueryKeywords=harry%20original
&MaxEntries=2
Here is the same input in XML format (HTTP POST). Note that this does not include standard values.
XML format (HTTP POST). Also available are the .txt version of this XML and the SOAP equivalent. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <QueryKeywords>harry original</QueryKeywords> <MaxEntries>2</MaxEntries> </FindItemsAdvancedRequest>
Output
The number of items in the output is limited to two items by the MaxEntries value.
XML format. Also available are the .txt version of this XML and the SOAP equivalent. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2007-07-06T00:51:05.250Z</Timestamp> <Ack>Success</Ack> <Build>e525_core_APILW_4863605_R1</Build> <SearchResult> <ItemArray> <Item> <ItemID>123000268897</ItemID> <EndTime>2009-07-23T09:26:21.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Original-Soundtrack-Harry-Potter-And-The-Philosoph_W0QQitemZ190000268897QQcategoryZ58580QQcmdZViewItem</ViewItemURLForNaturalSearch> <PrimaryCategoryID>58580</PrimaryCategoryID> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">12.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT8H35M16S</TimeLeft> <Title>Original Soundtrack - Harry Potter And The Philosoph...</Title> <ShippingCostSummary> <ShippingServiceCost>0.0</ShippingServiceCost> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>123000268898</ItemID> <EndTime>2009-07-24T09:26:21.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Original-Soundtrack-Harry-Potter-And-The-Philosoph_W0QQitemZ190000268898QQcategoryZ58580QQcmdZViewItem</ViewItemURLForNaturalSearch> <PrimaryCategoryID>58580</PrimaryCategoryID> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">177798.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT8H35M16S</TimeLeft> <Title>Original Soundtrack - Harry Potter And The Philosoph...</Title> <ShippingCostSummary> <ShippingServiceCost>0.0</ShippingServiceCost> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> </Item> </ItemArray> </SearchResult> <PageNumber>1</PageNumber> <TotalPages>5</TotalPages> <TotalItems>10</TotalItems> <ItemSearchURL>http://search.ebay.com/search/search.dll?satitle=harry+original</ItemSearchURL> </FindItemsAdvancedResponse>
Retrieves a set of items based on the specified ProductID.
Input
This example uses a ProductID value to obtain item listings. Use FindProducts to retrieve valid ProductID values.
URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML,
specify a different value for responseencoding. http://open.api.ebay.com/shopping?callname=FindItemsAdvanced
&responseencoding=XML
&appid=YourAppIDHere
&siteid=0
&version=525
&ProductID.type=Reference
&ProductID.Value=59049480
&MaxEntries=2
Here is the same input in XML format (HTTP POST). Note that this does not include standard values.
XML format (HTTP POST). Also available is the .txt version of this XML. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <ProductID type="Reference">59049480</ProductID> <MaxEntries>2</MaxEntries> </FindItemsAdvancedRequest>
Output
The number of items in the output is limited to two items by the MaxEntries value.
XML format. Also available is the .txt version of this XML. <?xml version="1.0" encoding="UTF-8"?> <FindItemsAdvancedResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2007-12-12T21:22:57.005Z</Timestamp> <Ack>Success</Ack> <Build>e539_core_Bundled_5643128_R1</Build> <Version>539</Version> <SearchResult> <ItemArray> <Item> <ItemID>160187916579</ItemID> <EndTime>2007-12-12T21:27:43.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-and-the-Deathly-Hallows-MINT-First-Edition_W0QQitemZ160187916579QQcategoryZ377QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/160187916579.jpg</GalleryURL> <PrimaryCategoryID>377</PrimaryCategoryID> <PrimaryCategoryName>Books:Fiction Books</PrimaryCategoryName> <BidCount>4</BidCount> <ConvertedCurrentPrice currencyID="USD">7.55</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>PT4M46S</TimeLeft> <Title>Harry Potter and the Deathly Hallows MINT First Edition</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">4.95</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>200181487084</ItemID> <EndTime>2007-12-12T22:08:17.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/HARRY-POTTER-AND-THE-DEATHLY-HALLOWS-COVER-FASTSHIPPIN_W0QQitemZ200181487084QQcategoryZ377QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/200181487084.jpg</GalleryURL> <PrimaryCategoryID>377</PrimaryCategoryID> <PrimaryCategoryName>Books:Fiction Books</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">0.99</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>PT45M20S</TimeLeft> <Title>HARRY POTTER AND THE DEATHLY HALLOWS COVER FASTSHIPPIN</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">15.0</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> </Item> </ItemArray> </SearchResult> <PageNumber>1</PageNumber> <TotalPages>86</TotalPages> <TotalItems>171</TotalItems> <ItemSearchURL>http://search.product.ebay.com/_W0QQfsooZ1QQfsopZ1QQfvcsZ2178QQsoprZ59049480</ItemSearchURL> </FindItemsAdvancedResponse>
Retrieves a set of items based on the ProductID value. Only items within the specified price range are returned.
Input
This search illustrates how to specify a price range using PriceMin and PriceMax. Notice that the URL version requires a Value field for PriceMin and PriceMax, wherehas this is not required in the XML version.
URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML,
specify a different value for responseencoding. http://open.api.ebay.com/shopping?callname=FindItemsAdvanced
&responseencoding=XML
&appid=YourAppIDHere
&siteid=0
&version=553
&ProductID.type=Reference
&ProductID.Value=59049480
&PriceMax.Value=200
&PriceMin.Value=1
&MaxEntries=2
Here is the same input in XML format (HTTP POST). Note that this does not include standard values.
XML format (HTTP POST). Also available is the .txt version of this XML. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <ProductID type="Reference">59049480</ProductID> <PriceMax>200</PriceMax> <PriceMin>1</PriceMin> <MaxEntries>2</MaxEntries> </FindItemsAdvancedRequest>
Output
The number of items in the output is limited by MaxEntries. Increase this value to obtian more results, where you can verify that only items within the stated price range are returned.
XML format. Also available is the .txt version of this XML. <?xml version="1.0" encoding="UTF-8" ?> <FindItemsAdvancedResponse> <Timestamp>2008-03-03T19:05:09.865Z</Timestamp> <Ack>Success</Ack> <Build>e553_core_Bundled_6126319_R1</Build> <Version>553</Version> <SearchResult> <ItemArray> <Item> <ItemID>160213036228</ItemID> <EndTime>2008-03-03T19:14:10.000Z</EndTime> <ViewItemURLForNaturalSearch> http://cgi.ebay.com/Harry-Potter-and-the-Deathly-Hallows-by-J-K-Rowlin_W0QQitemZ160213036228QQcategoryZ377QQcmdZViewItem </ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/160213036228.jpg</GalleryURL> <PrimaryCategoryID>377</PrimaryCategoryID> <PrimaryCategoryName>Books:Fiction Books</PrimaryCategoryName> <BidCount>6</BidCount> <ConvertedCurrentPrice currencyID="USD">5.5</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>PT9M1S</TimeLeft> <Title> Harry Potter and the Deathly Hallows by J. K. Rowlin... </Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">4.65</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>250219769233</ItemID> <EndTime>2008-03-03T19:42:15.000Z</EndTime> <ViewItemURLForNaturalSearch> http://cgi.ebay.com/Harry-Potter-and-the-Deathly-Hallows-by-J-K-Rowlin_W0QQitemZ250219769233QQcategoryZ377QQcmdZViewItem </ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/250219769233.jpg</GalleryURL> <PrimaryCategoryID>377</PrimaryCategoryID> <PrimaryCategoryName>Books:Fiction Books</PrimaryCategoryName> <BidCount>5</BidCount> <ConvertedCurrentPrice currencyID="USD">6.5</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>PT37M6S</TimeLeft> <Title> Harry Potter and the Deathly Hallows by J. K. Rowlin... </Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">6.0</ShippingServiceCost> <ShippingType>FlatDomesticCalculatedInternational</ShippingType> </ShippingCostSummary> </Item> </ItemArray> </SearchResult> <PageNumber>1</PageNumber> <TotalPages>34</TotalPages> <TotalItems>68</TotalItems> <ItemSearchURL> http://search.product.ebay.com/_W0QQfsooZ1QQfsopZ1QQfvcsZ2178QQsaprchiZ200Q2e0QQsaprcloZ1Q2e0QQsoprZ59049480 </ItemSearchURL> </FindItemsAdvancedResponse>
Sorts results by BestMatchCategoryGroup.
Input
To retrieve BestMatch results grouped by category, specify a value of BestMatchCategoryGroup in the ItemSort field. BestMatch results are based on community buying activity and other relevance-based factors. This example uses BestMatchCategoryGroup and specifies the maximum number of category groups to be returned (GroupsMax), as well as the maximum number of items to return for each group (GroupMaxEntries).
URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML,
specify a different value for responseencoding. http://open.api.ebay.com/shopping?callname=FindItemsAdvanced
&responseencoding=XML
&appid=YourAppIDHere
&siteid=0
&version=525
&QueryKeywords=harry%20original
&MaxEntries=20
&ItemSort=BestMatchCategoryGroup
&GroupsMax=2
&GroupMaxEntries=2
Here is the same input in XML format (HTTP POST). Note that this does not include standard values.
XML format (HTTP POST). Also available are the .txt version of this XML and the SOAP equivalent. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <QueryKeywords>harry original</QueryKeywords> <MaxEntries>20</MaxEntries> <ItemSort>BestMatchCategoryGroup</ItemSort> <GroupsMax>2</GroupsMax> <GroupMaxEntries>2</GroupMaxEntries> </FindItemsAdvancedRequest>
Output
XML format. Also available are the .txt version of this XML and the SOAP equivalent. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2007-08-11T00:57:36.857Z</Timestamp> <Ack>Success</Ack> <Build>e525_core_Bundled_5113095_R1</Build> <Version>525</Version> <SearchResult> <CategoryGroupNamePath>Collectibles</CategoryGroupNamePath> <CategoryGroupIDPath>1</CategoryGroupIDPath> <CategoryGroupItemCount>2</CategoryGroupItemCount> <ItemArray> <Item> <ItemID>330153133683</ItemID> <EndTime>2007-08-11T03:00:00.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-Gaming-Original-Booster-Box_W0QQitemZ330153133683QQcategoryZ29798QQcmdZViewItem</ViewItemURLForNaturalSearch> <PrimaryCategoryID>29798</PrimaryCategoryID> <PrimaryCategoryName>Collectibles:Fantasy, Mythical & Magic:Harry Potter:Other Items</PrimaryCategoryName> <BidCount>1</BidCount> <ConvertedCurrentPrice currencyID="USD">5.99</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>PT2H2M24S</TimeLeft> <Title>Harry Potter Gaming - Original Booster Box</Title> <ShippingCostSummary> <ShippingType>Calculated</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>250151352705</ItemID> <EndTime>2007-08-11T21:40:02.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-Original-Gaming-Booster-Box_W0QQitemZ250151352705QQcategoryZ73570QQcmdZViewItem</ViewItemURLForNaturalSearch> <PrimaryCategoryID>73570</PrimaryCategoryID> <PrimaryCategoryName>Collectibles:Trading Cards:Sci-Fi, Fantasy:Harry Potter</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">9.99</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>PT20H42M26S</TimeLeft> <Title>*Harry Potter Original Gaming Booster Box</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">10.5</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> </Item> </ItemArray> </SearchResult> <SearchResult> <CategoryGroupNamePath>Entertainment Memorabilia</CategoryGroupNamePath> <CategoryGroupIDPath>45100</CategoryGroupIDPath> <CategoryGroupItemCount>2</CategoryGroupItemCount> <ItemArray> <Item> <ItemID>260145570953</ItemID> <EndTime>2007-08-12T01:59:59.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/HARRY-POTTER-5-ORIGINAL-MOVIE-POSTER-FINAL_W0QQitemZ260145570953QQcategoryZ60334QQcmdZViewItem</ViewItemURLForNaturalSearch> <GalleryURL>http://thumbs.ebaystatic.com/pict/260145570953.jpg</GalleryURL> <PrimaryCategoryID>60334</PrimaryCategoryID> <PrimaryCategoryName>Entertainment Memorabilia:Movie Memorabilia:Posters:Originals-US:2000-Now</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">9.97</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P1DT1H2M23S</TimeLeft> <Title>HARRY POTTER 5 ORIGINAL MOVIE POSTER FINAL</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">7.93</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>280141499454</ItemID> <EndTime>2007-08-13T12:49:15.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/HARRY-POTTER-HAND-SIGNED-8X10-ORIGINAL-FELT-PEN_W0QQitemZ280141499454QQcategoryZ32988QQcmdZViewItem</ViewItemURLForNaturalSearch> <PrimaryCategoryID>32988</PrimaryCategoryID> <PrimaryCategoryName>Entertainment Memorabilia:Autographs-Original:Movies:Photos</PrimaryCategoryName> <BidCount>1</BidCount> <ConvertedCurrentPrice currencyID="USD">19.99</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P2DT11H51M39S</TimeLeft> <Title>HARRY POTTER HAND SIGNED 8X10 ORIGINAL FELT PEN</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">6.5</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> </Item> </ItemArray> </SearchResult> <PageNumber>1</PageNumber> <TotalPages>2</TotalPages> <TotalItems>94</TotalItems> <ItemSearchURL>http://search.ebay.com/search/search.dll?satitle=harry+original</ItemSearchURL> </FindItemsAdvancedResponse>
Retrieves details on items that include free shipping. The result also includes a category histogram (item counts by category).
Input
This example shows how to search for items that offer free shipping. In addition, the example uses two IncludeSelectors to enhance the result set.
To specify free shipping, specify FreeShipping in the SearchFlag field. You can also use IncludeSelectors to return additional fields in the result set. This exampls uses the following IncludeSelectors: Details (which returns an expanded set of item fields, including ListingType and PaymentMethods) and CategoryHistogram (which returns a container with data about the categories that match the search).
URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML,
specify a different value for responseencoding. http://open.api.ebay.com/shopping?callname=FindItemsAdvanced
&responseencoding=XML
&appid=YourAppIDHere
&siteid=0
&version=525
&QueryKeywords=ipod
&MaxEntries=2
&IncludeSelector=Details,CategoryHistogram
&SearchFlag(0)=FreeShipping
Here is the same input in XML format (HTTP POST). Note that this does not include standard values.
XML format (HTTP POST). Also available are the .txt version of this XML and the SOAP equivalent. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <QueryKeywords>ipod</QueryKeywords> <MaxEntries>2</MaxEntries> <IncludeSelector>Details,CategoryHistogram</IncludeSelector> <SearchFlag>FreeShipping</SearchFlag> </FindItemsAdvancedRequest>
Output
XML format. Also available are the .txt version of this XML and the SOAP equivalent. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2007-08-11T02:04:37.455Z</Timestamp> <Ack>Success</Ack> <Build>e525_core_Bundled_5113095_R1</Build> <Version>525</Version> <SearchResult> <ItemArray> <Item> <BestOfferEnabled>false</BestOfferEnabled> <ItemID>200140049136</ItemID> <EndTime>2007-08-11T02:35:00.000Z</EndTime> <StartTime>2007-08-10T02:35:00.000Z</StartTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/2GB-MP3-MP4-FM-Video-E-Book-player-Case-fit-iPod-Nano_W0QQitemZ200140049136QQcategoryZ73839QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <PaymentMethods>PayPal</PaymentMethods> <GalleryURL>http://thumbs.ebaystatic.com/pict/200140049136.jpg</GalleryURL> <PostalCode>M5H3E5</PostalCode> <PrimaryCategoryID>73839</PrimaryCategoryID> <PrimaryCategoryName>Consumer Electronics:Apple iPod, MP3 Players:Other MP3 Players</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">39.99</ConvertedCurrentPrice> <CurrentPrice currencyID="USD">39.99</CurrentPrice> <ListingStatus>Active</ListingStatus> <ShipToLocations>CA</ShipToLocations> <Site>Canada</Site> <TimeLeft>PT30M23S</TimeLeft> <Title>2GB MP3 MP4 FM Video E-Book player +Case fit iPod Nano!</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> <Country>CA</Country> </Item> <Item> <BestOfferEnabled>true</BestOfferEnabled> <ItemID>290147553469</ItemID> <EndTime>2007-08-11T02:45:00.000Z</EndTime> <StartTime>2007-08-08T02:45:00.000Z</StartTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/NEW-CAR-CASSETTE-DECK-ADAPTER-FOR-ALL-IPOD-MP3-CD-ZUNE_W0QQitemZ290147553469QQcategoryZ73835QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <PaymentMethods>PayPal</PaymentMethods> <GalleryURL>http://thumbs.ebaystatic.com/pict/290147553469.jpg</GalleryURL> <PostalCode>55305</PostalCode> <PrimaryCategoryID>73835</PrimaryCategoryID> <PrimaryCategoryName>Consumer Electronics:MP3 Accessories:Cassette Adapters:Apple iPod</PrimaryCategoryName> <ConvertedCurrentPrice currencyID="USD">6.98</ConvertedCurrentPrice> <CurrentPrice currencyID="USD">6.98</CurrentPrice> <ListingStatus>Active</ListingStatus> <ShipToLocations>US</ShipToLocations> <Site>US</Site> <TimeLeft>PT40M23S</TimeLeft> <Title>NEW CAR CASSETTE DECK ADAPTER FOR ALL IPOD MP3 CD ZUNE</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> <Country>US</Country> </Item> </ItemArray> </SearchResult> <PageNumber>1</PageNumber> <TotalPages>738</TotalPages> <TotalItems>1476</TotalItems> <CategoryHistogram> <Category> <CategoryID>293</CategoryID> <CategoryLevel>1</CategoryLevel> <CategoryName>Consumer Electronics</CategoryName> <ItemCount>1084</ItemCount> </Category> <Category> <CategoryID>58058</CategoryID> <CategoryLevel>1</CategoryLevel> <CategoryName>Computers & Networking</CategoryName> <ItemCount>108</ItemCount> </Category> <Category> <CategoryID>99</CategoryID> <CategoryLevel>1</CategoryLevel> <CategoryName>Everything Else</CategoryName> <ItemCount>102</ItemCount> </Category> <Category> <CategoryID>56169</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>MP3 Accessories</CategoryName> <CategoryParentID>293</CategoryParentID> <CategoryParentName>Consumer Electronics</CategoryParentName> <ItemCount>529</ItemCount> </Category> <Category> <CategoryID>15057</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Apple iPod, MP3 Players</CategoryName> <CategoryParentID>293</CategoryParentID> <CategoryParentName>Consumer Electronics</CategoryParentName> <ItemCount>394</ItemCount> </Category> <Category> <CategoryID>3270</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Car Electronics</CategoryName> <CategoryParentID>293</CategoryParentID> <CategoryParentName>Consumer Electronics</CategoryParentName> <ItemCount>61</ItemCount> </Category> <Category> <CategoryID>18793</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Software</CategoryName> <CategoryParentID>58058</CategoryParentID> <CategoryParentName>Computers & Networking</CategoryParentName> <ItemCount>87</ItemCount> </Category> <Category> <CategoryID>31530</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Desktop & Laptop Accessories</CategoryName> <CategoryParentID>58058</CategoryParentID> <CategoryParentName>Computers & Networking</CategoryParentName> <ItemCount>8</ItemCount> </Category> <Category> <CategoryID>4599</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Apple, Macintosh Computers</CategoryName> <CategoryParentID>58058</CategoryParentID> <CategoryParentName>Computers & Networking</CategoryParentName> <ItemCount>5</ItemCount> </Category> <Category> <CategoryID>102480</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Information Products</CategoryName> <CategoryParentID>99</CategoryParentID> <CategoryParentName>Everything Else</CategoryParentName> <ItemCount>58</ItemCount> </Category> <Category> <CategoryID>88433</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Other</CategoryName> <CategoryParentID>99</CategoryParentID> <CategoryParentName>Everything Else</CategoryParentName> <ItemCount>27</ItemCount> </Category> <Category> <CategoryID>102534</CategoryID> <CategoryLevel>2</CategoryLevel> <CategoryName>Mystery Auctions</CategoryName> <CategoryParentID>99</CategoryParentID> <CategoryParentName>Everything Else</CategoryParentName> <ItemCount>13</ItemCount> </Category> </CategoryHistogram> <ItemSearchURL>http://search.ebay.com/search/search.dll?satitle=ipod</ItemSearchURL> </FindItemsAdvancedResponse>
Retrieves multi-variation listings.
Description
The user bountifulbuyer is searching for women's Polo tops. In this sample, she happens to find tops that a seller has organized into a multi-variation listing.
Input
In this sample, bountifulbuyer fills in the keywords for the type of shirt she is looking for. To keep the sample short, the search result is limited to 5 items.
URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML,
specify a different value for responseencoding. http://open.api.ebay.com/shopping?callname=FindItemsAdvanced
&responseencoding=XML
&appid=YourAppIDHere
&siteid=0
&version=515
&QueryKeywords=ralph%20lauren%20polo%20shirt
&MaxEntries=5
Here is the same input in XML format (HTTP POST). Note that this does not include standard values.
XML format (HTTP POST). Also available is the .txt version of this XML. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <QueryKeywords>ralph lauren polo shirt</QueryKeywords> <MaxEntries>5</MaxEntries> </FindItemsAdvancedRequest>
Output
The response format is mostly the same as normal item search results, however, there are some differences in the data returned:
All the matching variations are returned as if they are separate items. In this case, the first 5 results are all from the same listing, so shared values like ItemID, Title, and EndTime are identical across all 5 results.
In each result, each ViewItemURLForNaturalSearch is different (specifically, the "var" parameter varies). If bountifulbuyer follows one of these links, she will be shown eBay's View Item page with the applicable variation selected.
In each result, the ConvertedCurrentPrice shows the price of the applicable variation, just like it would for any search result with no variations. (This is different from Item.ConvertedCurrentPrice in GetSingleItem, which always shows the price of the lowest-price active variation.)
XML format. Also available is the .txt version of this XML. <?xml version="1.0" encoding="utf-8"?> <FindItemsAdvancedResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2009-05-04T02:22:28.742Z</Timestamp> <Ack>Success</Ack> <Build>e615__Bundled_8552129_R1</Build> <Version>615</Version> <SearchResult> <ItemArray> <Item> <ItemID>190001574949</ItemID> <EndTime>2009-05-30T20:49:53.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/New-Ralph-Lauren-Polo-shirt-Pink-Black-Blue-Yellow_W0QQitemZ190001574949QQcategoryZ37565QQvarZ490000019377QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <GalleryURL>http://thumbs2.ebaystatic.com/pict/1900015749498080001_3.jpg</GalleryURL> <PrimaryCategoryID>37565</PrimaryCategoryID> <PrimaryCategoryName>Everything Else:Test Auctions:Attributes:Attributes7</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">17.99</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P26DT18H27M25S</TimeLeft> <Title>New Ralph Lauren Polo shirt Pink Black Blue Yellow</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost> <ShippingType>Calculated</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>190001574949</ItemID> <EndTime>2009-05-30T20:49:53.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/New-Ralph-Lauren-Polo-shirt-Pink-Black-Blue-Yellow_W0QQitemZ190001574949QQcategoryZ37565QQvarZ490000019379QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <GalleryURL>http://thumbs2.ebaystatic.com/pict/1900015749498080001_3.jpg</GalleryURL> <PrimaryCategoryID>37565</PrimaryCategoryID> <PrimaryCategoryName>Everything Else:Test Auctions:Attributes:Attributes7</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">17.99</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P26DT18H27M25S</TimeLeft> <Title>New Ralph Lauren Polo shirt Pink Black Blue Yellow</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost> <ShippingType>Calculated</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>190001574949</ItemID> <EndTime>2009-05-30T20:49:53.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/New-Ralph-Lauren-Polo-shirt-Pink-Black-Blue-Yellow_W0QQitemZ190001574949QQcategoryZ37565QQvarZ490000019383QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <GalleryURL>http://thumbs2.qa.ebaystatic.com/pict/1900015749498080002_3.jpg</GalleryURL> <PrimaryCategoryID>37565</PrimaryCategoryID> <PrimaryCategoryName>Everything Else:Test Auctions:Attributes:Attributes7</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">20.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P26DT18H27M25S</TimeLeft> <Title>New Ralph Lauren Polo shirt Pink Black Blue Yellow</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost> <ShippingType>Calculated</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>190001574949</ItemID> <EndTime>2009-05-30T20:49:53.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/New-Ralph-Lauren-Polo-shirt-Pink-Black-Blue-Yellow_W0QQitemZ190001574949QQcategoryZ37565QQvarZ490000019382QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <PrimaryCategoryID>37565</PrimaryCategoryID> <PrimaryCategoryName>Everything Else:Test Auctions:Attributes:Attributes7</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">20.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P26DT18H27M25S</TimeLeft> <Title>New Ralph Lauren Polo shirt Pink Black Blue Yellow</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost> <ShippingType>Calculated</ShippingType> </ShippingCostSummary> </Item> <Item> <ItemID>190001574949</ItemID> <EndTime>2009-05-30T20:49:53.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/New-Ralph-Lauren-Polo-shirt-Pink-Black-Blue-Yellow_W0QQitemZ190001574949QQcategoryZ37565QQvarZ490000019378QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <GalleryURL>http://thumbs2.ebaystatic.com/pict/1900015749498080001_3.jpg</GalleryURL> <PrimaryCategoryID>37565</PrimaryCategoryID> <PrimaryCategoryName>Everything Else:Test Auctions:Attributes:Attributes7</PrimaryCategoryName> <BidCount>0</BidCount> <ConvertedCurrentPrice currencyID="USD">17.99</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P26DT18H27M25S</TimeLeft> <Title>New Ralph Lauren Polo shirt Pink Black Blue Yellow</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost> <ShippingType>Calculated</ShippingType> </ShippingCostSummary> </Item> </ItemArray> </SearchResult> <PageNumber>1</PageNumber> <TotalPages>101</TotalPages> <TotalItems>502</TotalItems> <ItemSearchURL>http://search.ebay.com/ws/search/SaleSearch?DemandData=1&fsop=32&satitle=ralph+lauren+polo+shirt</ItemSearchURL> </FindItemsAdvancedResponse>
| Input Output Detail Controls Samples User Notes |
| Version | Description |
|---|---|
| 623 2009-06-24 |
|
| 615 2009-04-29 |
|
| 611 2009-04-01 |
|
| 603 2009-02-04 |
|
| 601 2009-01-21 |
|
| 599 2009-01-07 |
|
| 581 2008-09-03 |
|
| 573 2008-07-09 |
|
| 569 2008-06-11 |
|
| 565 2008-05-14 |
|
| 555 2008-03-03 |
|
| 553 2008-02-20 |
|
| 547 2008-1-9 |
|
| 537 2007-12-12 |
|
| 537 2007-10-31 |
|
| 535 2007-10-17 |
|
| 531 2007-09-19 |
|
| 527 2007-08-22 |
|
| 525 2007-08-08 |
|
| Input Output Detail Controls Samples Change History User Notes |
This document was generated with a customized version of the apireferencedocs tool [0.5M zip].
© 2009 eBay, Inc. All rights reserved.