Marketplace API Filters

所有平台搜索共用的一套过滤器词汇——名称、单位，以及各平台分别接受哪些。

搜索在各处都以同样的方式收窄。一个概念一个名称、一个单位；平台要么支持某个过滤器，要么指名拒绝它。

所有过滤器都是可选的，而且过滤本身不额外收费——只有Amazon的 brands 与 facets 例外，它们计 2 个单位（见下）。

词汇

参数	类型	含义
`priceMin`	number	返回结果的最低价，以十进制主单位表示（`40`、`10.5`）
`priceMax`	number	返回结果的最高价，单位相同
`brands`	string list	按平台自己的写法给出的品牌名：`brands=Nike,Adidas`
`ratingMin`	number	最低平均星级，按平台的 0–5 分制
`condition`	enum	`new` · `used` · `refurbished`
`freeShipping`	boolean	只返回平台标注为包邮的商品
`inStock`	boolean	只返回平台声明当前可购买的商品
`sort`	enum	结果排序——见下
`categoryId`	string	平台自己的类目 id——见下
`facets`	list	取自结果自带筛选栏的收窄条件：`facets=Sock Rise:Ankle,Color:Black`

priceMin/priceMax 与响应所报的单位一致。Money.amount 是十进制主单位，所以 priceMin=40 与返回的 {"currency":"USD","amount":40} 指的是同一件事。需要最小单位的平台会在内部转换，你永远看不到分。

列表在查询字符串里用逗号分隔，在 JSON 请求体里则是真正的数组。两者是同一个请求：

?brands=Nike,Adidas          {"brands": ["Nike", "Adidas"]}

布尔值接受 true/false/1/0。freeShipping=false 的确表示 false。

各平台接受哪些

	amazon	shopify	walmart	aliexpress
`priceMin` / `priceMax`	✅	✅	✅	✅
`categoryId`	✅	✅	✅	✅
`sort`	✅	—	✅	✅
`brands`	✅ (计 2 个单位)	—	✅	—
`ratingMin`	⚠️ 仅 `4`	✅	✅	—
`condition`	—	⚠️ 无 `refurbished`	—	—
`inStock`	—	✅	—	—
`facets`	✅ (计 2 个单位)	—	✅	—

freeShipping 属于共用词汇，但目前提供服务的平台都不接受它。

破折号表示会返回一个指名该参数的 400，而不是悄无声息地忽略它。

这些空缺属于平台，而不属于我们。某个过滤器缺席，是因为平台本身没有：AliExpress的搜索没有评分筛选；Shopify 没有翻新这一档（所以 condition=refurbished 会被拒绝，而不是被并入 used——那是两个不同的断言），而且完全不提供排序。

Amazon的评分筛选栏只有一个阈值"4 Stars & Up"，因此只接受 ratingMin=4，其余一律 400——而不是对 ratingMin=3 的请求悄悄返回 4 星以上的结果。

`categoryId`

并不存在一套共用的类目体系，所以这个 id 是平台自己的：Amazon是 browse 节点（679416011），Walmart是 cat_id（4171），AliExpress是类目 id（200000345），Shopify 是 Standard Product Taxonomy id（aa-1-13-8）。

这些 id 从哪来。 问来就好：categories 会列出平台自有分类的某一层，而 browse 接受它返回的内容。不带 categoryId 调用即可拿到顶层并逐层下钻，或者从某个 Product.category[] 里的 id 出发。

各端点页面点明了两点注意事项：同一个 id 未必在每个操作上都能用（Walmart的 search 接受纯 cat_id，而它的 browse 需要 categories 返回的下划线链），并且少数层级只用于导航，会被标为 "browsable": false。

在 search 上，它收窄关键词查询而不是取代它，query 仍然是必填。

若要完全不带关键词地列出一个类目，请改用 browse 操作：那里 categoryId 是必填，而 query 会被拒绝。除 Shopify 外每个平台都有它，并且接受与 search 相同的过滤器。调用前值得知道它与 search 的两点不同：

id 可能是另一种东西。 Walmart的 browse 要的是下划线连接的链（3944_133251_1095191_1230614_1230478），而不是它 search 接受的纯 cat_id。
错误 id 不一定报错。 AliExpress返回空的 items——它不区分未知类目与空类目。

