ASPECT_REFINEMENTS
or FULL
. Silver
, Brushed Nickel
, Pewter
, or even Grey
. The returned refinement container identifies all aspects that have been used in past listings for products that match your search criteria, along with all of the values those aspects have taken, and the number of times each value was used. You can use this data to present the seller with a histogram of the values of each aspect. The seller can see which color values have been used in the past, and how frequently they have been used, and selects the most likely value or values for their product. You issue the search call again with those values in the aspect_filter parameter to narrow down the collection of products returned by the call. (space)
= %20
,
= %2C
:
= %3A
[
= %5B
]
= %5D
{
= %7B
|
= %7C
}
= %7D
Parameter | Type | Description |
---|---|---|
offset | string | This parameter is reserved for internal or future use. Occurrence: Optional |
limit | string | The number of product summaries to return. This is the result set, a subset of the full collection of products that match the search or filter criteria of this call. Maximum: 200 Default: 50 Occurrence: Optional |
fieldgroups | array of string | The type of information to return in the response. Important: This parameter may not produce valid results if you also provide more than one value for the category_ids parameter. It is recommended that you avoid using this combination. Valid Values:
Default: MATCHING_PRODUCTS Occurrence: Optional |
aspect_filter | AspectFilter | An eBay category and one or more aspects of that category, with the values that can be used to narrow down the collection of products returned by this call. Aspects are product attributes that can represent different types of information for different products. Every product has aspects, but different products have different sets of aspects. You can determine appropriate values for the aspects by first submitting this call without this parameter. It will return either the productSummaries.aspects container, the refinement.aspectDistributions container, or both, depending on the value of the fieldgroups parameter in the request. The productSummaries.aspects container provides the category aspects and their values that are associated with each returned product. The refinement.aspectDistributions container provides information about the distribution of values of the set of category aspects associated with the specified categories. In both cases sellers can select from among the returned aspects to use with this parameter. Note: You can also use the Taxonomy API's getItemAspectsForCategory call to retrieve detailed information about aspects and their values that are appropriate for your selected category. The syntax for the aspect_filter parameter is as follows (on several lines for readability; categoryId is required): aspect_filter=categoryId:category_id, A matching product must be within the specified category, and it must have least one of the values identified for every specified aspect. Note: Aspect names and values are case sensitive. Here is an example of an aspect_filter parameter in which 9355 is the category ID, Color is an aspect of that category, and Black and White are possible values of that aspect (on several lines for readability): GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? Here is the aspect_filter with required URL encoding and a second aspect (on several lines for readability): GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? Note: You cannot use the aspect_filter parameter in the same call with either the gtin parameter or the mpn parameter. Occurrence: Optional |
category_ids | array of string | Important: Currently, only the first category_id value is accepted. One or more comma-separated category identifiers for narrowing down the collection of products returned by this call. Note: This parameter requires a valid category ID value. You can use the Taxonomy API's getCategorySuggestions call to retrieve appropriate category IDs for your product based on keywords. The syntax for this parameter is as follows: category_ids=category_id1,category_id2,... Here is an example of a call with the category_ids parameter: GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? Note: Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. If you provide only the category_ids parameter, you cannot specify a top-level (L1) category. Occurrence: Optional |
mpn | array of string | A string consisting of one or more comma-separated Manufacturer Part Numbers (MPNs) that identify products to search for. This call will return all products that have one of the specified MPNs. MPNs are defined by manufacturers for their own products, and are therefore certain to be unique only within a given brand. However, many MPNs do turn out to be globally unique. Note: Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. You cannot use the mpn parameter in the same call with either the q parameter or the aspect_filter parameter. Occurrence: Optional |
gtin | array of string | A string consisting of one or more comma-separated Global Trade Item Numbers (GTINs) that identify products to search for. Currently the GTIN values can include EAN, ISBN, and UPC identifier types. Note: Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. You cannot use the gtin parameter in the same call with either the q parameter or the aspect_filter parameter. Occurrence: Optional |
q | string | A string consisting of one or more keywords to use to search for products in the eBay catalog. Note: This call searches the following product record fields: title, description, brand, and aspects.localizedName, which do not include product IDs. Wildcard characters (e.g. * ) are not allowed. The keywords are handled as follows:
You cannot use the q parameter in the same call with either the gtin parameter or the mpn parameter. Occurrence: Optional |
This call also uses the X-EBAY-C-MARKETPLACE-ID
header to identify the user's business context. This header is currently limited to EBAY-US
, EBAY-AU
, EBAY-CA
, and EBAY-GB
values. If not included with your request, the marketplace value defaults to EBAY-US
. Note that it does not indicate a language preference or end-user location.
Examples:X-EBAY-C-MARKETPLACE-ID: EBAY-US
X-EBAY-C-MARKETPLACE-ID: EBAY-AU
This request requires an access token created with the authorization code grant flow, using one scope from the following list:
https://api.ebay.com/oauth/api_scope/sell.inventory
https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly
See OAuth access tokens for more information.
Note: Only the sell.inventory
scope is required for selling applications, and only the commerce.catalog.readonly
scope is required for buying applications.
Output container/field | Type | Description |
---|---|---|
href | string | This field is reserved for internal or future use. Occurrence: NA |
limit | integer | The number of product summaries returned in the response. This is the result set, a subset of the full collection of products that match the search or filter criteria of this call. If the limit query parameter was included in the request, this field will have the same value. Default: 50 Occurrence: Always |
next | string | This field is reserved for internal or future use. Occurrence: NA |
offset | integer | This field is reserved for internal or future use. Occurrence: NA |
prev | string | This field is reserved for internal or future use. Occurrence: NA |
productSummaries | array of ProductSummary | Returned if the fieldGroups query parameter was omitted from the request, or if it was included with a value of MATCHING_PRODUCTS or FULL . This container provides an array of product summaries in the current result set for products that match the combination of the q, category_ids, and aspect_filter parameters that were provided in the request. Each product summary includes information about the product's identifiers, product images, aspects, the product page URL, and the getProduct URL for retrieving the product details. Occurrence: Conditional |
productSummaries.additionalImages | array of Image | Contains information about additional images associated with this product. For the primary image, see the image container. Occurrence: Conditional |
productSummaries.additionalImages.height | integer | The height of the image in pixels. Occurrence: Conditional |
productSummaries.additionalImages.imageUrl | string | The eBay Picture Services (EPS) URL of the image. Occurrence: Always |
productSummaries.additionalImages.width | integer | The width of the image in pixels. Occurrence: Conditional |
productSummaries.aspects | array of Aspect | Contains an array of the category aspects and their values that are associated with this product. Occurrence: Conditional |
productSummaries.aspects.localizedName | string | The localized name of this category aspect. Occurrence: Conditional |
productSummaries.aspects.localizedValues | array of string | A list of the localized values of this category aspect. Occurrence: Conditional |
productSummaries.brand | string | The manufacturer's brand name for this product. Occurrence: Conditional |
productSummaries.ean | array of string | A list of all European Article Numbers (EANs) that identify this product. Occurrence: Conditional |
productSummaries.epid | string | The eBay product ID of this product. Occurrence: Always |
productSummaries.gtin | array of string | A list of all GTINs that identify this product. This includes all of the values returned in the ean, isbn, and upc fields. Occurrence: Conditional |
productSummaries.image | Image | Contains information about the primary image of this product. For more images of this product, see the additionalImages container. Occurrence: Always |
productSummaries.image.height | integer | The height of the image in pixels. Occurrence: Conditional |
productSummaries.image.imageUrl | string | The eBay Picture Services (EPS) URL of the image. Occurrence: Always |
productSummaries.image.width | integer | The width of the image in pixels. Occurrence: Conditional |
productSummaries.isbn | array of string | A list of all International Standard Book Numbers (ISBNs) that identify this product. Occurrence: Conditional |
productSummaries.mpn | array of string | A list of all Manufacturer Product Number (MPN) values that the manufacturer uses to identify this product. Occurrence: Conditional |
productSummaries.productHref | string | The URI of the getProduct call request that retrieves this product's details. Occurrence: Always |
productSummaries.productWebUrl | string | The URL for this product's eBay product page. Occurrence: Conditional |
productSummaries.title | string | The title of this product on eBay. Occurrence: Always |
productSummaries.upc | array of string | A list of Universal Product Codes (UPCs) that identify this product. Occurrence: Conditional |
refinement | Refinement | Returned only if the fieldGroups query parameter was included in the request with a value of ASPECT_REFINEMENTS or FULL . An aspect is a property of a category, used by sellers to provide details about the items they're listing. For example, the Cell Phones & Smartphones category (#9355) includes a Storage Capacity aspect. This container provides information about the distribution of values of a set of category aspects. The category aspects are those associated with the category that eBay determines is most likely to cover the products that match the search criteria. Occurrence: Conditional |
refinement.aspectDistributions | array of AspectDistribution | Contains information about one or more aspects that are associated with the category identified by dominantCategoryId. Occurrence: Conditional |
refinement.aspectDistributions.aspectValueDistributions | array of AspectValueDistribution | Contains information about one or more values of the category aspect identified by localizedAspectName. Occurrence: Conditional |
refinement.aspectDistributions.aspectValueDistributions.localizedAspectValue | string | The localized value of the category aspect identified by refinement.aspectDistributions.localizedAspectName. Occurrence: Conditional |
refinement.aspectDistributions.aspectValueDistributions.matchCount | integer | The number of times the value of localizedAspectValue has been used for eBay product listings. By comparing this quantity to the matchCount for other values of the same aspect, you can present a histogram of the values to sellers, who can use that information to select which aspect value is most appropriate for their product. You can then include the user-selected value in the the search call's aspect_filter parameter to refine your search. Occurrence: Conditional |
refinement.aspectDistributions.aspectValueDistributions.refinementHref | string | A HATEOAS reference that further refines the search with this particular localizedAspectValue. Occurrence: Conditional |
refinement.aspectDistributions.localizedAspectName | string | The localized name of an aspect that is associated with the category identified by dominantCategoryId. Occurrence: Conditional |
refinement.dominantCategoryId | string | The ID of the category that eBay determines is most likely to cover the products matching the search criteria. Occurrence: Conditional |
total | integer | This field is reserved for internal or future use. Occurrence: NA |
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 | Success |
204 | No Content |
400 | Bad Request |
403 | Forbidden |
500 | Internal Server Error |
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
75000 | API_CATALOG | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
75001 | API_CATALOG | REQUEST | The call must have a valid 'q', or 'category_ids' or 'gtin' or 'mpn' query parameter. |
75004 | API_CATALOG | REQUEST | The 'limit' value should be between 1 and 200 (inclusive). |
75006 | API_CATALOG | REQUEST | Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. |
75007 | API_CATALOG | REQUEST | Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} . |
75008 | API_CATALOG | REQUEST | The 'fieldgroups' value {fieldgroups} is invalid. The supported fieldgroups are: {supportedFieldgroups} |
75012 | API_CATALOG | REQUEST | The aspect_filter format is invalid. For more information, see the API call reference documentation. |
75013 | API_CATALOG | REQUEST | The 'aspect_filter' query parameter must include a categoryId. For more information, see the API call reference documentation. |
75014 | API_CATALOG | REQUEST | The categoryId in 'aspect_filter' query parameter is invalid. For more information, see the API call reference documentation. |
75015 | API_CATALOG | REQUEST | Insufficient permissions to fulfill the request. |
75017 | API_CATALOG | REQUEST | The specified GTIN value is invalid. |
75018 | API_CATALOG | REQUEST | The call must be made with either 'q' or 'gtin/mpn'. |
75019 | API_CATALOG | REQUEST | The call with 'gtin/mpn' cannot be made with aspect_filter. |
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.
Cell Phones & Smartphones
category.
iphone
keyword. Based on the results of that search, it returns the aspect refinements for the dominant category (Cell Phones & Smartphones
) of products that contain the keyword.
iphone
keyword, and filters the results for the Color
aspect value of Black
.
0813917020203
. Based on the results of that search, it returns all product summaries of the product identified by the provided GTIN.
3710RW
. Based on the results of that search, it returns all product summaries of the product identified by the provided MPN.