browse APIv1_beta.16.0

search

GET
/item_summary/search

This method searches for eBay items by various query parameters and retrieves summaries of the items. You can search by keyword, category, eBay product ID (ePID), or GTIN, or a combination of these.

This method also supports the following:

  • Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, see the filter parameter.
  • Retrieving the refinements (metadata) of an item , such as item aspects (color, brand), condition, category, etc. using the fieldgroups parameter.
  • Filtering by item aspects and other refinements using the aspect_filter parameter.
  • Creating aspects histograms, which enables shoppers to drill down in each refinement narrowing the search results.

For details and examples of these capabilities, see Browse API in the Buying Integration Guide.

Pagination and sort controls

There are pagination controls (limit and offset fields) and sort query parameters that control/sort the data that is returned. By default, the results are sorted by "Best Match". For more information about Best Match, see the eBay help page Best Match.

URLs for this method

  • Production URL: https://api.ebay.com/buy/browse/v1/item_summary/
  • Sandbox URL: https://api.sandbox.ebay.com/buy/browse/v1/item_summary/

Request headers

You will want to use the X-EBAY-C-ENDUSERCTX request header with this method. This header enables eBay Network Partners to pass in their identification in order to be paid for selling eBay items and it is strongly recommended you use contextualLocation to improve the estimated delivery window information. For details see, Request headers in the Buying Integration Guide.

Restrictions

This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see API Restrictions.

Input

Resource URI (production)

URI parameters

ParameterTypeDescription
gtinstringThis field lets you search by the Global Trade Item Number of the item as defined by http://www.gtin.info. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.

   /buy/browse/v1/item_summary/search?gtin=099482432621

Maximum: 1
Required: The method must have category_ids, epid, gtin, or q (or any combination of these)

Occurrence: Optional

epidstringThe ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID.

The Marketing API getMerchandisedProducts method and the Browse API getItem, getItemByLegacyId, and getItemsByItemGroup calls return the ePID of the product. You can also use the product_summary/search method in the Catalog API to search for the ePID of the product.

   /buy/browse/v1/item_summary/search?epid=15032

Maximum: 1
Required: The method must have category_ids, epid, gtin, or q (or any combination of these)

Occurrence: Optional

aspect_filterAspectFilterThis field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red.

For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt.

/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}

To get a list of the aspects pairs and the category, which is returned in the dominantCategoryId field, set fieldgroups to ASPECT_REFINEMENTS.
/buy/browse/v1/item_summary/search?q=shirt&fieldgroups=ASPECT_REFINEMENTS

Required: The category ID is required twice; once as a URI parameter and as part of the aspect_filter.

Occurrence: Optional

fieldgroupsarray of stringThis field is a comma separated list of values that lets you control what is returned in the response. The default is MATCHING_ITEMS, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.

Valid Values:
  • ASPECT_REFINEMENTS - This returns the aspectDistributions container, which has the dominantCategoryId, matchCount, and refinementHref for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be Model Year, Exterior Color, Vehicle Mileage, etc.

    Note: ASPECT_REFINEMENTS are category specific.

  • BUYING_OPTION_REFINEMENTS - This returns the buyingOptionDistributions container, which has the matchCount and refinementHref for AUCTION and FIXED_PRICE (Buy It Now) items.

    Note: Classified items are not supported.

  • CATEGORY_REFINEMENTS - This returns the categoryDistributions container, which has the categories that the item is in.
  • CONDITION_REFINEMENTS - This returns the conditionDistributions container, such as NEW, USED, etc. Within these groups are multiple states of the condition. For example, New can be New without tag, New in box, New without box, etc.
  • EXTENDED - Returns the shortDescription field, which provides condition and item aspect information and the itemLocation.city field.
  • MATCHING_ITEMS - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.
  • FULL - This returns all the refinement containers and all the matching items.
Code so that your app gracefully handles any future changes to this list.

Default: MATCHING_ITEMS

Occurrence: Optional

offsetstringSpecifies the number of items to skip in the result set. This is used with the limit field to control the pagination of the output.

If offset is 0 and limit is 10, the method will retrieve items 1-10 from the list of items returned, if offset is 10 and limit is 10, the method will retrieve items 11 thru 20 from the list of items returned.

Valid Values: 0-10,000 (inclusive)
Default: 0
Maximum number of items returned: 10,000

