eBay Commerce Network Publisher API REST Option Reference – eBay合作伙伴API学习笔记

之前研究过一段时间的Amazon Advertise Product API,这次上手eBay不算困难。我为了不至于以后修改程序还需要翻看英文文档,特意翻译成中文的简短说明,OK,来看看中英文对照的API REST Option Reference文档吧。

1、apiKey

The key that uniquely identifies the publisher within the eBay Commerce Network, attained through the Publisher Account Center online application.

这段话意思是apiKey应该是publisher唯一的标识符,类似于AWS的Private Key。

2、trackingId

ECN generated ID used for revenue tracking at the campaign (placement) level. This ID will be provided through the Partner Account Center when you sign up for the API. Previously known as a R20;linkin ID”.

trackingId顾名思义,就是标记你是哪个publisher,当你请求eBay时候eBay可以找到你这个publisher验证并返回你需要的数据,并计算佣金。

3、subTrackingId

User generated ID used to further break down traffic sources beyond ECN campaign level tracking. You may choose any arbitrary character sequence (up to 36 characters), and use as many different IDs as required.�0�2 Please note that you must contact your account manager to have reporting enabled for this sub-tracking ID – otherwise the parameter will simply be ignored.

这个id是为了区别你的多个请求来源,需要人工启用该字段,请联系客户经理。

4、visitorUserAgent、visitorIPAddress

The IP address of the visitor to which this data is being presented.�0�2 Like visitorUserAgent, this data helps eBay Commerce Network to differentiate real users from web crawlers or robots.

这个字段主要是为了提供访问者的ip和请求者的ip是否一致,便于eBay判断是机器人访问,还是人类访问。

5、categoryId

Used to restrict query results to a given category. There are two classes of category: leaf-level categories contain products and offers, whereas parent-level categories contain only other categories. Searches on parent-level categories must be additionally constrained by at least one keyword.

用于将搜索的关键词限制于某个类别中,这里有两种返回类型:一种是返回包含产品、优惠信息的产品集合,另外一种是只返回该分类下属的子节点集合。

6、keyword

The simplest and most popular way to query eBay Commerce Network is to request results using keywords. Results can vary widely depending on the corresponding options and the keyword(s) used. For example, searching for a keyword like R20;Sony” may return items in many different categories while searching for R20;digital cameras” may return items from a single category (if skipping is enabled). Multiple keywords (and/or attribute values) may be submitted to further constrain the results.

这里的keywords可以放大为一个product detail产品详情页面中的任意一个元素,比如SIBN或者描述关键词、或者所属的分类名称。只要Detail页面中出现过,那么就可以使用。

7、minPrice、maxPrice、

Used to filter query results to only those items or offers which have prices above this minimum.

Used to filter query results to only those items or offers which have prices below this

对即将发送的查询请求加入价格区间限制。

8、attributeValue

Used to filter query results based on item properties. eBay Commerce Network API queries may return a list of attribute values, which can be used to filter a given list of items to a more manageable set. The resulting list can be further filtered by supplying additional attribute values. Searches by attribute value can be mixed with searches by keywords to help the user filter results to the desired item(s).

属性值集合,便于对返回的结果集进行进一步的筛选。比如:该字段返回brand、color、size相关参数集合,那么就可以按照Brand、或者color、或者size进行筛选。

9、showAllValuesForAttr

Request all values to be returned for a single attribute. Generally, a page will display a truncated list of values for the attributes being presented.�0�2 This is also useful when requesting attributes without values, as you need a way for the user to view the actual list of values should they want to filter results using that attribute.�0�2 Use this parameter to allow the user to select from among all possible values for an attribute (at least all values which are applicable to the result set.)

简而言之,提取出结果集中公有的属性集合。相当于对结果集中的每个元素进行取attributeValue,并返回attributeValue集合中的公有元素组成的新的集合。

10、productId

Searching by productId returns offers for a specific product. For a valid product ID, the API will return a single category, containing a single product, containing a list of offers.�0�2 Multiple productId parameters may be provided in a single request.

类似于ASIN,eBay中每一个商品条目都被标记唯一的productId

11、offerId

Searching by offerId returns a single offer matching the given ID. For a valid offer ID, the API will return a single category, containing a single offer.�0�2 Multiple offerId parameters may be provided in a single request, in which case, the returned category will be the lowest common ancestor of all offers returned.

It should also be noted that the eBay Commerce Network offer catalog is much more dynamic than the product catalog since it reflects available inventory, and as such, offer IDs will not be as stable as product IDs.�0�2 We suggest storing other relevant information along with the offer ID (e.g. product ID, category ID, attribute values, etc.) to allow displaying related results should an offer ID becomes invalid.

同个产品有多个价格,这个商品与每个价格组成一个OfferId,当一个请求中包含多个offerId时,以最低价格的为准,返回一个包含请求类别

