browse APIv1_beta.10.0

Browse API Release Notes

Just getting started with the Browse API? See the following documents for details on using this API:

See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.

The API release history

The following table lists recent Browse API releases. For older releases, see the Browse API Release Notes Archive.

Release Version

Release Date

Description of Release

v1_beta.10

2017-11-010

The getItem and getLegacyItem calls

  • Added the value PRODUCT to the fieldgroups URI parameter
  • Added product type

All Browse API calls

  • Added unitPrice and unitPricingMeasure fields

v1_beta.9.0

2017-10-23

Added adultOnly field to the Browse API call responses

Added categoryId field to the getItem and getItemByLegacyId call responses

v1_beta.8.0

2017-09-21

  • Added fieldgroups URI parameter to the getItem call
  • Added new sellerItemRevision field to the getItem call
  • Added new error message to the search call

v1_beta.7.0

2017-06-07

search call

  • Added gtin URI parameter
  • Removed the gtin field filter (backwards incompatible change)
  • Added error messages

v1_beta.6.0

2017-05-25

  • getItem, getItemsByItemGroup, and getItemByLegacyId calls

    • Added fields to the response
    • Added support for legacy SKU
  • search call
    • Added fieldgroup and aspect_filter URI parameters
    • Added refinement response containers
    • Added filters
    • Added constraint information: maximum number of items returned is 10,000
  • Remove Get Item Feed call from Browse API. This functionality was moved to the Feed API.
  • Added support for additional eBay marketplaces
  • Added Taxonomy API information to the documentation, which retrieves category Ids

 

v1_beta.10

You can now use the getItem and getLegacyItem calls to retrieve product details for an item. The product information is returned in the new product type fields. This type is included in the response when the fieldgroups URI parameter is set to PRODUCT. You can also retrieve the price per unit, which helps buyers accurately compare prices.

Added the PRODUCT fieldgroups value

When you set the URI parameter fieldgroups to PRODUCT, it adds fields to the response containing information about the product associated with the item.

Added Product type

The product type has been added to the getItem and getLegacyItem calls. This type is returned only if the URI parameter fieldgroups is set to PRODUCT. The following table lists the fields or types returned in the product type. See the getItem call for details about these new types and fields. For an example of the response, see Get item details and the item product information sample.

product Type Field/Types

Description

product.additionalImages An array of containers with the URLs for the product images that are in addition to the primary image.
product.additionalProductIdentities A product can have more than one identifier value for a product type, such as UPC, EAN, ect. For example, the same product UPC can have an identifier that is 12, 13, or 14 digits.

This container returns an array of all the product identifiers (type/value pairs) associated with the product. These are in addition to the identifiers returned in the mpn and gitn fields.
product.aspectGroups An array of containers for the product aspects. Each group contains the aspect group name and the aspect name/value pairs.
product.brand The brand associated with the product. To identify the product, this is always used along with MPN (manufacturer part number).
product.description The rich description of an eBay product, which might contain HTML.
product.gtins An array of all the possible GTINs values associated with the product. A GTIN is a unique Global Trade Item number of the item. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.
product.image The primary image of the product. This is often a stock photo.
product.mpns An array of all possible MPN values associated with the product. A MPNs is manufacturer part number of the product. To identify the product, this is always used along with brand.
product.title The title of the product.

 

Added unitPrice and unitPricingMeasure fields

The unitPrice and unitPricingMeasure fields were added to all the Browse APIs calls.

New Field

Field Description

unitPrice This is the price per unit for the item. The European Union requires listings for certain types of products to include the price per unit so buyers can accurately compare prices.
unitPricingMeasure The designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item.

 

v1_beta.9.0

The following fields were added to the Browse API call responses.

New Field

Call

Field Description

adultOnly All Browse API calls 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 Searching for adult only items for buyers.
categroyId getItem and getItemByLegacyId calls The Id of the category for the item.

 

v1_beta.8.0

The following changes were made to the Browse API.

Added fieldgroups URI parameter to the getItem call