Occurrence: Optional

limitstringThe number of items, from the result set, returned in a single page.

Default: 50
Maximum number of items per page (limit): 200
Maximum number of items in a result set: 10,000

Occurrence: Optional

sortarray of SortFieldSpecifies the order and the field name to use to sort the items. To sort in descending order use - before the field name. Currently, you can only sort by price (in ascending or descending order), or by distance (only applicable if the "pickup" filters are used, and only ascending order is supported).

If no sort parameter is submitted, the result set is sorted by "Best Match".

The following are examples of using the sort query parameter.

SortResult
&sort=price Sorts by price in ascending order (lowest price first)
&sort=-price Sorts by price in descending order (highest price first)
&sort=distance Sorts by distance in ascending order (shortest distance first)

Default: ascending

Occurrence: Optional

filterarray of FilterFieldThis field supports multiple field filters that can be used to limit/customize the result set.

For example:
   /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]

You can also combine filters.
   /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}

The following are the supported filters. For details and examples for all the filters, see Buy API Field Filters.

Occurrence: Optional

category_idsarray of stringThe category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.

For example:
   /buy/browse/v1/item_summary/search?category_ids=29792

Note: Currently, you can pass in only one category ID.

You can also use any combination of the category_Ids, epid, and q fields. This gives you additional control over the result set.

For example, let's say you are looking of a toy phone. If you search for "phone", the result set will be mobile phones because this is the "Best Match" for this search. But if you also include the toy category ID, the results will be what you wanted.

For example:
   /buy/browse/v1/item_summary/search?q=phone&category_ids=220

The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site:
  • Use the Category Changes page.
  • Use the Taxonomy API. For details see Get Categories for Buy APIs.
  • Submit the following method to get the dominantCategoryId for an item.
    /buy/browse/v1/item_summary/search?q=keyword&fieldgroups=ASPECT_REFINEMENTS
Note: If a top-level (L1) category is specified, you must also include the q query parameter.

Required: The method must have category_ids, epid, gtin, or q (or any combination of these)

Occurrence: Optional

qstringA string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:
  • If the keywords are separated by a comma, it is treated as an AND. In the following example, the query returns items that have iphone AND ipad.

    /buy/browse/v1_beta/item_summary/search?q=iphone,ipad
  • If the keywords are separated by a space, it is treated as an OR. In the following examples, the query returns items that have iphone OR ipad.

    /buy/browse/v1_beta/item_summary/search?q=iphone ipad
    /buy/browse/v1_beta/item_summary/search?q=iphone, ipad
Restriction: The * wildcard character is not allowed in this field.
Required: The method must have category_ids, epid, gtin, or q (or any combination of these)

Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the client grant flow, using one scope from the following list:

https://api.ebay.com/oauth/api_scope

See OAuth access tokens for more information.

Output

HTTP response headers

{ /* SearchPagedCollection<ItemSummary> */
"href" : "string",
"itemSummaries" : [
{ /* ItemSummary */
"additionalImages" : [
{ /* Image */ }
],
"categories" : [
{ /* Category */ }
],
"epid" : "string",
"image" :
{ /* Image */ },
"itemId" : "string",
"thumbnailImages" : [
{ /* Image */ }
],
"title" : "string",
}
],
"limit" : "integer",
"next" : "string",
"prev" : "string",
"total" : "integer",
}
Output container/fieldTypeDescription
hrefstringThe URI of the current page of results.

The following example of the search method returns items 1 thru 5 from the list of items found.

https://api.ebay.com/buy/v1/item_summary/search?q=shirt&limit=5&offset=0.

Occurrence: Always

itemSummariesarray of ItemSummaryAn array of items in one result set. The items are sorted according to the sorting method specified in the request.

Occurrence: Always

itemSummaries.additionalImagesarray of ImageAn array of containers with the URLs for the images that are in addition to the primary image. The primary image is returned in the image.imageUrl field.

Occurrence: Conditional

itemSummaries.additionalImages.heightinteger Reserved for future use.

Occurrence: Conditional

itemSummaries.additionalImages.imageUrlstringThe URL of the image.

Occurrence: Conditional

itemSummaries.additionalImages.widthinteger Reserved for future use.

Occurrence: Conditional

itemSummaries.adultOnlybooleanThis indicates if the item is for adults only. For more information about adult-only items on eBay, see Adult items policy for sellers and Adult-Only items on eBay for buyers.

