Browse API

Using the Browse API, you can create a rich selection of items for your buyers to browse with keyword and category searches.

The Browse API has the item_summary, search_by_image, and item resources.

• item_summary:
  • Lets shoppers search for specific items by keyword, GTIN, category, charity, product, compatible products, Promoted Listings, or item aspects and refine the results by using filters.
  • Lets shoppers retrieve the details of a specific item or all the items in an item group, which is an item with variations such as color and size and check if a product is compatible with the specified item, such as whether a specific car is compatible with a specific part.
  • Lets shoppers search for an item or a group of items based on an image ID (a Base64 string) search.
• item:
• Retrieve detailed information for a purchasable items to enable users to make buying decisions. In addition to the basic item information and providing additional information about shipping, seller, etc., the item details include product review data, item location, return policy terms, and more.
• Check if the listing is available for purchase by reviewing the itemEndDate and estimatedAvailabilityStatus fields. If the item has an EndDate in the past, the listing should not be pulled in.
• Retrieve the available payment methods for an item, including the payment method types, brands, and instructions for the buyer.
• Provides a bridge between the RESTful Buy APIs and the legacy APIs, such as Finding.

The use cases that these resources support are described below. For an example of each of the use cases, see the method Sample section in the Browse API reference.

Search for items

You can search for items by keywords, image ID (a Base64 string), eBay category ID, charity IDs, eBay product ID (EPID), or GTIN (Global Trade Item Number), or a combination of these.

The following are examples of using these query parameters:

• Search by keyword
  /search?q=phone
• Limit the results to the category "Cell Phones & Smartphones"
  

  /search?q=phone&category_ids=9355

• Limit the results to the Samsung Galaxy S5 product
  

  /search?q=phone&category_ids=220&epid=182527490
  or
  /search?epid=182527490

For each item found, a subset of the item details is returned. To get the complete item details, pass in the itemId returned by search in the getItem method.

Retrieve item aspects

By default, search returns matching items. But in addition to or instead of returning items, you can use the fieldgroups query parameter to retrieve refinements (aspects) of the item. This information lets you refine the items returned by aspect and create histograms, which enables shoppers to drill down in each refinement narrowing the search results.

You can retrieve:

• ASPECT_REFINEMENTS - Lets shoppers refine the result set by variation aspects, such as Brand, Color, etc.
• BUYING_OPTION_REFINEMENTS - 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_REFINEMENTS - Lets shoppers refine the result set by item condition, such as NEW, USED, etc.
• EXTENDED - Returns the shortDescription and itemLocation.city fields.
• MATCHING_ITEMS - The default, which returns the items matching the search criteria. 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, except the Promoted Listing items.

Curate the search results

You can use the filter and the aspect_filter query parameters to control what items are returned in the search results. These parameters make it quick and easy to curate the search results.

Filtering by field value

You use the filter query parameter to filter on the value of fields, such as buying options, condition, price range, free shipping, etc. See Buy API Field Filters for details and examples for all the available field filters.

Filtering by item aspect

You use the aspect_filter query parameter to filter the search result set by item aspects within a category, such as Brand or color.

The following examples show you how to get the dominant category and the item aspects and then filter by these aspects.

• Get the dominant category and item aspects
  

  /search?q=world cup soccer ball&fieldgroups=ASPECT_REFINEMENTS
  

• Filter the items by one aspect (Brand)

  /search?q=world cup soccer ball&category_ids=20863&aspect_filter=categoryId:20863,Brand:{adidas}

• Filter the items by multiple aspects

  /search?q=world cup soccer ball&category_ids=20863&aspect_filter=categoryId:20863,Brand:{adidas},Featured Refinements:{Adidas Match Ball}

• Filter the items by multiple aspect values

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

Creating a histogram

You can use the item aspects to create histograms, which enables shoppers to drill down in each refinement narrowing the search results. The following is an example of a histogram of camera brands. It was created from the data returned in the aspect refinement container (aspectDistributions).

/search?q=camera&fieldgroups=ASPECT_REFINEMENTS

      

When a shopper clicks on one of the refinements, such as "Canon", you use the search method to retrieve only Canon cameras.

search?q=camera&categoryId:20863&aspect_filter=categoryId:20863,Brand:{canon}

Sort results and limit items per page

You can also sort the search results and limit the number of items returned "per page".

Retrieve specific items and item groups

You can retrieve specific purchasable items and the individual items within an item group.

Retrieve a specific item

You can use the getItem method to retrieve the complete details of a specific item.

You can also use the fieldgroups query parameter with the getItem method to control what is returned. Setting this parameter is to COMPACT retrieves only a few fields that let you quickly check if the availability or price of the item has changed, if the item has been revised by the seller, or if an item's top-rated plus status has changed for items you have stored. Setting this parameter to PRODUCT retrieves the product information that describes the product associated with the item.

Retrieve items in a group

You can use the getItemsByItemGroup method to retrieve all the individual items in a group (such as the same shirt in red, size S, in red size M, in red, size L, in blue, size S, etc.).