The fieldgroups URI parameter was added to the getItem call to enable you to control what is returned in the response. The Buy APIs are designed to let you create an eBay shopping experience in your app or website. This means you will need to know when item details, such as the price, availability, etc., has changed in any eBay item you are offering. You can now do this easily by setting fieldgroups to COMPACT, which reduces the response to only the fields that you need in order to check if any item detail has changed. For more information, see fieldgroups.

Add sellerItemRevision field to the getItem call

The sellerItemRevision field is n identifier generated/incremented when a seller revises the item. There are two types of item revisions; seller changes, such as changing the title, and eBay system changes, such as changing the quantity when an item is purchased. This Id is changed only when the seller makes a change to the item. This means you cannot use this value to determine if the quantity has changed.

New error message

The following error message was added to the search call.

Error Id

Error Description

12023 This keyword search results in a response that is too large to return. Either change the keyword or add additional query parameters and/or filters.

Announcement - June 2017

Availability of OpenAPI Specification

This release of the Browse API includes Beta version downloadable JSON and YAML formats of the API contract that comply with version 2.0 of the OpenAPI Specification. The OpenAPI Specification is a widely adopted standard for describing RESTful APIs. The eBay API specification files can facilitate your development process through the ability to generate client code in numerous languages, using the Swagger-Codegen tools, as well as the ability to easily view and test the API via the Swagger UI projects. Development of the OpenAPI Specification is overseen by the Open API Initiative, an open source collaborative project of the Linux Foundation.

Note: If you want to use the Swagger editing tool for viewing and testing, we advise you use the version of the editor that is compatible with 2.0 OpenAPI specifications: https://editor2.swagger.io/

Read the eBay API documentation for comprehensive API details, including allowed values, constraints, method-specific error messages, and implementation details.

File download     Download Browse API JSON specification (beta)

File download     Download Browse API YAML specification (beta)

v1_beta.7.0

The following changes were made to the search call.

Added gtin URI parameter

Added a gtin URI parameter, which lets you search by GTIN (other Global Trade Item Number) or UPC (Universal Product Code) value. It can be used alone or with the other query parameters; category_ids, epid, or q.

For example:

/buy/browse/v1/item_summary/search?gtin:{099482432621}

Removed gtin field filter

The gtin field filter was removed. Note: This is a backwards incompatible change.

&filter=gtin:099482432621

Added new error messages

The following error messages were added.

Error Id

Error Description

12019 Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .
12020 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'.
12021 The 'epid' value {value} is invalid. For information, see the API call reference documentation.
12022 The 'gtin' value {value} is invalid. For information, see the API call reference documentation.

v1_beta.6.0

The following changes have been made in this release.

getItem, getItemsByItemGroup, and getItemByLegacyId call changes

The following response fields were added.

New Field/Container Name

Description