Occurrence: Always

itemSummaries.bidCountintegerThis integer value indicates the total number of bids that have been placed for an auction item. This field is only returned for auction items.

Occurrence: Conditional

itemSummaries.buyingOptionsarray of stringA comma separated list of the purchase options available for the item, such as FIXED_PRICE, AUCTION.
  • FIXED_PRICE - Returned for fixed-price items (non-auction)
  • AUCTION - Returned for auction items without Buy It Now feature
  • FIXED_PRICE and AUCTION - Returned for auction items enabled with the Buy It Now feature
Code so that your app gracefully handles any future changes to this list.

Occurrence: Always

itemSummaries.categoriesarray of CategoryThis container returns the primary category ID of the item (as well as the secondary category if the item was listed in two categories).

Occurrence: Always

itemSummaries.categories.categoryIdstringThe unique identifier of the primary item category of the item, as well as the secondary item category if item was listed in two categories.

Occurrence: Always

itemSummaries.conditionstringThe text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.conditionIdstringThe identifier of the condition of the item. For example, 1000 is the identifier for NEW. For a list of condition names and IDs, see Item Condition IDs and Names.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Always

itemSummaries.currentBidPriceConvertedAmountThis container returns the current highest bid for an auction item. The value field shows the dollar value of the current highest bid, and the currency field (3-digit ISO code) denotes the currency associated with that bid value. This field is only returned for auction items.

Occurrence: Conditional

itemSummaries.currentBidPrice.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

itemSummaries.currentBidPrice.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

itemSummaries.currentBidPrice.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Always

itemSummaries.currentBidPrice.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Always

itemSummaries.distanceFromPickupLocationTargetLocationThis container returns the distance away that the item is from the pickupPostalCode value that was supplied in the method request. This container is only returned if the 'local pickup' filter fields are used in the request.

Occurrence: Conditional

itemSummaries.distanceFromPickupLocation.unitOfMeasurestringThis value shows the unit of measurement used to measure the distance between the location of the item and the buyer's location. This value is typically mi or km.

Occurrence: Conditional

itemSummaries.distanceFromPickupLocation.valuestringThis value indicates the distance (measured in the measurement unit in the unitOfMeasure field) between the item location and the buyer's location.

Occurrence: Conditional

itemSummaries.energyEfficiencyClassstringThis indicates the energy efficiency rating of the item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only.

Currently, this field is only applicable for the Germany site, and is only returned if the seller specified the energy efficiency rating through item specifics at listing time. Rating values include A+++, A++, A+, A, B, C, D, E, F, and G.

Occurrence: Conditional

itemSummaries.epidstringAn ePID is the eBay product identifier of a product from the eBay product catalog. This indicates the product in which the item belongs.

Occurrence: Conditional

itemSummaries.imageImageThe URL to the primary image of the item.

Occurrence: Always

itemSummaries.image.heightinteger Reserved for future use.

Occurrence: Conditional

itemSummaries.image.imageUrlstringThe URL of the image.

Occurrence: Conditional

itemSummaries.image.widthinteger Reserved for future use.

Occurrence: Conditional

itemSummaries.itemAffiliateWebUrlstringThe URL to the View Item page of the item, which includes the affiliate tracking ID. This field is only returned if the seller enables affiliate tracking for the item by including the X-EBAY-C-ENDUSERCTX request header in the method.

Occurrence: Conditional

itemSummaries.itemGroupHrefstringThe HATEOAS reference of the parent page of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Note: This field is returned only for item groups.

Occurrence: Conditional

itemSummaries.itemGroupTypestringThe indicates the item group type. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Currently only SELLER_DEFINED_VARIATIONS is supported and indicates this is an item group created by the seller.

Note: This field is returned only for item groups.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.itemHrefstringThe URI for the Browse API getItem method, which can be used to retrieve more details about items in the search results.

Occurrence: Always

itemSummaries.itemIdstringThe unique RESTful identifier of the item.

Occurrence: Always

itemSummaries.itemLocationItemLocationImplThis container returns the location of the item. This container consists of fields you typically see for an address, including postal code, county, state/province, street address, city, and country (2-digit ISO code).

Occurrence: Always

itemSummaries.itemLocation.addressLine1stringThe first line of the street address.

Occurrence: Conditional