上面那些类型化过滤器是所有平台的公约数，它们只是站点实际提供内容的一小部分：在Walmart搜一次袜子会渲染出 25 个筛选分组，其中只有四个能对应到类型化参数。其余二十一个——Sock Rise、Sleeve Length、Fabric Material、 Weather Suitability——都是这次查询特有的。换成搜笔记本电脑，它们就变成了 Screen Size 与 RAM。

因为筛选栏是按查询变化的，所以它靠发现而非声明。搜索响应会把它带上：

{
  "items": [ "…" ],
  "facets": [
    { "id": "sock_rise", "name": "Sock Rise", "kind": "select",
      "values": [ { "value": "Ankle", "name": "Ankle", "count": 412 } ] },
    { "id": "brand", "name": "Brand", "kind": "select", "maps_to": "brands",
      "values": [ { "value": "Hanes", "name": "Hanes" } ] },
    { "id": "price", "name": "Price", "kind": "range", "maps_to": "priceMin", "min": 0, "max": 45 }
  ]
}

用 facets 把取值回传：

curl "https://gateway.apinoa.com/v1/walmart/search?query=socks&facets=sock_rise:Ankle,color:Black" \
  -H "x-api-key: $APINOA_API_KEY"

当存在对应关系时，maps_to 会指出覆盖同一概念的类型化过滤器。优先使用类型化参数——它在每个平台上含义相同，而 facets 并非如此。

哪些平台有筛选栏

	发现	应用	备注
walmart	✅	✅	两边都免费
amazon	✅ `include=facets`	✅	发现计 1 个单位，应用计 2 个——见下
shopify	`[]`	—	Shopify 搜索没有筛选栏
aliexpress	—	—	没有筛选栏

facets 缺失表示没有返回筛选栏；为空表示这次查询没有筛选栏。Shopify 返回 []。

Amazon：发现计 1 个单位，应用计 2 个

这是两件不同的事，只有其中一件额外收费。

include=facets 计 1 个单位——与不带它的搜索相同。

brands 与 facets 计 2 个单位。 cost.search 是 1..2。Amazon的其余一切仍是 1 个单位。

筛选栏里没有的标签会得到一个指名它的 400，并附上筛选栏实际提供了哪些取值的示例。Amazon会截断自己的筛选栏，因此一个匹配不上的标签是真正含糊的——返回未过滤的结果会掩盖这一点，什么都不返回则等于猜测。

排序

取值	含义	amazon	walmart	aliexpress
`best_match`	平台自己的相关度	✅	✅	—
`price_asc`	价格从低到高	✅	✅	✅
`price_desc`	价格从高到低	✅	✅	✅
`newly_listed`	最近上架优先	✅	✅	—
`best_seller`	按销量	—	✅	✅
`avg_review`	按平均评分	✅	—	—

这些名称是我们的，各平台自己的编码属于内部实现。平台做不到的取值会得到 400。

示例

# under $40, four stars and up
curl "https://gateway.apinoa.com/v1/amazon/search?query=running+shoes&priceMax=40&ratingMin=4" \
  -H "x-api-key: $APINOA_API_KEY"

# Nike only, rated 4+, cheapest first
curl "https://gateway.apinoa.com/v1/walmart/search?query=running+shoes&brands=Nike&ratingMin=4&sort=price_asc" \
  -H "x-api-key: $APINOA_API_KEY"

# in stock, $20-$60, rated 4+
curl "https://gateway.apinoa.com/v1/shopify/search?query=wool+socks&priceMin=20&priceMax=60&ratingMin=4&inStock=true" \
  -H "x-api-key: $APINOA_API_KEY"

一个需要知道的注意点

价格条件过滤的是商品条目，而有些条目带的是价格区间而不是单一价格。一个变体价格在 $28–$50 之间的商品，会因为它 $50 的变体而满足 priceMin=40 的请求，但它的卡片报出的是"起价" $28。

因此少数返回行可能落在你所要求的区间之外一点。实测 90–95% 落在区间内。如果你需要严格边界，请自行对返回的 price 再过滤一遍——平台就是这样运作的，而我们选择如实报告它们返回的内容，而不是把行藏起来。

Filters

词汇

各平台接受哪些

`categoryId`

facets——平台自己的筛选栏

哪些平台有筛选栏

Amazon：发现计 1 个单位，应用计 2 个

排序

示例

一个需要知道的注意点

本页内容