POST/item_summary/search_by_image
Note: This is an experimental method that is available to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.
This method searches for eBay items based on a image and retrieves summaries of the items. You pass in a Base64 image in the request payload and can refine the search by category, or eBay product ID (ePID), or a combination of these using URI parameters.
To get the Base64 image string, you can use sites such as https://codebeautify.org/image-to-base64-converter.
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.
- Filtering by item aspects using the aspect_filter parameter.
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.
URL Encoding for Parameters
Query parameter values need to be URL encoded. For details, see URL encoding query parameter values. For readability, code examples in this document have not been URL encoded.
Restrictions
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in theitemAffiliateWebUrl
field to forward your buyer to the ebay.com site. Input
Resource URI
This method is not supported in Sandbox environment.
URI parameters
Parameter | Type | Description |
---|---|---|
charity_ids | array of string | The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities. For example: /buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469 The charity ID is the charity's registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called "Charity Number".
category_Ids and q fields with a charity_Ids to filter the result set. This gives you additional control over the result set. Restriction: This is supported only on the US and GB marketplaces. Maximum: 20 IDs Required: One ID Occurrence: Optional |
fieldgroups | array of string | This 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:
Default: MATCHING_ITEMS Occurrence: Optional |
category_ids | array of string | The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs. Note: Currently, you can pass in only one category ID per request. You can also use any combination of the category_Ids and epid fields. This gives you additional control over the result set. 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:
Occurrence: Optional |
filter | array of FilterField | An array of 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} Note: Refer to Buy API Field Filters for details and examples of all supported filters. Occurrence: Optional |
sort | array of SortField | The order and field name that is used to sort the items. You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen ( - ) before the name of the sorting option. If no sort parameter is submitted, the result set is sorted by "Best Match".Here are some examples showing how to use the sort query parameter:
Occurrence: Optional |
limit | string | The number of items from the result set returned in a single page. Note: If a value is set in the limit field, the value of offset must be either zero or a multiple of the limit value. An error is returned for invalid values of offset. Note: This method can return a maximum of 10,000 items in one results set. Min: 1 Max: 200 Default: 50 Occurrence: Optional |
offset | string | Specifies the number of items to skip in the result set. This is used with the limit field to control the pagination of the output. For example, 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-20 from the list of items returned. Note: The value of offset must be either zero or a multiple of the value set in the limit field. An error is returned for invalid values of offset. Note: This method can return a maximum of 10,000 items in one results set. Min: 0 Max: 9,999 Default: 0 Occurrence: Optional |
aspect_filter | AspectFilter | This 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. category_ids=15724&aspect_filter=categoryId:15724,Color:{Red} Required: The category ID is required twice; once as a URI parameter and as part of the aspect_filter. Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
Header | Type | Description |
---|---|---|
Content-Type | string | This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required |
X-EBAY-C-ENDUSERCTX | string | This header is required to support revenue sharing for eBay Partner Network and to improve the accuracy of shipping and delivery time estimations. For additional information, refer to Use request headers. Occurrence: Optional |
X-EBAY-C-MARKETPLACE-ID | string | This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.See HTTP request headers for the marketplace ID values. Occurrence: Strongly Recommended |
OAuth scope
This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope
See OAuth access tokens for more information.
Request payload
Copy complete valid JSON to clipboardRequest fields
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
Output container/field | Type | Description |
---|---|---|
autoCorrections | AutoCorrections | The auto-corrected inputs. Occurrence: Conditional |
autoCorrections.q | string | The automatically spell-corrected keyword from the request. Occurrence: Conditional |
href | string | The URI of the current page of results. Occurrence: Always |
itemSummaries | array of ItemSummary | An array of the items on this page. The items are sorted according to the sorting method specified in the request. Occurrence: Conditional |
itemSummaries.additionalImages | array of Image | An 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.height | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.additionalImages.imageUrl | string | The URL of the image. Occurrence: Always |
itemSummaries.additionalImages.width | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.adultOnly | boolean | This 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.availableCoupons | boolean | This boolean attribute indicates if coupons are available for the item. Occurrence: Always |
itemSummaries.bidCount | integer | This 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.buyingOptions | array of string | A comma separated list of all the purchase options available for the item.
Occurrence: Always |
itemSummaries.categories | array of Category | This array returns the name and ID of each category associated with the item, including top level, branch, and leaf categories. Occurrence: Conditional |
itemSummaries.categories.categoryId | string | The unique identifier of the category. Occurrence: Always |
itemSummaries.categories.categoryName | string | The name of the category. Occurrence: Conditional |
itemSummaries.compatibilityMatch | CompatibilityMatchEnum | This indicates how well the item matches the compatibility_filter product attributes. Occurrence: Conditional |
itemSummaries.compatibilityProperties | array of CompatibilityProperty | This container returns only the product attributes that are compatible with the item. These attributes were specified in the compatibility_filter in the request. This means that if you passed in 5 attributes and only 4 are compatible, only those 4 are returned. If none of the attributes are compatible, this container is not returned. Occurrence: Conditional |
itemSummaries.compatibilityProperties.localizedName | string | The name of the product attribute that as been translated to the language of the site. Occurrence: Conditional |
itemSummaries.compatibilityProperties.name | string | The name of the product attribute, such as Make, Model, Year, etc. Occurrence: Conditional |
itemSummaries.compatibilityProperties.value | string | The value for the name attribute, such as BMW, R1200GS, 2011, etc. Occurrence: Conditional |
itemSummaries.condition | string | The text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names. Occurrence: Conditional |
itemSummaries.conditionId | string | The 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. Occurrence: Conditional |
itemSummaries.currentBidPrice | ConvertedAmount | This 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.convertedFromCurrency | CurrencyCodeEnum | The 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.convertedFromValue | string | The 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.currency | CurrencyCodeEnum | The 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. Occurrence: Conditional |
itemSummaries.currentBidPrice.value | string | The 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: Conditional |
itemSummaries.distanceFromPickupLocation | TargetLocation | This 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.unitOfMeasure | string | This 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 Occurrence: Conditional |
itemSummaries.distanceFromPickupLocation.value | string | This 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.energyEfficiencyClass | string | This indicates the European energy efficiency rating (EEK) of the item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only. Occurrence: Conditional |
itemSummaries.epid | string | An 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.image | Image | The URL to the primary image of the item. Occurrence: Always |
itemSummaries.image.height | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.image.imageUrl | string | The URL of the image. Occurrence: Always |
itemSummaries.image.width | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.itemAffiliateWebUrl | string | The URL to the View Item page of the item which includes the affiliate tracking ID.
Occurrence: Conditional |
itemSummaries.itemCreationDate | string | The date and time when the item listing was created. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. Occurrence: Conditional |
itemSummaries.itemEndDate | string | The date and time up to which the item can be purchased. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. Occurrence: Conditional |
itemSummaries.itemGroupHref | string | The 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. Occurrence: Conditional |
itemSummaries.itemGroupType | string | The indicates the item group type. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. Occurrence: Conditional |
itemSummaries.itemHref | string | The URI for the Browse API getItem method, which can be used to retrieve more details about items in the search results. Occurrence: Always |
itemSummaries.itemId | string | The unique RESTful identifier of the item. Occurrence: Always |
itemSummaries.itemLocation | ItemLocationImpl | This 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: Conditional |
itemSummaries.itemLocation.addressLine1 | string | The first line of the street address. Occurrence: Conditional |
itemSummaries.itemLocation.addressLine2 | string | The second line of the street address. This field may contain such values as an apartment or suite number. Occurrence: Conditional |
itemSummaries.itemLocation.city | string | The city in which the item is located. Occurrence: Conditional |
itemSummaries.itemLocation.country | CountryCodeEnum | The two-letter ISO 3166 standard code that indicates the country in which the item is located. Occurrence: Always |
itemSummaries.itemLocation.county | string | The county in which the item is located. Occurrence: Conditional |
itemSummaries.itemLocation.postalCode | string | The postal code (or zip code in US) where the item is located. Sellers set a postal code (or zip code in US) for items when they are listed. The postal code is used for calculating proximity searches. It is anonymized when returned in itemLocation.postalCode via the API. Occurrence: Conditional |
itemSummaries.itemLocation.stateOrProvince | string | The state or province in which the item is located. Occurrence: Conditional |
itemSummaries.itemWebUrl | string | The 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.leafCategoryIds | array of string | The leaf category IDs of the item. When the item belongs to two leaf categories, the ID values are returned in the order primary, secondary. Occurrence: Always |
itemSummaries.legacyItemId | string | The unique identifier of the eBay listing that contains the item. This is the traditional/legacy ID that is often seen in the URL of the listing View Item page. Occurrence: Always |
itemSummaries.listingMarketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace where the seller listed the item. Occurrence: Always |
itemSummaries.marketingPrice | MarketingPrice | This 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.discountAmount | ConvertedAmount | This container returns the monetary amount of the seller discount. Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.convertedFromCurrency | CurrencyCodeEnum | The 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.convertedFromValue | string | The 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.currency | CurrencyCodeEnum | The 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. Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.value | string | The 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: Conditional |
itemSummaries.marketingPrice.discountPercentage | string | This field expresses the percentage of the seller discount based on the value in the originalPrice container. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice | ConvertedAmount | This container returns the monetary amount of the item without the discount. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.convertedFromCurrency | CurrencyCodeEnum | The 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.convertedFromValue | string | The 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.currency | CurrencyCodeEnum | The 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. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.value | string | The 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: Conditional |
itemSummaries.marketingPrice.priceTreatment | PriceTreatmentEnum | Indicates the pricing treatment (discount) that was applied to the price of the item. Occurrence: Conditional |
itemSummaries.pickupOptions | array of PickupOptionSummary | This 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.pickupLocationType | string | This container returns the local pickup options available to the buyer. Possible values are Occurrence: Conditional |
itemSummaries.price | ConvertedAmount | The price of the item after it has been converted into another currency.
Occurrence: Always |
itemSummaries.price.convertedFromCurrency | CurrencyCodeEnum | The 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.convertedFromValue | string | The 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.currency | CurrencyCodeEnum | The 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. Occurrence: Conditional |
itemSummaries.price.value | string | The 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: Conditional |
itemSummaries.priceDisplayCondition | PriceDisplayConditionEnum | Indicates when in the buying flow the item's price can appear for minimum advertised price (MAP) items, which is the lowest price a retailer can advertise/show for this item. Occurrence: Conditional |
itemSummaries.priorityListing | boolean | This field is returned as Occurrence: Always |
itemSummaries.qualifiedPrograms | array of string | An array of the qualified programs available for the item, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION. Occurrence: Conditional |
itemSummaries.seller | Seller | This container returns basic information about the seller of the item, such as name, feedback score, etc. Occurrence: Always |
itemSummaries.seller.feedbackPercentage | string | The percentage of the total positive feedback. Occurrence: Always |
itemSummaries.seller.feedbackScore | integer | The 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.sellerAccountType | string | Indicates 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. Occurrence: Conditional |
itemSummaries.seller.username | string | The user name created by the seller for use on eBay. Occurrence: Always |
itemSummaries.shippingOptions | array of ShippingOptionSummary | This container returns the shipping options available to ship the item. Occurrence: Conditional |
itemSummaries.shippingOptions.guaranteedDelivery | boolean | Indicates if the seller has committed to shipping the item with eBay Guaranteed Delivery. With eBay Guaranteed Delivery, the seller is committed to getting the line item to the buyer within 4 business days or less. See the Buying items with eBay Guaranteed Delivery help topic for more details about eBay Guaranteed Delivery. Occurrence: Conditional |
itemSummaries.shippingOptions.maxEstimatedDeliveryDate | string | The 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. Occurrence: Conditional |
itemSummaries.shippingOptions.minEstimatedDeliveryDate | string | The 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. Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost | ConvertedAmount | This is the estimated price to ship the item.
Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.convertedFromCurrency | CurrencyCodeEnum | The 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.convertedFromValue | string | The 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.currency | CurrencyCodeEnum | The 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. Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.value | string | The 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: Conditional |
itemSummaries.shippingOptions.shippingCostType | string | Indicates the type of shipping used to ship the item. Possible values are Occurrence: Conditional |
itemSummaries.shortDescription | string | This 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. Occurrence: Conditional |
itemSummaries.thumbnailImages | array of Image | An array of thumbnail images for the item. Occurrence: Conditional |
itemSummaries.thumbnailImages.height | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.thumbnailImages.imageUrl | string | The URL of the image. Occurrence: Always |
itemSummaries.thumbnailImages.width | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.title | string | The seller-created title of the item. Occurrence: Always |
itemSummaries.topRatedBuyingExperience | boolean | This indicates if the item is a top-rated plus item. There are three benefits of a top-rated plus item: a minimum 30-day money-back return policy, shipping the item in 1 business day with tracking provided, and the added comfort of knowing that this item is from an experienced seller with the highest buyer ratings. See the Top Rated Plus Items and Becoming a Top Rated Seller and qualifying for Top Rated Plus help topics for more information. Occurrence: Conditional |
itemSummaries.tyreLabelImageUrl | string | The URL to the image that shows the information on the tyre label. Occurrence: Conditional |
itemSummaries.unitPrice | ConvertedAmount | 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. Occurrence: Conditional |
itemSummaries.unitPrice.convertedFromCurrency | CurrencyCodeEnum | The 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.convertedFromValue | string | The 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.currency | CurrencyCodeEnum | The 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. Occurrence: Conditional |
itemSummaries.unitPrice.value | string | The 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: Conditional |
itemSummaries.unitPricingMeasure | string | The designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item. This helps buyers compare prices. Occurrence: Conditional |
itemSummaries.watchCount | integer | The number of users that have added the item to their watch list. Occurrence: Conditional |
limit | integer | The 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 |
next | string | The 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. Occurrence: Conditional |
offset | integer | This value indicates the offset used for current page of items being returned. Assume the initial request used an offset of Occurrence: Always |
prev | string | The URI for the previous page of results. This is returned if there is a previous page of results from the result set. Occurrence: Conditional |
refinement | Refinement | The container for all the search refinements. Occurrence: Conditional |
refinement.aspectDistributions | array of AspectDistribution | An array of containers for the all the aspect refinements. Occurrence: Conditional |
refinement.aspectDistributions.aspectValueDistributions | array of AspectValueDistribution | An 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.localizedAspectValue | string | The value of an aspect. For example, Red is a value for the aspect Color. Occurrence: Always |
refinement.aspectDistributions.aspectValueDistributions.matchCount | integer | The number of items with this aspect. Occurrence: Always |
refinement.aspectDistributions.aspectValueDistributions.refinementHref | string | A HATEOAS reference for this aspect. Occurrence: Always |
refinement.aspectDistributions.localizedAspectName | string | The name of an aspect, such as Brand, Color, etc. Occurrence: Conditional |
refinement.buyingOptionDistributions | array of BuyingOptionDistribution | An array of containers for the all the buying option refinements. Occurrence: Conditional |
refinement.buyingOptionDistributions.buyingOption | string | The container that returns the buying option type. This will be AUCTION, FIXED_PRICE, CLASSIFIED_AD, or a combination of these options. For details, see buyingOptions. Occurrence: Always |
refinement.buyingOptionDistributions.matchCount | integer | The number of items having this buying option. Occurrence: Always |
refinement.buyingOptionDistributions.refinementHref | string | The HATEOAS reference for this buying option. Occurrence: Always |
refinement.categoryDistributions | array of CategoryDistribution | An array of containers for the all the category refinements. Occurrence: Conditional |
refinement.categoryDistributions.categoryId | string | The identifier of the category. Occurrence: Always |
refinement.categoryDistributions.categoryName | string | The name of the category, such as Baby & Toddler Clothing. Occurrence: Always |
refinement.categoryDistributions.matchCount | integer | The number of items in this category. Occurrence: Always |
refinement.categoryDistributions.refinementHref | string | The HATEOAS reference of this category. Occurrence: Always |
refinement.conditionDistributions | array of ConditionDistribution | An array of containers for the all the condition refinements. Occurrence: Conditional |
refinement.conditionDistributions.condition | string | The text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names. Occurrence: Conditional |
refinement.conditionDistributions.conditionId | string | The identifier of the condition. For example, 1000 is the identifier for NEW. Occurrence: Conditional |
refinement.conditionDistributions.matchCount | integer | The number of items having the condition. Occurrence: Always |
refinement.conditionDistributions.refinementHref | string | The HATEOAS reference of this condition. Occurrence: Always |
refinement.dominantCategoryId | string | The identifier of the category that most of the items are part of. Occurrence: Always |
total | integer | The total number of items that match the input criteria. Occurrence: Always |
warnings | array of ErrorDetailV3 | The container with all the warnings for the request. Occurrence: Conditional |
warnings.category | string | This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. Occurrence: Always |
warnings.domain | string | The name of the primary system where the error occurred. This is relevant for application errors. Occurrence: Always |
warnings.errorId | integer | A 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: Always |
warnings.inputRefIds | array of string | An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any. Occurrence: Conditional |
warnings.longMessage | string | A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem. Occurrence: Conditional |
warnings.message | string | A description of the condition that caused the error or warning. Occurrence: Always |
warnings.outputRefIds | array of string | An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any. Occurrence: Conditional |
warnings.parameters | array of ErrorParameterV3 | An 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.name | string | This is the name of input field that caused an issue with the call request. Occurrence: Conditional |
warnings.parameters.value | string | This is the actual value that was passed in for the element specified in the name field. Occurrence: Conditional |
warnings.subdomain | string | The 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.
Status | Meaning |
---|---|
200 | OK |
400 | Bad Request |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
12000 | API_BROWSE | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
12004 | API_BROWSE | REQUEST | The 'offset' value cannot be negative. |
12005 | API_BROWSE | REQUEST | The 'offset' value must be an integer. |
12006 | API_BROWSE | REQUEST | The 'limit' value should be between 1 and 200 (inclusive). |
12007 | API_BROWSE | REQUEST | The 'limit' value must be an integer value. |
12013 | API_BROWSE | BUSINESS | Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. |
12019 | API_BROWSE | BUSINESS | Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} . |
12020 | API_BROWSE | BUSINESS | The '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'. |
12025 | API_BROWSE | REQUEST | The 'charity_ids' field has exceeded the maximum limit of 20. |
12026 | API_BROWSE | REQUEST | The 'charity_ids' field is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}. |
12029 | API_BROWSE | REQUEST | The maximum number of listings that can be retrieved is 10,000, so your offset value must be less than 10,000. If 10,000 or more listings are matching your search criteria, consider narrowing the scope of your search. |
12030 | API_BROWSE | REQUEST | The number of categories in the request has exceeded the limit. Please reduce the number of categories to {allowedMaxCategories} or less. |
12032 | API_BROWSE | REQUEST | The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer. |
12033 | API_BROWSE | REQUEST | The 'qualifiedPrograms' filter for {filterValue} requires valid 'deliveryPostalCode' and 'deliveryCountry' filter values. |
12034 | API_BROWSE | REQUEST | The 'buyingOptions' filter value {filterValue} is not supported for the sort by {sortOption}. For the supported values, refer to the API call documentation. |
12500 | API_BROWSE | REQUEST | This image search results in a response that is too large to return. Either change the image or add additional query parameters and/or filters. |
12501 | API_BROWSE | REQUEST | The image data is empty, is not Base64 encoded, or is invalid. |
12507 | API_BROWSE | REQUEST | To filter by 'guaranteedDeliveryInDays', you must include 'deliveryCountry'. |
12508 | API_BROWSE | REQUEST | To filter by 'guaranteedDeliveryInDays', you must include 'deliveryPostalCode' for the 'deliveryCountry'. |
12509 | API_BROWSE | REQUEST | The 'guaranteedDeliveryInDays' value {guaranteedDeliveryInDays} is invalid for 'deliveryCountry' value {deliveryCountry}. Valid values for 'guaranteedDeliveryInDays' for {deliveryCountry} must be in the range of {rangeLowerBound} to {rangeUpperBound} inclusive. |
12510 | API_BROWSE | REQUEST | The 'guaranteedDeliveryInDays' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12512 | API_BROWSE | REQUEST | The 'qualifiedPrograms' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12513 | API_BROWSE | BUSINESS | The 'priorityListing' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12514 | API_BROWSE | BUSINESS | The 'priorityListing' filter is not supported for the specified sort option. Refer to the API call documentation. |
12515 | API_BROWSE | REQUEST | The 'offset' value must be either zero or a multiple of the 'limit' value. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
12002 | API_BROWSE | REQUEST | The {filterName} value is invalid. For the valid values, refer to the API call documentation. |
12003 | API_BROWSE | REQUEST | A seller 'username' provided in the request filters is invalid. |
12008 | API_BROWSE | REQUEST | The 'sort' value is invalid. For the valid values, refer to the API call documentation. |
12009 | API_BROWSE | REQUEST | The 'category_ids' query parameter is invalid. |
12010 | API_BROWSE | REQUEST | There are four filters required for local pickup. 'pickupPostalCode','pickupCountry','pickupRadiusUnit','pickupRadius'. One or more is missing or invalid. |
12011 | API_BROWSE | REQUEST | 'deliveryCountry' is a mandatory filter to provide a delivery location. 'deliveryPostalCode' is optional. |
12012 | API_BROWSE | REQUEST | A valid 'price' filter and a valid 'priceCurrency' filter is necessary to filter based on price. |
12014 | API_BROWSE | BUSINESS | The 'sellerAccountTypes' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12015 | API_BROWSE | REQUEST | The postal code filter value is invalid for the specified country and this filter was ignored. |
12016 | API_BROWSE | REQUEST | The 'fieldgroups' value {fieldgroups} is invalid. For the valid values, refer to the API call reference documentation |
12017 | API_BROWSE | REQUEST | The 'aspect_filter' query parameter must include a categoryId. For information, see the API call reference documentation. |
12018 | API_BROWSE | REQUEST | The {aspectFilter} aspect_filter value is invalid. For information, see the API call reference documentation. |
12024 | API_BROWSE | REQUEST | The 'charity_ids' value {charity_id} is invalid. For more information see the API call reference documentation. |
12031 | API_BROWSE | REQUEST | The following filter(s) is/are not supported by this operation: {unsupportedFilters}. For more information see the API call reference documentation. |
12511 | API_BROWSE | REQUEST | Either 'deliveryCountry' or 'deliveryPostalCode' is invalid, hence 'guaranteedDeliveryInDays' filter was ignored. |
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 Image
This call searches for items using an image ID.
Input
The Base64 ID of an image, which in this case is an image of a drill, in the request payload. There are no URI parameters required.
POSThttps://api.ebay.com/buy/browse/v1/item_summary/search_by_image?&limit=3&sort=-price
Output
This call returns items that are similar to the image ID submitted sort by price from smallest to largest.