itemSummaries.itemLocation.addressLine2stringThe second line of the street address. This field may contain such values as an apartment or suite number.

Occurrence: Conditional

itemSummaries.itemLocation.citystringThe city in which the item is located.

Restriction: This field is populated in the search method response only when fieldgroups = EXTENDED.

Occurrence: Conditional

itemSummaries.itemLocation.countryCountryCodeEnumThe two-letter ISO 3166 standard code that indicates the country in which the item is located.

Occurrence: Always

itemSummaries.itemLocation.countystringThe county in which the item is located.

Occurrence: Conditional

itemSummaries.itemLocation.postalCodestringThe postal code (or zip code in US) where the item is located.

Occurrence: Always

itemSummaries.itemLocation.stateOrProvincestringThe state or province in which the item is located.

Occurrence: Always

itemSummaries.itemWebUrlstringThe URL to the View Item page of the item. This enables you to include a "Report Item on eBay" hyperlink that takes the buyer to the View Item page on eBay. From there they can report any issues regarding this item to eBay.

Occurrence: Always

itemSummaries.marketingPriceMarketingPriceThis container is returned if the item is eligible for a seller discount and contains the item's original price, and the seller discount amount and percentage.

Occurrence: Conditional

itemSummaries.marketingPrice.discountAmountConvertedAmountThis container returns the monetary amount of the seller discount.

Occurrence: Conditional

itemSummaries.marketingPrice.discountAmount.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

itemSummaries.marketingPrice.discountAmount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

itemSummaries.marketingPrice.discountAmount.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Always

itemSummaries.marketingPrice.discountAmount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Always

itemSummaries.marketingPrice.discountPercentagestringThis field expresses the percentage of the seller discount based on the value in the originalPrice container.

Occurrence: Conditional

itemSummaries.marketingPrice.originalPriceConvertedAmountThis container returns the monetary amount of the item without the discount.

Occurrence: Conditional

itemSummaries.marketingPrice.originalPrice.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

itemSummaries.marketingPrice.originalPrice.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

itemSummaries.marketingPrice.originalPrice.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Always

itemSummaries.marketingPrice.originalPrice.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Always

itemSummaries.pickupOptionsarray of PickupOptionSummaryThis container returns the local pickup options available to the buyer. This container is only returned if the user is searching for local pickup items and set the local pickup filters in the method request.

Occurrence: Conditional

itemSummaries.pickupOptions.pickupLocationTypestringThis container returns the local pickup options available to the buyer. Possible values are ARRANGED_LOCATION and STORE.

Occurrence: Conditional

itemSummaries.priceConvertedAmountThe price of the item after it has been converted into another currency.

Occurrence: Always

itemSummaries.price.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

itemSummaries.price.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

itemSummaries.price.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Always

itemSummaries.price.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Always

itemSummaries.sellerSellerThis container returns basic information about the seller of the item, such as name, feedback score, etc.

Occurrence: Always

itemSummaries.seller.feedbackPercentagestringThe percentage of the total positive feedback.

Occurrence: Always

itemSummaries.seller.feedbackScoreintegerThe feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller.

Occurrence: Always

itemSummaries.seller.sellerAccountTypestringIndicates if the seller is a business or an individual. This is determined when the seller registers with eBay. If they register for a business account, this value will be BUSINESS. If they register for a private account, this value will be INDIVIDUAL. This designation is required by the tax laws in some countries.

This field is returned only on the following sites.

EBAY_AT   EBAY_BE   EBAY_CH   EBAY_DE   EBAY_ES   EBAY_FR   EBAY_GB   EBAY_IE   EBAY_IT   EBAY_PL

Valid values:
  • BUSINESS
  • INDIVIDUAL
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.seller.usernamestringThe user name created by the seller for use on eBay.

Occurrence: Always

itemSummaries.shippingOptionsarray of ShippingOptionSummaryThis container returns the shipping options available to ship the item.

Occurrence: Conditional

itemSummaries.shippingOptions.maxEstimatedDeliveryDatestringThe end date of the delivery window (latest projected delivery date). This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer.

Note: For the best accuracy, always include the contextualLocation values in the X-EBAY-C-ENDUSERCTX request header.

Occurrence: Conditional

itemSummaries.shippingOptions.minEstimatedDeliveryDatestringThe start date of the delivery window (earliest projected delivery date). This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer.

