Browse API

The Browse API provides the ability to:

  • 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 you 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.
    • Experimental Release (Experimental) Provides the ability for eBay members to see the contents of their eBay cart, and add, remove, and change the quantity of items in their eBay cart. Note: This resource is not available in the eBay API Explorer.
  • Experimental Release (Experimental) search_by_image - Lets shoppers basic information 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 a product is compatible with the specified item, such as if a specific car is compatible with a specific part.
    • Provides a bridge between the RESTful Buy APIs and the legacy APIs, such as Finding.
  • Experimental Release (Experimental) shopping_cart - Provides the ability for eBay members to see the contents of their eBay cart, add, remove, or change the quantity of items in their eBay cart.

The Browse API has the item_summary, search_by_image, item, and shopping_cart resources. The use cases 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.

Important! Query parameters need to be URL encoded. For readability, the call examples in this document are not encoded. For more information about encoding, see URL encoding query parameter values.

Search for items

You can search for items by keyword, image ID (a Base64 string), eBay category ID, 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. Note: The categoryId is required twice when using aspect_filter; once as a query parameter and as part of the aspect_filter. You can use the dominant category (category most of the items are in), which is returned with the aspects or the Commerce Taxonomy API to determine the category ID. See Get Categories for Buy APIs for details.

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

       Image of a Carmera Brand Histogram

When a shopper clicks on one of the refinements, such as "Canon", you use the search call 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. 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.

Note: The only products supported are cars, trucks, and motorcycles.

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

Note: Don't forget you must encode the filter values as shown below.

https://api.ebay.com/buy/browse/v1/item_summary/search?search?q=brakes&category_ids=33559&compatibility_filter=Year%3A2012%3BMake%3AHonda%3BModel%3ACivic%3BTrim%3AEX%20Sedan%204-Door%3BEngine%3A1.8L%201799CC%20l4%20GAS%20SOHC%20Naturally%20Aspirated

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 call is successful, the response will return the compatibilityStatus, which tells you if the item is compatible with the product.

Important! The only products supported are cars, trucks, and motorcycles.

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

Product attributes that define cars, trucks, and motorcycles (US Marketplace)

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 Samplesof the call reference page.

Access an eBay cart

You can use the methods in the shopping_cart resource to let eBay members add items to, remove items from, and change the quantity of an item in their eBay cart. It also lets you retrieve all the items in the eBay member's cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. When the shopper is ready to purchase the items, the checkout is done on the eBay site using their PayPal account.

You will use a User access token and get permission from the eBay member to act on their behalf, which allows you to make changes to their cart on eBay. You can use the Trading API method GetUser to retrieve the eBay member's information, which you can use to send them email describing the change and send them a link to their eBay cart. The link to the cart is returned by the getShoppingCart call in the cartWebUrl field.

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.

ePN affiliate link example
https://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=5337984774&customid=Q4-76d54tr&toolid=10050
&mpre=https%3A%2F%2Fwww.latest.ebay.com%2Fitm%2FNew-Mens-zipper-Hooded-Windbreaker-
%2F182382849018%3Fvar%3D484950112932%26src%3Durllib

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

 

RESTful APIs
request header

Trading
PlaceOffer call fields

Finding
findItemsAdvanced call fields

campid Required affiliateCampaignIdAffiliateTrackingDetails.TrackingID
plus
AffiliateTrackingDetails.TrackingPartnerCode
AffiliateTrackingDetails.ApplicationDeviceType
affiliate.trackingId
plus
affiliate.networkId
customidOptional affiliateReferenceIdAffiliateTrackingDetails.AffiliateUserIDaffiliate.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

Important! Because the contextualLocation has multiple name value pairs, these need to be encoded. For more information, see URL encoding query parameter values.

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 AP getItemByLegacyId URI parameter to use to get the RESTful item ID.

  • Variations container - 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, for example V-00031-WHM
  • 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=110039490209
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=110039490209&legacy_variation_sku=V-00031-WHM

 

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 an boolean value that indicates whether the listing is for a listing with multiple variations.
  • itemId - This is the ID of the listing, for example 262446562346.
isMultiVariationListing = true This indicates this listing is 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=262446562346
isMultiVariationListing = false This indicates this 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=262446562346