12、groupItemsByCategory

Control whether or not items are separated into different categories. By default, searches don’t separate items by category. Instead, a single category (with id R20;0”) is returned containing items from different categories.

以分类方式分割不同的产品,当一个分类id是0,那么会返回其所有的产品(id为0是意思是所有分类也就是不限制分类)

13、numAttributes

The number of attributes to return in results which contain only one category. For any result composed of a single category containing a list of products or offers (not for the same product), the eBay Commerce Network API may provide attributes for filtering the results to more manageable sizes. By default, the API will return 0 attributes, which can be changed by using this parameter. However, any attributes above 5 will not include values unless you also set the numAttributesWithValues parameter. Note that attributes are never returned for offers under a single product, only for items at the category level.

返回一个集合中产品属性交集的元素个数

14、numAttributesWithValues

Control the number of attributes for which values will be returned. Requesting attributes without values (i.e.setting this parameter to a smaller value than numAttributes,) allows you to present the user with more filtering options while saving space on the page. By default, up to 5 attributes will include values.

设置属性默认显示的个数,比如

15、numValuesPerAttribute

Control the number of values to include with each attribute. Attribute values can be used to filter the list of items in a query result. By default, 5 values will be provided for each of the first 5 attributes returned.

设置过滤器中公有属性默认显示值得个数(比如设置nAWV为5那么 颜色显示:红白黄绿蓝 nAPV设置为1那么就是 颜色显示:红)

16、numCategories

When a search result contains multiple categories, the API will return up to 5 matching categories (within the relevance thresholds). If you would like more (or fewer) categories returned (still within the relevance thresholds), use the numCategories parameter. If, on the other hand, you would like to return all matching categories, regardless of relevance, use the showAllMatchingCategories parameter.

当你想限制返回集合中分类的个数,应该用numCategories限制返回分类个数,当需要返回所有的分类中的内容,应该使用showAllMatchingCategories 这个参数。

17、showAllMatchingCategories

Control whether or not this query will return all matching categories, regardless of relevance. When performing a keyword search, the eBay Commerce Network API will normally return 0 or more matching categories up to a relevance threshold. This means that even if the search engine finds 100 categories matching the keyword, it may only return a fraction of those if it determines that the remaining categories are outside of the relevance threshold. Setting the numCategories parameter to 100 will not change this behavior, as numCategories is overruled by relevance thresholds.

If you would like to see all matching categories (sorted alphabetically), regardless of relevance thresholds, use the showAllMatchingCategories parameter. Keep in mind, however, that due to the large number of categories normally returned, the API will not return items per category for this type of result. If, on the other hand, your keyword search has skipped to a single category, and you would simply like to see results from more than that one category (still subject to relevance thresholds), use the doSkipping parameter instead .

搜索时关键词相关度设置,0~100.

18、numItems

Control how many products and/or offers are returned within a category as well as the number of offers returned within a single product result. The only case where this parameter is not used is in the case where the showProductOffers option is being used to return offers for multiple products. In that case, the numOffersPerProduct parameter is the equivalent.

控制返回的产品数量

19、showProductOffers

Control whether or not offers are returned for each product in multi-product results. Normally when the API returns a product item, the offers for that product are not returned, unless the search engine has skipped to a single product. Instead, the API provides the product ID, which can be used to make a follow-up request for offers using a search by product ID query. If instead you would like offers included with every product returned, you can use the showProductOffers parameter.

如果showProductOffers选项为true,此参数控制搜索返回的结果包含多少个产品。

20、numOffersPerProduct

If the showProductOffers option is true, this parameter controls how many offers will be returned for each product when a search returns multiple products.

如果showProductOffers设置为true,那么这个参数可以控制显示不同型号的产品的数量。

21、showOffersOnly

Control whether search results should return only offers (i.e. no product information.) At the moment, showOffersOnly does not support searches across multiple categories, which means you can limit the search to offers only when searching by leaf-level category or product ID.

控制返回的结果是否只包含价格信息(不包含产品的其他信息)

22、showProductSpecs

Product specifications include data about products from the eBay Commerce Network catalog, including things such as MPN/UPC, weight, dimensions, or other features which may be unique to the specific product.�0�2 Generally, when products are returned in ECN API results, they only include a few details about the product itself, and then possibly a list of store offers.�0�2�0�2 This parameter will control the inclusion of complete specifications for the returned products in addition to any other information (offers, reviews) you have requested.

You can also do a side by side comparison of any number of products, simply by providing multiple productId parameters in the request, or by using this parameter along with a request which returns multiple products (generally, products should be from the same category, as a comparison of products from different categories would generally not be meaningful.)�0�2 Finally, if you only want product specifications, and don’t care about the store offers for those products, remember to set the parameter ‘showProductOffers’ to false (or set ‘numItems’ to 0 if making a single productId request.)

