GET | POST /api/sellerfinder

Seller Finder（卖家筛选）：Product Finder 的卖家版——用同一套 _gte / _lte 筛选语法检索 Amazon 商家库，按评分/评分数、地址国家、FBA、店铺规模、经营类目/品牌、竞对关系等条件组合筛选，返回符合条件的卖家 ID 列表。

数据链路：Redis 缓存 → spider 通路（pro/sellerfinder WS，不消耗 API key 池，且额外返回 sellers 名称/评分摘要）→ API 兜底（此时 sellers 为 null，见响应）。拿到 ID 列表后，用 seller 接口分批（≤100）拉完整卖家对象。

接口

支持 GET / POST 两种形式（语义完全相同）：

POST https://mcp.keepamore.com/api/sellerfinder
Content-Type: application/json

GET  https://mcp.keepamore.com/api/sellerfinder?selection=<URL 编码的 sellerQuery JSON>&domain=1

POST 时 body 直接为 sellerQuery JSON（也可包一层 { "domain": 1, "sellerQuery": { ... } } / { "domain": 1, "selection": { ... } }，服务端自动拆包）；GET 时把 sellerQuery JSON 用 encodeURIComponent 编码后塞进 selection 参数，站点可用 domain / domainId / country query 参数指定

计费

项目	units
基础（每次成功调用）	10
结果集附加	每返回 100 个卖家 ID +1（向上取整）

例：一次返回 50 个 ID = 10 + 1 = 11 units；返回 250 个 = 10 + 3 = 13 units；匹配 0 个卖家也收基础 10 units。
预扣按 perPage 估算，实际返回更少时（如 totalResults < perPage）按实际返回数自动退差额。

selection（sellerQuery）字段

必填约束

名称	类型	说明
`domain`	integer	站点 ID，参见 domain 映射。也可用 `domainId` / `country` 别名
筛选条件	—	至少一个（`page` / `perPage` / `sort` / `minMatch` 不算），否则报 400 `the query has no filter criteria.`

所有筛选条件之间为 AND；数组类筛选内部为 OR（数组最多 50 项，- 前缀表示排除，如 ["cn","hk","-de"]）；字符串筛选全部不区分大小写。

分页与排序

名称	类型	默认	说明
`perPage`	integer	`50`	每页卖家数，限制 50–10000，且 `(page+1)*perPage ≤ 10000`
`page`	integer	`0`	0-indexed 页码；分页时上游不缓存首查结果，两次请求间隔过久页间顺序可能不一致
`sort`	array[][]	—	最多 3 个排序键，如 `[["currentRatingCount","desc"]]`；默认按 `currentRatingCount` 降序（大卖家优先）；无法识别的排序字段不报错，整个 `sort` 被忽略退回默认排序

检索与身份

字段	类型	说明
`search`	string	单词条全文检索：跨卖家名 / 商号 / 地址 / ID 等字段；单词越多越窄，超 300 字符截断
`sellerId`	string[]	精确匹配卖家 ID
`sellerName`	string	卖家名（精确小写匹配）
`businessName`	string	商业名称
`isAmazon`	boolean	是否 Amazon 自营
`activeOnly`	boolean	仅近 31 天内有在架行为的活跃卖家（服务端动态口径，等价 `lastSeenOffer_gte` 截止值）

评分与反馈（时间窗 30/90/365/Lifetime）

字段	说明
`currentRating_gte` / `_lte`	当前好评率（0–100）
`currentRatingCount_gte` / `_lte`	累计评分数
`ratingCount30/90/365/Lifetime_gte` / `_lte`	时段评分数
`positiveRating` / `neutralRating` / `negativeRating*`	同时段好评 / 中评 / 差评数
`ratingCountDelta30/90/365_gte` / `_lte`	时段评分数净变化
`lastRatingUpdate_gte` / `_lte`	最近评分更新时间（KeepaTime 分钟）
`lastFeedbackDate_gte` / `_lte`	最近反馈日期（KeepaTime 分钟）

经营画像（类目 / 品牌 / 竞对）

字段	说明
`rootCategories_include/exclude`	经营根类目 ID 数组（追踪其销量 Top 10 品类）
`brands` / `primaryBrand`	经营品牌数组 / 主品牌
`competitorSellerIds`	给定卖家的竞对（目录重叠度最高的商家）——竞品调研利器
`topCompetitorSellerId`	指定"最重竞对"的卖家
`totalStorefrontAsins_gte` / `_lte`	店铺在架 SKU 规模
`hasFBA`	是否有 FBA 行为
`addressCountry`	地址国家代码数组，如 `["cn","hk"]`
`hasBusinessDetails`	是否有可解析的工商信息块（Amazon 卖家档案页）
`businessType` / `vatID` / `tradeNumber`	工商类型 / VAT 号 / 营业执照号
`trackedSince_gte` / `_lte`	数据源开始追踪时间（KeepaTime 分钟）

日期类字段（lastRatingUpdate / lastFeedbackDate / lastSeenOffer / lastSeenFbaOffer / trackedSince）均为 KeepaTime 分钟——误传 Unix 秒/毫秒会被服务端拦截报错（换算见 KeepaTime）。

minMatch（K-of-N 匹配）