Retrieve items using legacy item IDs

The getItemsByLegacyId method returns the RESTful item ID, which can then be used in any of other Buy API methods. You can use this method to do the following:

• Retrieve a group of items or the details of a specific item using a eBay legacy item ID. Legacy IDs are returned by eBay legacy APIs, such as the Finding API. For details, see Item ID legacy API compatibility overview.
• Retrieve an item using the legacy SKU of the item.
• Use the fieldgroups query parameter to retrieve product information that describes the product associated with the item.

Check compatibility

You can use the Browse API to search for compatible items or to check if a product is compatible with a specified item.

Search for compatible items

You can use the search method to submit a keyword, a fitment supported category ID, and the attributes used to define a specific product, such as a car, truck, or motorcycle, to find items that might be compatible. The service searches for items matching the keyword or the keyword and product attribute values in the title of the item. For example, if the keyword is brakes and compatibility-filter=Year:2018;Make:Honda, the items returned are items with brakes, 2018, or Honda in the title.

For each item found, the service checks the name/value product attribute pairs submitted and returns the following:

• If the attribute is compatible, the attribute name and value are returned in the compatibilityProperties container of the item.
• If the attribute is not compatible, it is not returned in the compatibilityProperties container of the item.
• If none of the attributes are compatible, the compatibilityProperties container is not returned.

This means the result set will have items that are compatible or could be compatible (one or more of the attributes were compatible) and items that are not compatible (none of the attributes were compatible). You can use the absence of the compatibilityProperties container to filter out the items that are not compatible.

The service also returns the CompatibilityMatchEnum value that indicates how well the item matches the attributes.

Testing search in the Sandbox

Searching for compatible items in the Sandbox is only supported using mock data. The following is the URL you must use in the Sandbox. Using anything else in the Sandbox will result in the appropriate errors.

https://api.ebay.com/buy/browse/v1/item_summary/search?search?q=brakes&category_ids=33559&compatibility_filter=Year:2012;Make:Honda;Model:Civic;Trim:EX Sedan 4-Door;Engine:1.8L 1799CC l4 GAS SOHC Naturally Aspirated

Check if an item is compatible

You can use the checkCompatibility method to check if a product such as a car, truck, or motorcycle, is compatible with a specified item.

For example, to check the compatibility of a part, you pass in the item ID of the part as a URI parameter and specify all the product attributes used to define a specific car in the compatibilityProperties container. If the method is successful, the response will return the compatibilityStatus, which tells you if the item is compatible with the product.

Specifying product attributes

The key to getting the best compatibility results is the product attributes. The more accurate they are the better the results. The search method allows you to specify any number of attributes. But the checkCompatibility method requires you to specify the following attributes.

The following table lists the required product attributes for the US marketplace that describe motor vehicles.

Cars and Trucks	Motorcycles
Year Make Model Trim Engine	Year Make Model Submodel

To find the attributes and values for a specific marketplace, you can use the compatibility methods in the Taxonomy API.

For an example, see the search sample and checkCompatibility Samples of the reference page.

Search with the eBay Items Widget

The eBay Items Widget, powered by the Browse API, is a fully-customizable component for React applications to surface a rich selection of items for buyers. It features many of the capabilities outlined in the sections above, and it comes with a ready-to-use express server and a NodeJS example to bootstrap integration with the Browse API.

This component provides a highly-responsive UI experience and provides capabilities such as: 

• Four different layouts to show items retrieved by the Browse API:
  • Single Item Carousel
  • Multiple Items Carousel
  • List
  • Gallery
• Support for customizable search parameters:
  • Search by keyword
  • Search by image
  • Search by charity ID(s)
• Options to sort search results by:
  • Price (ascending)
  • Price (descending)
  • Distance
  • Newly listed
• Ability to limit search results with pagination control
• Capacity to surface items from different eBay marketplaces

For more details about this widget, such as a full features list, prerequisites, and usage guidelines, visit the eBay Items Widget GitHub page.

Use request headers

Several of the Buy APIs use the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping time estimations.

You use this request header to enable eBay Partner Network's campaign ID to be commissioned for selling eBay items. And it is strongly recommended you use contextualLocation to improve the estimated delivery window information.

Header for affiliate information

If you are part of the eBay Partner Network you must pass in the values for affiliateCampaignId and optionally affiliateReferenceId in the X-EBAY-C-ENDUSERCTX header in the following cases:

• Browse API requests - To return the itemAffiliateWebUrl field containing the URL to the View Item page with the affiliate tracking ID.
  
• Order API placeGuestOrder request - To enable revenue sharing when the buyer purchases items.
  
  

eBay Partner Networks header example

X-EBAY-C-ENDUSERCTX: affiliateCampaignId=ePNCampaignId,affiliateReferenceId=referenceId

• The affiliateCampaignId value is required. This is a 10-digit unique number provided by the eBay Partner Network. This is embedded in the campid part of the ePN affiliate link.
• The affiliateReferenceId value is optional. This can be any value you want to use to identify this item or purchase order and can be a maximum of 256 characters. This is embedded in the customid part of the ePN affiliate link. Note: The referenceId is the same as SUB-ID.
  
  