显示相同类别下几个产品的相同参数showProductOffers,可以进行同类产品的横向对比。

23、showProductReviews

Reviews are provided for many of the products in the eBay Commerce Network catalog courtesy of the Epinions community.�0�2 This parameter will allow you to retrieve product reviews with every product returned by the API (if available).�0�2 Each reviews section will contain the overall (average) rating, as well as a list of individual ratings, including the ‘pros’, ‘cons’, ‘bottom line’, and a short snippet of the full review text.�0�2 As with product specifications, if you only want product reviews, and don’t care about the store offers for those products, remember to set the parameter ‘showProductOffers’ to false (or set ‘numItems’ to 0 if making a single productId request.)

Any individual review displayed must include a link to the “full review” (which will be provided in the API response) as well as attribution to Epinions through the display of a logo and language that states R20;provided by Epinions”.�0�2 Also, the complete reviews information must be presented as it is returned by the API and cannot be altered.�0�2 Finally, reviews content must be enabled by your account manager, once you have reached traffic levels of 10,000 leads per month, and upon acceptance of an amendment to the original API agreement (which they will provide.)

可以提供一些产品的评论,但是只显示一部分,其他的内容将在后面跟上全部评论的链接。当该网站每个月能贡献10000次的访问量,那么将可以放放开这个限制。

24、numReviewsPerProduct

If the showProductReviews option is true, this parameter controls how many reviews will be returned for each product in the API results.

显示的评论数量

25、pageNumber

Set which page of results to return. When more results are available than are returned in a single query (indicated by a difference between the matchedCount and returnedCount) additional pages of results can be requested using the pageNumber parameter. Pagination currently only works for items returned by a leaf-level category search, a keyword search resulting in items across multiple categories, or the offers returned by a product ID search. You currently cannot paginate any results of a groupItemsByCategory=true keyword-only search, nor can you paginate the offers returned for each product when using the showProductOffers parameter.

在设置matchedCount和returnedCount这两个参数后,pageNumber将随之改变。但是请注意,这个参数不会对产品Offer产生影响(换而言之,这个只是对返回的产品集合中进行分页处理,不会对其他集合进行分页处理比如属性集合)

26、productReviewsPageNumber

Set which page of reviews to return for each product. When more reviews are available than are returned for a particular product, or list of products (indicated by a difference between the matchedReviewCount and returnedReviewCount) additional pages of reviews can be requested using the reviewsPageNumber parameter.�0�2 Generally, reviews pagination only makes sense in the context of a single product, as reviews will be paginated for all products present in the response (if applicable.)

在设置matchedReviewCount和returnedReviewCount这两个参数时,该字段才会显示作用。

27、doSkipping

Control whether or not the eBay Commerce Network search engine should R20;skip” directly to the most relevant category or product as a result of a keyword search, rather than providing a wider (but less relevant) selection of results across multiple categories. With skipping disabled, the set of categories returned by the API will still be limited to the most relevant. If instead, you would like to see all categories in which the keyword was found (not limited by relevance thresholds), use the showAllMatchingCategories parameter.

屏蔽包含某些关键词的产品,当需要显示所有产品的时候,需要使用showAllMatchingCategories这个参数。

28、postalCode

Set the postal code of the current user, for tax and shipping purposes. Tax and shipping costs will be provided along with each offer returned by the API (when available) if a valid postal code is included in the request. These costs will be added to the offer’s base price to calculate a total price, which is then used for sorting by price.

通过用户所在地区的邮政编码,提供运输到该地的运费以及运费与商品价格税费的综合价格,并按照合并后的价格排序。

29、itemsSortType

Set the method of sorting items at the category level . The API will return items ordered to maximize yield by default. If you would like to use a different method of ordering (e.g. the user requested to sort by price) for category level items, use the itemsSortType parameter to control the type of sorting, and the itemsSortOrder to control the direction of sorting. The available sort types are:

store-name – The name of the store providing this offer, sorted alphabetically.
store-rating – The average rating (between 0 and 5) of the store providing this offer, based on reviews by Epinions members.
product-rating – The average rating (between 0 and 5) of the product based on reviews by Epinions members.
price – The total price of the offer (base price if total price isn’t available.)
relevance – A score calculated by the eBay Commerce Network search engine to indicate how well the result relates to the search criteria, based on factors such as lexical relevance, user behavior, etc. The store’s bid is used in the case of a list of offers for a single product, since all offers are equally relevant.
yield – A calculation taking into account relevance, CPCs and other factors, in order to maximize the yield (or RPM) of a result.
Please note that some sort types may not be applicable in all results.�0�2 For instance, the ‘product-rating’ sort type would not apply to results containing only offers.�0�2 To address situations in which you need to request a default sort order without knowing the type of results which will be returned, you can chain multiple sort types together using a comma (e.g. itemsSortType=product-rating,store-rating), and the API will use the appropriate type.�0�2 There are separate sort type and sort order parameters for offers under products.