数组筛选默认 OR（命中任一即可）。minMatch 把门槛提高到"至少 K 项同时命中"：

json

{ "brands": ["anker", "spigen", "baseus"], "minMatch": { "brands": 2 } }

响应

json

{
	"code": "0000",
	"msg": "ok",
	"data": {
		"sellerIdList": ["A2VT4H683M5NNA", "A11HC9SRN13WHM", "A2PKN2PT2YIWJF"],
		"totalResults": 23614,
		"totalResultsCapped": false,
		"sellers": [
			{
				"sellerId": "A2VT4H683M5NNA",
				"name": "ThriftBooks-Chicago",
				"rating": 90,
				"ratingCount": 1053184
			},
			{
				"sellerId": "A11HC9SRN13WHM",
				"name": "BookOutlet USA",
				"rating": 92,
				"ratingCount": 641773
			}
		],
		"fromCache": false
	},
	"metadata": { "...": "计费 / 耗时元信息" }
}

字段	说明
`sellerIdList`	官方 API 兼容字段：按 `sort` 排序的卖家 ID 列表（当前页），分批（≤100）喂给 `seller` 拉完整对象
`totalResults`	官方 API 兼容字段：全量匹配数（跨页）
`totalResultsCapped`	总数是否被上游封顶（spider 通路独有；`true` 时 `totalResults` 为封顶值而非精确值）
`sellers`	增值字段：与 `sellerIdList` 顺序对齐的名称/评分摘要（spider 通路附带、零额外计费）；API 兜底路径为 `null`——需要时用 `seller/name` 批量补
`fromCache`	是否命中缓存（缓存 5 分钟）

示例

找美国站地址在中国大陆/香港、累计评分 ≥ 1000、近 31 天活跃的卖家，按评分数降序取前 100：

cURL (POST)cURL (GET)JavaScriptPython

bash

# 请将 km_xxx 替换为你的 API Key
curl -X POST "https://mcp.keepamore.com/api/sellerfinder" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: km_xxx" \
  -d '{
    "domain": 1,
    "addressCountry": ["cn", "hk"],
    "currentRatingCount_gte": 1000,
    "activeOnly": true,
    "sort": [["currentRatingCount", "desc"]],
    "perPage": 100,
    "page": 0
  }'

bash

# 请将 km_xxx 替换为你的 API Key
# selection 必须 URL 编码（这里用 jq 演示）
SEL=$(printf '%s' '{"addressCountry":["cn","hk"],"currentRatingCount_gte":1000,"activeOnly":true,"perPage":50}' | jq -sRr @uri)
curl "https://mcp.keepamore.com/api/sellerfinder?domain=1&selection=$SEL" \
  -H "X-API-Key: km_xxx"

// 请将 km_xxx 替换为你的 API Key
const selection = {
	addressCountry: ["cn", "hk"],
	currentRatingCount_gte: 1000,
	activeOnly: true,
	sort: [["currentRatingCount", "desc"]],
	perPage: 100,
	page: 0,
};
const resp = await fetch("https://mcp.keepamore.com/api/sellerfinder", {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"X-API-Key": "km_xxx",
	},
	body: JSON.stringify({ domain: 1, ...selection }),
});
console.log(await resp.json());

python

# 请将 km_xxx 替换为你的 API Key
import requests

selection = {
    "addressCountry": ["cn", "hk"],
    "currentRatingCount_gte": 1000,
    "activeOnly": True,
    "sort": [["currentRatingCount", "desc"]],
    "perPage": 100,
    "page": 0,
}
resp = requests.post("https://mcp.keepamore.com/api/sellerfinder",
                     headers={"X-API-Key": "km_xxx"},
                     json={"domain": 1, **selection}, timeout=180)
print(resp.json())

典型配方

场景	关键字段
中国卖家调研	`addressCountry=["cn"]` + `currentRatingCount_gte=1000` + `activeOnly=true`
某卖家的竞对	`competitorSellerIds=["A2L77EE7U53NWQ"]` + `activeOnly=true` + `sort=[["totalStorefrontAsins","desc"]]`
高分大店	`currentRating_gte=95` + `totalStorefrontAsins_gte=5000`
FBA 品牌卖家	`hasFBA=true` + `brands=["anker","spigen"]` + `minMatch={"brands":1}`
按名字找卖家	`search="thriftbooks"`（官网搜索同款单词条检索）
某类目卖家	`rootCategories_include=[<catId>]` + `activeOnly=true`

常见错误

code	场景
`4000`	缺 `domain` / JSON 非法 / GET 缺 `selection` / 无筛选条件 / `perPage` 超范围 / 日期字段误传 Unix 时间戳
`QUOTA_*`	额度 / 限速不足

和 MCP 的对应

MCP：kmore_seller_finder

GET | POST /api/sellerfinder ​

接口 ​

计费 ​

selection（sellerQuery）字段 ​

必填约束 ​

分页与排序 ​

检索与身份 ​

评分与反馈（时间窗 30/90/365/Lifetime） ​

经营画像（类目 / 品牌 / 竞对） ​

minMatch（K-of-N 匹配） ​

响应 ​

示例 ​

典型配方 ​

常见错误 ​

和 MCP 的对应 ​