Note: For the best accuracy, always include the contextualLocation values in the X-EBAY-C-ENDUSERCTX request header.

Occurrence: Conditional

itemSummaries.shippingOptions.shippingCostConvertedAmountThis is the estimated price to ship the item.

Occurrence: Conditional

itemSummaries.shippingOptions.shippingCost.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

itemSummaries.shippingOptions.shippingCost.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

itemSummaries.shippingOptions.shippingCost.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Always

itemSummaries.shippingOptions.shippingCost.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Always

itemSummaries.shippingOptions.shippingCostTypestringThis field indicates the type of shipping used to ship the item. Possible values are FIXED (flat-rate shipping) and CALCULATED (shipping cost calculated based on item and buyer location).

Occurrence: Conditional

itemSummaries.shortDescriptionstringThis text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.). Sometimes the title doesn't give enough information but the description is too big. Surfacing the shortDescription can often provide buyers with the additional information that could help them make a buying decision.

For example:

"title": "Petrel U42W FPV Drone RC Quadcopter w/HD Camera Live Video One Key Off / Landing",
"shortDescription": "1 U42W Quadcopter. Syma X5SW-V3 Wifi FPV RC Drone Quadcopter 2.4Ghz 6-Axis Gyro with Headless Mode. Syma X20 Pocket Drone 2.4Ghz Mini RC Quadcopter Headless Mode Altitude Hold. One Key Take Off / Landing function: allow beginner to easy to fly the drone without any skill.",


Restriction: This field is returned by the search method only when fieldgroups = EXTENDED.

Occurrence: Conditional

itemSummaries.thumbnailImagesarray of ImageAn array of thumbnail images for the item.

Occurrence: Conditional

itemSummaries.thumbnailImages.heightinteger Reserved for future use.

Occurrence: Conditional

itemSummaries.thumbnailImages.imageUrlstringThe URL of the image.

Occurrence: Conditional

itemSummaries.thumbnailImages.widthinteger Reserved for future use.

Occurrence: Conditional

itemSummaries.titlestringThe seller-created title of the item.

Maximum Length: 80 characters

Occurrence: Always

itemSummaries.unitPriceConvertedAmountThis is the price per unit for the item. Some European countries require listings for certain types of products to include the price per unit so buyers can accurately compare prices.

For example:

"unitPricingMeasure": "100g",
"unitPrice": {
  "value": "7.99",
  "currency": "GBP"

Occurrence: Conditional

itemSummaries.unitPrice.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

itemSummaries.unitPrice.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

itemSummaries.unitPrice.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Always

itemSummaries.unitPrice.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Always

itemSummaries.unitPricingMeasurestringThe designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item. This helps buyers compare prices.

For example, the following tells the buyer that the item is 7.99 per 100 grams.

"unitPricingMeasure": "100g",
"unitPrice": {
  "value": "7.99",
  "currency": "GBP"

Occurrence: Conditional

limitintegerThe value of the limit parameter submitted in the request, which is the maximum number of items to return on a page, from the result set. A result set is the complete set of items returned by the method.

Occurrence: Always

nextstringThe URI for the next page of results. This value is returned if there is an additional page of results to return from the result set.

The following example of the search method returns items 5 thru 10 from the list of items found.

https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=10

Occurrence: Conditional

offsetintegerThis value indicates the offset used for current page of items being returned. Assume the initial request used an offset of 0 and a limit of 3. Then in the first page of results, this value would be 0, and items 1-3 are returned. For the second page, this value is 3 and so on.

Occurrence: Always

prevstringThe URI for the previous page of results. This is returned if there is a previous page of results from the result set.

The following example of the search method returns items 1 thru 5 from the list of items found, which would be the first set of items returned.

https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=0

Occurrence: Conditional

refinementRefinementThe container for all the search refinements.

Occurrence: Conditional

refinement.aspectDistributionsarray of AspectDistributionA array of containers for the all the aspect refinements.

Occurrence: Conditional

refinement.aspectDistributions.aspectValueDistributionsarray of AspectValueDistributionAn array of containers for the various values of the aspect and the match count and a HATEOAS reference ( refinementHref) for this aspect.

Occurrence: Conditional

refinement.aspectDistributions.aspectValueDistributions.localizedAspectValuestringThe value of an aspect. For example, Red is a value for the aspect Color.

Occurrence: Always

refinement.aspectDistributions.aspectValueDistributions.matchCountintegerThe number of items with this aspect.

Occurrence: Always

refinement.aspectDistributions.aspectValueDistributions.refinementHrefstringA HATEOAS reference for this aspect.

Occurrence: Always

refinement.aspectDistributions.localizedAspectNamestringName of an aspect, such as Brand, Color, etc.

Occurrence: Conditional

refinement.buyingOptionDistributionsarray of BuyingOptionDistributionA array of containers for the all the buying option refinements.

Occurrence: Conditional

refinement.buyingOptionDistributions.buyingOptionstringBuying option type. This will be AUCTION or FIXED_PRICE or both.

Occurrence: Always

refinement.buyingOptionDistributions.matchCountintegerThe number of items having this buying option.

Occurrence: Always

refinement.buyingOptionDistributions.refinementHrefstringThe HATEOAS reference for this buying option.

Occurrence: Always

refinement.categoryDistributionsarray of CategoryDistributionA array of containers for the all the category refinements.

Occurrence: Conditional

refinement.categoryDistributions.categoryIdstringThe identifier of the category.

Occurrence: Always

refinement.categoryDistributions.categoryNamestringThe name of the category, such as Baby & Toddler Clothing.

Occurrence: Always

refinement.categoryDistributions.matchCountintegerThe number of items in this category.

Occurrence: Always

refinement.categoryDistributions.refinementHrefstringThe HATEOAS reference of this category.

Occurrence: Always

refinement.conditionDistributionsarray of ConditionDistributionA array of containers for the all the condition refinements.

Occurrence: Conditional

refinement.conditionDistributions.conditionstringThe text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

refinement.conditionDistributions.conditionIdstringThe identifier of the condition. For example, 1000 is the identifier for NEW.

Occurrence: Always

refinement.conditionDistributions.matchCountintegerThe number of items having the condition.

Occurrence: Always

refinement.conditionDistributions.refinementHrefstringThe HATEOAS reference of this condition.

Occurrence: Always

refinement.dominantCategoryIdstringThe identifier of the category that most of the items are part of.

Occurrence: Always

totalintegerThe total number of items that match the input criteria.

Occurrence: Always

warningsarray of ErrorDetailV3The container with all the warnings for the request.

Occurrence: Conditional

warnings.categorystringThis string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Conditional

warnings.domainstringThe name of the primary system where the error occurred. This is relevant for application errors.

Occurrence: Conditional

warnings.errorIdintegerA unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of stringAn array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestringA detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.messagestringA description of the condition that caused the error or warning.

Occurrence: Conditional

warnings.outputRefIdsarray of stringAn array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.namestringThis is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.parameters.valuestringThis is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstringThe name of the subdomain in which the error or warning occurred.

Occurrence: NA

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200OK
400Bad Request
500Internal Server Error

Error codes

CodeDomainCategoryMeaning
12000API_BROWSEAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
12001API_BROWSEREQUESTThe call must have a valid 'q', 'category_ids', 'epid' or 'gtin' query parameter.
12004API_BROWSEREQUESTThe 'offset' value cannot be negative.
12005API_BROWSEREQUESTThe 'offset' value must be an integer.
12006API_BROWSEREQUESTThe 'limit' value should be between 1 and 200 (inclusive).
12007API_BROWSEREQUESTThe 'limit' value must be an integer value.
12013API_BROWSEBUSINESSTop level category browsing is not allowed. Please provide keywords or more filters for the applied top level category.
12019API_BROWSEBUSINESSCurrently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .
12020API_BROWSEBUSINESSThe 'fieldgroups' value {fieldgroups} is invalid when multiple 'category_ids' are specified. Either change the call to have only one value in 'category_ids' or remove the 'fieldgroups'.
12023API_BROWSEREQUESTThis keyword search results in a response that is too large to return. Either change the keyword or add additional query parameters and/or filters.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Search for Items by Keyword

This sample returns a set of eBay items that match the keyword.

Input

The inputs are limit and q, which is the keyword, URI parameters. There is no payload with this request.
GET
https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=3

Output

If the call is successful, 3 items per set will be returned.

Sample 2: Search for Items by Category

This sample searches for items in the Cameras & Photo|Camera Drones category.

Input

The input is categoryIds URI parameters. There is no payload with this request.

Note: As with all query parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about encoding request parameters, see URL Encoding Parameters and Headers at the top of this page.

GET
https://api.ebay.com/buy/browse/v1/item_summary/search?category_ids=20863&limit=3

Output

If the call is successful, drones with cameras are returned.

Sample 3: Refine Keyword Results by Category

Using a category ID with a keyword gives you additional control over the result set. For example, let's say you are looking of a toy phone. If you search for "phone", the result set will be mobile phones because this is the "Best Match" for this search. But if you also include the toy category ID, the results will be what you wanted.

Input

The inputs are q and categoryIds URI parameters. There is no payload with this request.

Note: As with all query parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about encoding request parameters, see URL Encoding Parameters and Headers at the top of this page.

GET
https://api.ebay.com/buy/browse/v1/item_summary/search?q=phone&category_ids=220&limit=3

Output

If the call is successful, toy phones are returned.

Sample 4: Retrieve the Item Aspects by Keyword Search

This call searches for drones. Based on the results of that search, it returns the dominant category ID, which is the category most of the items are in and the aspect refinements for this category.

Input

The inputs are q and fieldgroups=ASPECT_REFINEMENTS URI parameters. There is no payload with this request.

Note: As with all query parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about encoding request parameters, see URL Encoding Parameters and Headers at the top of this page.

GET
https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&fieldgroups=ASPECT_REFINEMENTS

Output

If the call is successful, the dominantCategoryId field, which we will use in the next sample, and the aspectDistributions container are returned.

Sample 5: Return All Refinements For a Category

This call retrieves all the refinements for the category submitted. We used the category ID returned by the previous sample in the dominantCategoryId field.

If you wanted to return the refinement and the items, you would replace fieldgroups=ASPECT_REFINEMENTS,CATEGORY_REFINEMENTS,CONDITION_REFINEMENTS,BUYING_OPTION_REFINEMENTS fieldgroups=FULL.

Input

The inputs are q and fieldgroups URI parameters. There is no payload with this request.

Note: As with all query parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about encoding request parameters, see URL Encoding Parameters and Headers at the top of this page.

GET
https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=3&category_ids=179697&fieldgroups=ASPECT_REFINEMENTS,CATEGORY_REFINEMENTS,CONDITION_REFINEMENTS,BUYING_OPTION_REFINEMENTS

Output

If the call is successful, the dominantCategoryId field is return, which is the category that was submitted in the call. The categoryDistributions container is return, which shows the category name. The conditionDistributions buyingOptionDistributions aspectDistributions containers are returned, which contain all the refinements for the category. You can use response from this call to create a histogram for this category, which gives your shoppers the ability to browse the items and further refine the results.

Sample 6: Filter the Keyword Results by Item Aspects

This call searches for drones and returns only the items within the category and the item aspects specified. Because fieldgroups is set to EXTENDED it also returns the shortDescription and itemLocation.city fields.

Input

The inputs are q, category_ids, fieldgroups and aspect_filter URI parameters. There is no payload with this request.

Note: As with all query parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about encoding request parameters, see URL Encoding Parameters and Headers at the top of this page.

GET
https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&category_ids=179697&limit=3&fieldgroups=EXTENDED,MATCHING_ITEMS&aspect_filter=categoryId:179697,conditionDistributions:{NEW},Connectivity:{App Controller},Camera Integration:{Camera Included},Type:{Ready to Fly Drone}

Output

If the call is successful, a paged collection of items matching the criteria are returned.

Sample 7: Return Items with Free Shipping

This call searches for drones and returns only the items that offer free shipping.

Input

The inputs are q the maxDeliveryCost filter URI parameters. There is no payload with this request.

Note: As with all query parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about encoding request parameters, see URL Encoding Parameters and Headers at the top of this page.

GET
https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=3&filter=maxDeliveryCost:0

Output

If the call is successful, three items that have free shipping (shippingOptions.shippingCost.value is 0) are returned.

Sample 8: Return Items Based on Price and Condition

This call searches for new iPhones within a price range.

Input

The inputs are q and the price, priceCurrency, and conditions, filter URI parameters. There is no payload with this request.

Note: As with all query parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about encoding request parameters, see URL Encoding Parameters and Headers at the top of this page.

GET
https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=5&filter=price:[300..800],priceCurrency:USD,conditions:{NEW}

Output

If the call is successful, the items meeting the criteria are returned.