conditionId The identifier of the condition. For example, 1000 is the identifier for NEW.
epid An identifier of a product in the eBay product (epid) catalog. This indicates the product in which the item belongs.
productFicheWebUrl The URL to a page containing the manufacture's specification of an item, which helps buyers make a purchasing decision. This information is available for items that include the European energy efficiency rating (EEK) but is not available for all items with an EEK rating. This field is returned only if this information is available. The EEK rating of the item is returned in the energyEfficiencyClass field.
seller.sellerLegalInfo.email The seller's email address.
seller.sellerLegalInfo.fax The seller's fax number.
seller.sellerLegalInfo.imprint This is a free-form string created by the seller. This is information often found on business cards, such as address. This is information used by some countries.
seller.sellerLegalInfo.legalContactFirstName The seller's first name.
seller.sellerLegalInfo.legalContactLastName The seller's last name.
seller.sellerLegalInfo.name The name of the seller's business.
seller.sellerLegalInfo.phone The seller's phone number.
seller.sellerLegalInfo.registrationNumber The seller trade registration number.
seller.sellerLegalInfo.sellerProvidedLegalAddress The container for the seller's address to be used to contact them.
seller.sellerLegalInfo.termsOfService This is a free-form string created by the seller. This is the seller's terms or condition, which is in addition to the seller's return policies.
seller.sellerLegalInfo.vatDetails.issuingCountry The seller's VAT (value added tax) country code. VAT is a tax added by some European countries.
seller.sellerLegalInfo.vaDetails.vatId The seller's VAT (value added tax) Id. VAT is a tax added by some European countries.
taxes.includedInPrice Indicates if tax was applied for the cost of the item.
taxes.shippingAndHandlingTaxed Indicates if tax is applied for the shipping cost.
taxes.taxJurisdiction.region The region of the tax jurisdiction.
taxes.taxJurisdiction.region.regionName A free-form string that indicates the name of the region. This value can be the name of a world region (such as the "Middle East" or "Southeast Asia"), a country, or a domestic region within a country (such as "Alaska/Hawaii" or "US Protectorates") depending on the value of regionType. This value should be WORLDWIDE if the regionType value is WORLDWIDE.
taxes.taxJurisdiction.region.regionType Indicates the type of region. Valid values: COUNTRY, COUNTRY_REGION, STATE_OR_PROVINCE, WORLD_REGION, and WORLDWIDE
taxes.taxJurisdiction.taxJurisdictionId The identifier of the tax jurisdiction.
taxes.taxPercentage The percentage of tax.
taxes.taxType Container that returns the tax type. Valid values: PROVINCE_SALES_TAX, REGION, STATE_SALES_TAX, and VAT

 

Added support for legacy SKU

The following is an example of using the value of the ItemID and SKU fields, which were returned by the Trading API, to get the RESTful itemId value.

browse/v1/item/get_item_by_legacy_id?legacy_item_id=110039490209&legacy_variation_sku=V-00031-WHM

The following section describes the changes that were made to the Search for Items call.

search call changes

The following section describes the changes that were made to the search call.

Added fieldgroups and aspect_filter URI parameters

The following URI parameters were added to the search call.

New URI Parameters

Description

fieldgroups

This controls what is returned in the response. The default is MATCHING_ITEMS, which returns the items that match the keyword or category specified.

The ASPECT_REFINEMENTS, BUYING_OPTION_REFINEMENTS, CATEGORY_REFINEMENTS, and CONDITION_REFINEMENTS values return all the aspects, buying options, categorys, and conditions metadata of the items along with the number of items in each. This data that can be used to create histograms.

You can also use include refinements and MATCHING_ITEMS to return both the metadata and items.

For complete details, see fieldgroups in the Browse Call Reference.

aspect_filter

This is an optional field that lets you limit the response to a category, which is required, and name/value aspect pairs. For example, in a clothing category one aspect pair would be Color/Red.

 

For example, the call below uses the category Id for Women's Clothing. This will return only items for a woman's red shirt.

/buy/browse/v1/item_summary/search?q=shirt&aspect_filter=categoryId:15724,Color:{Red}

 

To get a list of the aspects pairs and the category, which is returned in the dominantCategoryId field, set fieldgroups to ASPECT_REFINEMENTS.

/buy/browse/v1/item_summary/search?q=shirt&fieldgroups=ASPECT_REFINEMENTS

epid

The EPID is the eBay product identifier of a product from the eBay product catalog. Only items in the specified EPID are returned. The getItem, getItemByLegacyId, and getItemsByItemGroup calls return the EPID of the item.

       /buy/browse/v1/item_summary/search?filter=epid:{15032}

Maximum: 1

Required: The call must have catedgory_ids, epid, or q (or any combination of these)

Added fields to the response

The following fields and containers were added to the search call response.

New Fields

Description

Example

dominantCategoryId

The identifier of the category that has the most items.

"dominantCategoryId": "20863",

itemSummaries.
   conditionId

The identifier of the condition of the item.

"conditionId": "1000",

itemSummaries.
  epid

An identifier of a product in the eBay product (EPID) catalog. This indicates the product in which the item belongs.

"epid": "691335615",
refinement.
   aspectDistributions

