POST/item_summary/search_by_image
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 with other available filters.
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, refer to the filter parameter.
- Filtering by item aspects using the aspect_filter parameter.
URL Encoding for Parameters
Query parameter values need to be URL encoded. For details, refer to 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, refer to API Restrictions.eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in the
itemAffiliateWebUrl
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 filters results to return only those items associated with the specified charity. Note: charity_ids is only supported by the US and UK marketplaces.Charity ID is a charity's unique identification number:
charity_ids may be retrieved/determined as follows:
charity_ids may be specified in each query. Additionally, charity_ids may be combined with category_ids and/or q keyword values to further filter returned results.A sample query using charity_ids is:/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469 Occurrence: Optional |
fieldgroups | array of string | A comma-separated list of values that controls 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:
MATCHING_ITEMS Occurrence: Optional |
category_ids | array of string | The category ID is used to limit the results that are returned. This field may pass in one category ID or a comma separated list of IDs as illustrated in the following examples:/buy/browse/v1/item_summary/searchByImage?category_ids=29792 /buy/browse/v1/item_summary/searchByImage?category_ids=267,29792Note: Currently, you can pass in only one category ID per request. To refine the set of information that is returned, category_ids may be combined with other available filters.Because the list of eBay category IDs is not published and category IDs are not the same across all eBay marketplaces, category IDs may be determined by:
Occurrence: Optional |
filter | array of FilterField | An array of field filters that can be used to limit/customize the result set. Refer to Buy API Field Filters for the information about available filters. For example, to filter shirts based on a specific range of prices, include the filter illustrated here: /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]Filters may also be combined within a single request as illustrated in the sample below which further refines results to return only those shirts available from specific sellers: /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}Note: Refer to Buy API Field Filters for additional information and examples of all supported filters. Occurrence: Optional |
sort | array of SortField | Note: This call currently returns results in a best-match order. This query parameter presently has no practical use. 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 offset values.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:
offset must be either zero or a multiple of the value set in the limit field. An error is returned for invalid offset values.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. Note: The category ID must be specified twice:
For example, to return items for a woman's red shirt, issue the following request: /buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}To get a list of the aspect pairs and the category, which is returned in the dominantCategoryId field, set fieldgroups to ASPECT_REFINEMENTS as illustrated here:/buy/browse/v1/item_summary/search?q=shirt&fieldgroups=ASPECT_REFINEMENTSNote: The pipe symbol is used as a delimiter between aspect filter values. If a value contains a pipe symbol (for example, the brand name 'Bed|Stü'), you must enter a backslash before the pipe character to prevent it from being evaluated as a delimiter. The following example illustrates the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol: /buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed\|Stü|Nike} 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 |
Accept-Language | string | This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example:
Occurrence: Conditional |
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 in the Buying Integration Guide. 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 MarketplaceIdEnum for supported 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
Input container/field | Type | Description |
---|---|---|
image | string | The Base64 string of the image. Occurrence: Required |
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. https://api.ebay.com/buy/v1/item_summary/search?q=shirt&limit=5&offset=0. 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 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, refer to the Adult items policy. 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 an item matches the
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 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 Occurrence: Conditional |
itemSummaries.condition | string | The text describing the condition of the item, such as New or Used. For a list of condition names, refer to Item Condition IDs and Names. Occurrence: Conditional |
itemSummaries.conditionId | string | The identifier of the condition of the item. For example, Occurrence: Conditional |
itemSummaries.currentBidPrice | ConvertedAmount | This container returns the current highest bid for an auction item. The Occurrence: Conditional |
itemSummaries.currentBidPrice.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.currentBidPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional |
itemSummaries.currentBidPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.currentBidPrice.value | string | The monetary amount in the currency specified by the Occurrence: Conditional |
itemSummaries.distanceFromPickupLocation | TargetLocation | This container returns the distance away that the item is from the 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 for items when they are listed. The postal code is used for calculating proximity searches. It is anonymized when returned in 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 on which 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 Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.value | string | The monetary amount in the currency specified by the Occurrence: Conditional |
itemSummaries.marketingPrice.discountPercentage | string | This field expresses the percentage of the seller discount based on the value in the 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 Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.value | string | The monetary amount in the currency specified by the 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 returned only 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 Occurrence: Conditional |
itemSummaries.price.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional |
itemSummaries.price.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.price.value | string | The monetary amount in the currency specified by the 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 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:
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 or INDIVIDUAL 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 | Although this field is still returned, it can be ignored since eBay Guaranteed Delivery is no longer a supported feature on any marketplace. This field may get removed from the schema in the future. 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 Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.value | string | The monetary amount in the currency specified by the 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 does not provide enough information but the description is too big. Surfacing the "title": "Petrel U42W FPV Drone RC Quadcopter w/HD Camera Live Video One Key Off / Landing", Restriction: This field is returned by the search method only when fieldgroups = EXTENDED . 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. For more information, refer to Look for Top Rated Plus Items and Seller performance overview. 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. "unitPricingMeasure": "100g", Occurrence: Conditional |
itemSummaries.unitPrice.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.unitPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional |
itemSummaries.unitPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional |
itemSummaries.unitPrice.value | string | The monetary amount in the currency specified by the 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. "unitPricingMeasure": "100g", 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 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. https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=10 Occurrence: Conditional |
offset | integer | This value indicates the 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. https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=0 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 ( 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 unique 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, refer to Item Condition IDs and Names. Occurrence: Conditional |
refinement.conditionDistributions.conditionId | string | The identifier of the condition. For example, 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 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.