商品排序,通过store-name(商店title字母表顺序排序),sotre-rating(商店的评论评级),product-rating(产品的评论评级),price(价格排序),relevance(按照搜索引擎的相关度进行排序,包括用户行为在内的影响因子),yield(在契合产品的相关度下,尽可能提供高购买率的产品显示)

30、itemsSortOrder

Control whether results containing multiple items at the category level will be sorted in ascending or descending order.

该参数控制多个产品以产品类别的id进行排序。

31、productOffersSortType

Set the method of sorting offers at the product level . The API will return product offers ordered to maximize yield by default. If you would like to use a different type of ordering (e.g. the user requested to sort by price) for product offers, use the productOffersSortType parameter to control the method of sorting, and the productOffersSortOrder to control the direction of sorting. The available sort types are:

store-name – The name of the store providing this offer, sorted alphabetically.
store-rating – The average rating (between 0 and 5) of the store providing this offer, based on reviews by Epinions members.
price – The total price of the offer (base price if total price isn’t available.)
relevance – A score calculated by the eBay Commerce Network search engine to indicate how well the result relates to the search criteria, based on factors such as lexical relevance, user behavior, etc. The store’s bid is used in the case of a list of offers for a single product, since all offers are equally relevant.
yield – A calculation taking into account relevance, CPCs and other factors, in order to maximize the yield (or RPM) of a result.
There are separate sort type and sort order parameters for items at the category level.

与29同类,但默认提供的是收益最大化(利润率最高)的产品。

32、productOffersSortOrder

Control whether offers under products will be sorted in ascending or descending order.

通过价格升降序控制产品排列。

33、showSmartBuyOnly

The eBay Commerce Network Smart Buy is the lowest offer from a trusted store within the list of offers for any given product. By enabling the showSmartBuyOnly parameter, only the offer matching these criteria (if one exists) will be returned.

只通过eBay智能的返回商品列表,每件商品只返回一个eBay认为最合适的店铺的产品信息与价格。

34、showFeaturedOffersOnly

The eBay Commerce Network Featured Offers (or Featured Stores) are offers for which a store has paid for premium placement.�0�2 Use the showFeaturedOffersOnly parameter to request a list of featured offers in any search context.

只显示eBay特惠的产品或者是缴纳保证金的店铺的产品。

35、numFeatured

Set the maximum number of featured stores to include in a result, when using the showFeaturedOffersOnly parameter.By default, up to 3 featured stores will be included.

当使用showFeaturedOffersOnly参数后,该参数用来设置特色产品分类的个数。

36、productReviewsSortType

Control how to sort product reviews listings. The API will return product reviews ordered by review date by default.If you would like to use a different type of ordering (e.g. the user requested to sort by rating) for product reviews, use the productReviewsSortType parameter to control the type of sorting, and the productReviewsSortOrder to control the direction of sorting. The available sort types are:

review-date – The date (and time) the review was written.
product-rating – The authors overall rating (between 0 and 5) of the product.
productReviewsSortOrder

Control whether product reviews listings will be sorted in ascending or descending order.

可以按照评论时间、产品星级评分来升降序排列评论。默认是日期排列。

 

 

**********过期参数,不被生效与使用**********

Deprecated parameters
The following parameters have been deprecated with the migration to our new search engine.

offerSortType

offerSortOrder

productSortType

productSortOrder

hybridSortType

hybridSortOrder

The legacy sort parameters above have been replaced by the new itemsSortType, itemsSortOrder, productOffersSortType, and productOffersSortOrder.

showSmartBuy

Smart Buy offers are no longer included in normal search/browse results, and must now be requested independently with the showSmartBuyOnly parameter.

showSoftProducts

It is no longer possible to exclude soft products from API results.

showProductsWithoutOffers

It is currently not possible to include products without offers in search results.�0�2 However, it is still possible to request products without offers by ID.

doKeywordNormalization

This legacy parameter has been split into the new doSpellChecking and yet to be released doAndSearch parameters.

doSpellChecking

Control whether or not submitted keywords should be spell-checked by the search engine.�0�2 Enabled by default, and using is suggested, especially if you are passing user-entered keywords.

Option availability by search method
The eBay Commerce Network is trying to ensure every option is available in every use case it would makes sense. Some limitations, however, were not immediately addressable, and we are currently working hard to R20;plug these holes.” In the meantime, this chart shows which options are usable in offerId, productId, categoryId, and keyword searches.

eBay Commerce Network如果嫌弃慢的话,小生特意反代了一下源站,速度更快,点此查看