keepa_product_finder

按几百个字段组合筛选 Amazon 产品，选品场景的主力工具。对应 Keepa /query 接口。

用途

• 按价格区间、排名区间、品牌、分类、评分、评论数、月销量、销量变化、历史低价等条件精准筛选 ASIN
• 返回满足条件的 asinList 和 totalResultCount，拿到 ASIN 后再用 keepa_get_product 拉详情

参数

名称	类型	必填	默认	约束	说明
domain	integer		—	1–14	Keepa domain ID（与 country 二选一，与官方参数名一致）
country	enum		—	—	Amazon 站点代码（与 domain 二选一）
selection	object	✅	—	任意 Keepa 筛选字段 JSON	筛选条件，所有字段可选；详见下方常用字段表
page	integer		0	≥ 0	0-indexed 页码
perPage	integer		50	1–10000	每页条目数（Keepa 最大 10000）

selection 常用字段

Keepa Product Finder 支持数百个字段，以下为高频子集。所有筛选 / 排序字段的取值含义、单位（cents / KeepaTime / 评分 ×10 等）实质上是 Product Object 字段及其 csv Price Type 索引 的别名，详见对应字段速查；完整字段列表见 Keepa 官方文档。

价格区间（单位：分）

字段	含义
current_AMAZON_gte / _lte	当前 Amazon 价格
current_BUY_BOX_SHIPPING_gte / _lte	当前 Buy Box 含运费价
current_NEW_gte / _lte	当前 New 最低价
current_USED_gte / _lte	当前 Used 最低价

排名与销量

字段	含义
current_SALES_gte / _lte	当前 Sales Rank
avg30_SALES_gte / _lte	30 天平均排名
monthlySold_gte / _lte	月销量
salesRankDrops30_gte / _lte	30 天排名下降次数

分类与品牌

字段	含义
categories_include	分类 ID 数组（必包含其中任一）
categories_exclude	分类 ID 数组（排除）
rootCategory	根分类 ID 数组
brand	品牌数组
productType	产品类型数组

评分与评论

字段	含义
current_RATING_gte / _lte	评分 × 10，如 45 = 4.5 星
current_COUNT_REVIEWS_gte / _lte	评论数
hasReviews	是否有评论

价格变动 / 历史低价

字段	含义
deltaPercent30_BUY_BOX_SHIPPING_gte / _lte	30 天价格变化百分比
isLowest_BUY_BOX_SHIPPING	是否历史最低

标题与排序

字段	含义
title	标题关键词
sort	排序数组，如 [["current_SALES","asc"]]

计费

项目	units
基础（每次成功调用）	1
selection.stats=1（额外返回 searchInsights 聚合 KPI）	+30

例：仅查 ASIN 列表 = 1 unit；同时要 searchInsights = 1 + 30 = 31 units。结果数量（perPage）不影响计费。

使用示例

找美国站小家电、Buy Box 价 10–50 美元、评分 ≥ 4 星、月销 ≥ 100、排名上升中的产品，按销量升序前 100 条：

{
	"domain": 1,
	"page": 0,
	"perPage": 100,
	"selection": {
		"rootCategory": [284507],
		"current_BUY_BOX_SHIPPING_gte": 1000,
		"current_BUY_BOX_SHIPPING_lte": 5000,
		"current_RATING_gte": 40,
		"monthlySold_gte": 100,
		"salesRankDrops30_gte": 5,
		"sort": [["current_SALES", "asc"]]
	}
}

返回结构

{
	"code": "0000",
	"data": {
		"asinList": ["B0...", "B0..."],
		"totalResultCount": 12345,
		"searchInsights": null,
		"fromCache": false
	}
}

拿到 asinList 后，传给 keepa_get_product 拉详情即可（建议 detailLevel: "summary" 减少响应体）。返回的产品字段定义详见 Product Object 字段速查。

selection 不带 stats 时 searchInsights 固定为 null；带 "stats": 1 时返回完整的 Search Insights Object（命中 ASIN 的聚合 KPI），同时按 +30 units 计费（见上文计费表）。

完整字段参考

所有 selection 字段（价格类型、时间窗口、属性筛选、boolean 标记等）的逐项详解见：

• Product Finder 完整字段参考（含全部 selection 参数、取值、互斥规则）

和 HTTP API 的对应

• HTTP：GET | POST /api/keepa/productfinder