This container returns name/values pair of the various aspects, the number of items matching this aspect, and the HATEOAS reference for the aspect. It also returns the dominantCategoryId field.

This container is returned when you set fieldgroups to ASPECT_REFINEMENTS or FULL in the request.

"dominantCategoryId": "20863",
"aspectDistributions": [
  {
    "localizedAspectName": "Brand",
    "aspectValueDistributions": [
      {
        "localizedAspectValue": "adidas",
        "matchCount": 187,
        "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search?q=world+cup+soccer+ball&limit=50&aspect_filter=categoryId%3A20863,Brand%3A%7Badidas%7D"
      },
      {
        "localizedAspectValue": "Nike",
        "matchCount": 7,
        "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball&limit=50 &aspect_filter=categoryId%3A20863,Brand%3A%7BNike%7D"
      },
refinement.
   buyingOptionDistributions
This container returns the buying option type, the number of items matching this option, and the HATEOAS reference for the option. Only AUCTION and FIXED_PRICE options are supported.

 

This container is returned when you set fieldgroups to BUYING_OPTION_REFINEMENTS or FULL in the request.

"buyingOptionDistributions": [
  {
    "buyingOption": "AUCTION",
    "matchCount": 41,
    "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball &limit=50&filter=buyingOptions%3A%7BAUCTION%7D"
  },
refinement.
   categoryDistributions

This container returns the category name and Id, and the number of items in this category, and the HATEOAS reference for the option.

 

This container is returned when you set fieldgroups to CATEGORY_REFINEMENTS or FULL in the request.

"categoryDistributions": [
  {
    "categoryName": "Clothing, Shoes & Accessories",
    "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball&limit=50 &category_ids=11450",
    "categoryId": "11450",
    "matchCount": 10856
  },
refinement.
   conditionDistributions
This container returns the condition name and Id, the number of items with this condition, the HATEOAS reference for the condition. Only NEW, USED, and UNSPECIFIED are returned.

 

This container is returned when you set fieldgroups to CONDITION_REFINEMENTS or FULL in the request.

"conditionDistributions": [
  {
    "condition": "NEW",
    "conditionId": "1000",
    "matchCount": 12281,
    "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball &limit=50&filter=conditions%3A%7BNEW%7D"
  },

 

Added new filters

The following filters were added the search calls.

Filter Name

Syntax

Description

conditionIds filter=conditionIds:{1000|1500} Only items with the specified condition Id are returned. For more information on item conditions for some popular eBay categories, see the Item Condition Ids and Names. Multiple values can be used for this filter and are separated by the pipe symbol - '|'.
itemStartDate filter=itemStartDate:[2016-11-14T07:47:48Z.. 2016-12-14T07:47:48Z] Only items scheduled to start within the specified date-time range are returned. The first date-time value is the start of the range and the second date-time value is the end of the range. The start and end range value are separated by two dots ('..').
maxDeliveryCost filter=maxDeliveryCost:0 Only items with free shipping are returned. Note: The only value supported is zero.
paymentMethods filter=paymentMethods:{CREDIT_CARD} Only items that offer payment by credit card are returned. Currently, only CREDIT_CARD is supported.

 

Added constraint information

Search can return a maximum of 10,000 items.

Removed Get Item Feed call from Browse API

The Get Item Feed call has been removed from the Browse API. This capability will be available in the new Feed API soon.

Added support for additional eBay marketplaces

The Browse API is now available on the following eBay marketplaces.

  • EBAY-AU - Australia (ebay.com/au)
  • EBAY-CA - Canada (English) (ebay.ca)
  • EBAY-DE - Germany (ebay.de)
  • EBAY-ES - Spain (ebay.es)
  • EBAY-FR - France (ebay.fr)
  • EBAY-IT - Italy (ebay.it)
  • EBAY-UK - Great Britain (ebay.co.uk)
  • EBAY-US - USA (ebay.com)

 

Added Taxonomy API information

The new Taxonomy API can be used to find categories you want to browse or search. It provides calls that enable the you to browse or search the category tree hierarchy. See the Getting categories for Buy APIs.