ePN affiliate link example

https://www.ebay.com/itm/2021-New-RC-Drone-4k-HD-Wide-Angle-Camera-WIFI-FPV-Drone-Dual-Camera-Quadcopter/
2**********5?hash=item4**********5&mkevt=1&mkcid=1&mkrid=711-53200-19255-0&campid=1********E&
customid=2**********F&toolid=10001

Specifying affiliate information - RESTful APIs vs legacy APIs

There are differences between how the RESTful APIs and the legacy API handle specifying affiliate tracking information. The first difference is that RESTful APIs specify this information in the X-EBAY-C-ENDUSERCTX request header and the legacy APIs use fields in the call's request body.

Next, there are differences in the names of the elements/fields and the requirements. The following table captures these differences.

Embedded in the ePN affiliate link	Required or Optional	RESTful APIs request header	Trading PlaceOffer call fields	Finding findItemsAdvanced call fields
campid	Required	affiliateCampaignId	AffiliateTrackingDetails.TrackingID plus AffiliateTrackingDetails.TrackingPartnerCode AffiliateTrackingDetails.ApplicationDeviceType	affiliate.trackingId plus affiliate.networkId
customid	Optional	affiliateReferenceId	AffiliateTrackingDetails.AffiliateUserID	affiliate.customId

For more information, see the eBay ePN Affiliate Tracking page.

Header for shipping information accuracy

Although the X-EBAY-C-ENDUSERCTX header containing contextualLocation is optional, it is strongly recommended that you use it when submitting Browse API methods. This header increases the accuracy of the estimated delivery window information and is needed for the calculated shipping information. When using this header, you must always include the country code and the zip code if zip codes are used in that country.

Shipping header example

X-EBAY-C-ENDUSERCTX: contextualLocation=country=US,zip=19406

X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406

eBay Partner Networks and Shipping header example

The following is an example if you need both contextualLocation and affiliate information. (This example has been broken into multiple lines for readability.)

X-EBAY-C-ENDUSERCTX: affiliateCampaignId=ePNCampaignId,affiliateReferenceId=referenceId,
contextualLocation=country%3DUS%2Czip%3D19406

Item ID legacy API compatibility overview

There are differences between how legacy APIs, such as Finding and Shopping, and the Buy RESTful APIs, such as Browse, return the identifier of an "item"and what the item ID represents.

What an item ID represents

The legacy APIs return listing IDs not item IDs. A listing can be for one specific item, that could have many in stock. Or the listing can be a group of the same item that has variations, such as a shirt that comes in several sizes and colors. The legacy APIs do not return the IDs of the individual items within a group, such as the red shirt size M and the red shirt size L. For each variation, the legacy APIs return the same ("parent") ItemID value, which represents the ID of a listing.

The RESTful APIs return either the ID of a group or the ID of a specific item, which can be a non-variation item or a specific item in an item group. These values are returned in the itemGroupId and itemId fields respectively.

Although the IDs returned by the legacy APIs cannot be used directly with the RESTful APIs, the following details how you can use a legacy item ID to obtain the RESTful item ID.

Shopping API item IDs

The Shopping API responses include the following fields and container. You use these to determine which Browse API getItemByLegacyId URI parameter to use to get the RESTful item ID.

• Variations container - This is returned when the ItemID is for a group of items.
• SKU - This is a free-form string created by the seller for a specific item in a group.
• ItemID - This is the ID of the listing, which can be for a specific item or a group of items.

If the Variations container is not returned.	This is a specific item that is not in a group. To get the RESTful item ID, pass in the legacy ItemID value in the legacy_item_id URI parameter of getItemByLegacyId. browse/v1/item/get_item_by_legacy_id?legacy_item_id=1**********9
If the Variations container is returned and the SKU field is returned.	This is a specific item within a group. To get the RESTful item ID of the item, pass in the legacy ItemID value in the legacy_item_id parameter and the SKU value in the legacy_variation_sku parameter of getItemByLegacyId. browse/v1/item/get_item_by_legacy_id?legacy_item_id=1**********9&legacy_variation_sku=V**********M

Finding API item IDs

The Finding API response includes the following fields. You use these fields to determine which Browse API method to use to get the RESTful item ID.

• isMultiVariationListing - This is a boolean value that indicates whether the listing is for a listing with multiple variations.
• itemId - This is the ID of the listing.

isMultiVariationListing = true	This indicates that the listing is for a group of items with variations, so the itemId value represents an item group. To get the IDs for each item in the group, pass in the itemId value using the getItemsByItemGroup method in the Browse API. browse/v1/item/get_items_by_item_group?item_group_id=2**********6
isMultiVariationListing = false	This indicates that the listing is for a specific item. To get the RESTful item ID, pass in the itemId value using the getItemByLegacyId method in the Browse API. browse/v1/item/get_item_by_legacy_id?legacy_item_id=2**********6