browse APIv1_beta.11.0

search

GET
/item_summary/search

This call searches for eBay items by various URI 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.

The following are examples of using these parameters to limit the results:

  • The following call returns 4,330,774 items.
       /buy/browse/v1/item_summary/search?q=phone
  • This call, which limits the results to the category "Cell Phones & Smartphones", returns 142,098 items.
       /buy/browse/v1/item_summary/search?q=phone&category_ids=9355
  • These calls, which limit results to a Samsung Galaxy S5, returns 97 items.
       /buy/browse/v1/item_summary/search?q=phone&category_ids=220&epid=182527490
       or
       /buy/browse/v1/item_summary/search?epid=182527490

Controlling what is returned

You can also control what is returned by using the fieldgroups field. In addition to returning items, which is the default, you can return refinements (metadata) about an item that enables you to create aspect histograms. A histogram enables users to drill down in each refinement narrowing the search results. You can return:

  • ASPECT_REFINEMENTS - Lets shoppers refine the result set by variation aspects, such as Brand, Color, etc.
  • BUYING_OPTION_REFINEMENT - Lets shoppers refine the result set by either FIXED_PRICE or AUCTION
  • CATEGORY_REFINEMENTS - Lets shoppers refine the result set by items in a category
  • CONDITION_REFINEMENT - Lets shoppers refine the result set by item condition, such as NEW, USED, etc.
  • MATCHING_ITEMS - The default, which returns the items. When used with one or more of the refinement values above the specified refinements and all the matching items are returned.
  • FULL - This returns all the refinement containers and all the matching items.

Filtering by aspects

You can use the ASPECT_REFINEMENTS returned to filter the result set using the aspect_filter field.

For example:

  • This call gets a list of the aspects pairs for the item and the dominant category (category most of the items are in).
    /buy/browse/v1/item_summary/search?q=world cup soccer ball&fieldgroups=ASPECT_REFINEMENTS
  • This call filters the items by one of the aspect pairs returned and the dominant category. The category ID is required twice when using aspect_filter; once as a URI parameter and as part of the aspect_filter.
    /buy/browse/v1/item_summary/search?q=world cup soccer ball&category_ids=20863&aspect_filter=categoryId:20863,Brand:{adidas}
  • This call filters the items by multiple aspects
    /buy/browse/v1/item_summary/search?q=world cup soccer ball&category_ids=20863&aspect_filter=categoryId:20863,Brand:{adidas},Featured Refinements:{Adidas Match Ball}
  • This call filters the items by multiple aspect values
    /buy/browse/v1/item_summary/search?q=world cup soccer ball&category_ids=20863&aspect_filter=categoryId:20863,Brand:{Nike|Wilson}

Fields filters

There are also field filters you can use to refine the result set, such as listing format, item condition, price range, listing end date, location, and more. You can use multiple field filters in a single call. For a list and details of the supported filters, see search Call Field Filters.

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 call

  • 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 call. If you are an eBay Network Partner you must use affiliateCampaignId=ePNCampaignId,affiliateReferenceId=referenceId in the header in order to be paid for selling eBay items on your site and it is strongly recommended you use contextualLocation to improve the estimated delivery window information. For details see, Request headers in the Buy APIs Overview.

Restrictions

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

URL Encoding Parameters and Headers

As with all query parameter values, the filter parameter value and request header values must be URL encoded. For better readability, the examples in this document omit the encoding.

Example:
  search?q=world cup soccer ball&category_ids=20863&aspect_filter=categoryId:20863,Brand:{Nike|Wilson}

Encoded Example:
   search?q=world cup soccer ball&category_ids=20863&aspect_filter=categoryId%3A20863%2CBrand%3A%7BNike%7CWilson%7D

For more information about encoding, see HTML URL Encoding Reference.

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 call 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 call and the Browse API getItem, getItemByLegacyId, and getItemsByItemGroup calls return the ePID of the product. You can also use the product_summary/search call in the Catalog API to search for the ePID of the product.

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

Maximum: 1
Required: The call 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 call 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 lets you control what is to be 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. For code examples see, aspect_filter.

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

offsetstringThe 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 call will retrieve items 1-10 from the list of items returned, if offset is 10 and limit is 10, the call 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 in a result set.

Default: 50
Maximum per result set: 200
Total Maximum number of items for all result sets: 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 search Call 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 call 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 call 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 (iphone,ipad), the query returns items that have iphone AND ipad.
  • If the keywords are separated by a space (iphone ipad or iphone, ipad), the query returns items that have iphone OR ipad.
Restriction: The * wildcard character is not allowed in this field.
Required: The call 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 Application access token with the following scope(s):

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 result set.

For example:
https://api.ebay.com/buy/v1/item/search?q=shirt&price=[20..80]&limit=5

This query is for a shirt, that is priced between 20 and 80 dollars and limits the response to 5 items.

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 Searching for adult only items 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 ConditionEnum.

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

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.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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 call 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 call.

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 call, 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.

Occurrence: Always

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.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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 call 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.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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 (calculated shipping).

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.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates 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 maximum number of items that can be returned in a result set. This is the limit value that was used in the request.

Occurrence: Always

nextstringThe URL for the next result set. This is returned if there is a next result set.

The following example returns items 11 thru 20 from the list of items.

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

Occurrence: Always

offsetintegerThis value indicates the current 'page' of items being displayed. This value is 0 for the first page of data, 1 for the second page of data, and so on.

Occurrence: Always

prevstringThe URL for the previous result set. This is returned if there is a previous result set.

The following example returns items 1 thru 10 from the list of items.

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

Occurrence: Always

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

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 input 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
200Success
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: 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.

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 Refinements

This call searches for drones and returns only the items within the category and refinements specified.

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=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=3&filter=price:[300..800],priceCurrency:USD,conditions:{NEW}

Output

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