browse APIv1_beta.21.0

Browse API Overview

Topics

Technical overview

Using the Browse API, you can create a rich selection of items for your buyers to browse with keyword and category searches. You can also provides the ability to eBay members to add items and change the quantity of an item in their eBay shopping cart as well as view the contents of their eBay cart.

Browse API resources

The Browse API has the following resources:

  • item_summary:
    • Search for items. You can search by keyword, image ID (a Base64 string), category, product, GTIN, or charity ID.
    • Filter the result by fields values, item aspects, and compatibility.
  • 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 the details of a specific item.
    • Retrieve the details of all the individual items in an item group (variations). An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.
    • Check if a product is compatible with the specified item, such as if a specific car is compatible with a specific part.
    • Retrieve the RESTful API item ID using a legacy API item ID.
  • 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.

Business use cases

The Browse API is designed to be used together with the Buy APIs to create cohesive shopping, browsing, buying applications. For example, your buyers can have a seamless buying experience woven into a social application. This section outlines the high-level use cases for the Browse API. For details, see the Integration Guide.

Find eBay items using search

You can find exactly the items you want to show to your shoppers by searching for items by keyword, category, eBay product ID (EPID), GTIN, or image, and charity ID. You can also search for compatible item or check compatibility of an item

Refine the search results

You can control what is returned by the search using the fieldgroups field. By default, search returns matching items. But in addition to or instead of returning items, you can choose to return the aspects (all the variations of an item such and color and size), buying options (fixed or auction), conditions, and categories of the items found. These are known as refinements. This information enables you to create histograms, which enables shoppers to drill down in each refinement narrowing the search results.

Filter the search results by item aspects

You can use the information returned in aspectDistributions to filter the results by specific aspects (aspect_filter), such as brand. You can also filter the results by items that are compatible with a specific product (compatibility_filter).

Filter the search results by field values

You can use field filters to refine the results based on the value returned in a field, such as listing format, item condition, price range, UPC value, listing end date, location, and more. You can use multiple filters in a single method. For details about, see Buy API Field Filters.

Get the details of each item in a group or a specific item

When the item has variations, you can retrieve the details of the individual items in an item group. You can also retrieve the details of a specific item.

Get item details using a legacy item ID or SKU

You can use the item IDs returned by eBay legacy APIs, such as Shopping and Finding, to retrieve the details of the item and the RESTful item ID, which you can use with all the Buy API methods.

Add/change/remove/view items in an eBay cart

You can use the shopping_cart methods to add items to, remove items from, and change the quantity of an item an eBay member's cart on eBay. You can also retrieve all the items in the eBay member's cart. When the eBay member is ready to purchase the items, they go to the eBay site. To use this resource, 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.

API restrictions

Please note the following constraints for the Browse API.

Identifier incompatibility

The Buy APIs identifiers for item and order do not match the identifiers used on the eBay site and in buyer emails. So you cannot use the Buy APIs identifiers with any of the eBay legacy APIs, such as Finding. But you can use the eBay legacy item identifiers in the Browse API getItemByLegacyId method to retrieve items. For details, see the Legacy API compatibility in the Buying Integration Guide.

Regional/site constraints

For a list of the supported eBay sites for all the Buy APIs, see Buy API Support by Marketplace.

To specify the site, set the X-EBAY-C-MARKETPLACE-ID request header to the site. For example:

X-EBAY-C-MARKETPLACE-ID = EBAY_GB

getItem method restriction

This method will return FIXED_PRICE (Buy It Now) items and AUCTION items where no bids have been placed. But after a bid has been placed, that item becomes an active auction item and is no longer returned.

Search method restrictions

The following restrictions apply to the search and searchByImage methods.

  • Only FIXED_PRICE (Buy It Now) items are returned. However, these methods do return items where both FIXED_PRICE and AUCTION are available as a buying option. But after a bid has been placed, that item becomes an active auction item and is no longer returned.

  • The search methods can return a maximum of 10,000 items in a result set. A result set is the complete set of items returned by a method.
  • You cannot use a wildcard (*) in search method requests. For example, the following is not allowed:

       /buy/browse/v1/item_summary/search?q=*phones

shopping_cart resource restrictions

The following lists the restrictions that apply to the shopping_cart resource:

  • The end user must have an eBay account.

  • To be added to an eBay cart, the item must be a fixed price (no auctions) item that accepts PayPal payments.

  • An eBay member can have multiple carts but only one cart per site per member. Once a cart is created, is does not expire but it can be deleted.

eBay policies and rules

Although the eBay Buy APIs are available for anyone to use in eBay's sandbox environment, use of the APIs in production is restricted. Users must meet standard eligibility requirements, get approvals from eBay support organizations, and sign contracts with eBay and PayPal to access the Buy APIs in production.

See Production eligibility requirements in the Buying Integration Guide for more information.

Rate limits

The Browse API limits the number of calls that can be made per day on behalf of your application. For the current application rate limits, see the eBay API Call Limits page.