GET /api/topseller

获取某站点 Most Rated Sellers（评价数最多的卖家）排行榜，支持历史日期与全字段详情。数据来自我们的每日全量快照（每天北京时间 02:00 同步），快照不可用时自动回退实时接口。

接口

GET https://mcp.keepamore.com/api/topseller

计费

响应形态	units / 次
只返回卖家 ID 列表（默认）	20
detail=1（含全字段详情）	50

计费按响应形态计，与数据来源（快照 / 实时）无关。

参数（Query String）

名称	类型	必填	默认	约束	说明
domain	integer	✅	—	1–12	站点 ID，参见 domain 映射。也可用 domainId / country 别名
date	string		—	日期格式	快照日期 YYYY-MM-DD：查该日的榜单。不传 = 最新快照日期（每天 02:00 后为当天）。历史自 2026-06 起、每站点 Top 10 万名内。带此参数时仅查快照，无该日期则报错（实时接口没有历史）
detail	boolean		false	—	true 返回全字段详情（45 列：评分分布/BuyBox/类目品牌统计/竞争对手等，仅快照链路支持）。detail 模式 perPage 上限 1000，不传分页参数时默认返回第 0 页 1000 条
page	integer		—	≥ 0	分页页码（0-indexed）；不传则返回全部（detail 模式除外）
perPage	integer		—	1–10000	每页数量（detail 模式 1–1000）；不传则返回全部（detail 模式除外）

与 bestseller / seller 一致：page / perPage 都不传时返回全量；任一传入才启用服务端分页。detail=1 例外——始终分页（默认第 0 页 1000 条），全量详情请翻页拉取。

响应

默认（ID 列表）：

{
	"code": "0000",
	"msg": "ok",
	"data": {
		"sellerIdList": ["A1PA6795UKMFR9", "ATVPDKIKX0DER", "..."],
		"_pagination": {
			"page": 0,
			"perPage": 100,
			"total": 10000,
			"totalPages": 100
		},
		"_snapshot": { "date": "2026-10-03", "source": "snapshot" },
		"fromCache": false
	}
}

• _snapshot.source = "snapshot"：来自每日快照；快照整体不可用回退实时时无 _snapshot 字段
• 不启用分页时无 _pagination 字段

detail=1（全字段详情）：增加 sellers 数组（与当页 sellerIdList 同序），每行 45 列快照字段（snake_case），字段清单见 MCP 工具文档的 detail 字段表——评分分布（30/90/365 天 count+好评/中评/差评）、BuyBox 占有率、类目/品牌完整统计、竞争对手（competitors_json）、主营类目品牌等；JSON 列已解析为对象。

历史覆盖范围

• 时间：2026-06 起至今（每天一份全量，北京时间 02:00 后可查当天）
• 范围：每站点 Top 100,000 名内卖家
• 指定日期无快照时报错并列出该站点可用日期范围

示例

cURL

# 请将 km_xxx 替换为你的 API Key
# 1) 最新榜单前 100 名（最常用，20 units）
curl "https://mcp.keepamore.com/api/topseller?domain=1&page=0&perPage=100" \
  -H "X-API-Key: km_xxx"

# 2) 查 2026-09-01 的历史榜单（20 units）
curl "https://mcp.keepamore.com/api/topseller?domain=1&date=2026-09-01&page=0&perPage=100" \
  -H "X-API-Key: km_xxx"

# 3) 前 50 名全字段详情（50 units）
curl "https://mcp.keepamore.com/api/topseller?domain=1&detail=1&page=0&perPage=50" \
  -H "X-API-Key: km_xxx"

JavaScript

// 请将 km_xxx 替换为你的 API Key
const URL = "https://mcp.keepamore.com/api/topseller";
const HEADERS = { "X-API-Key": "km_xxx" };

// 1) 最新榜单前 100 名
const r1 = await fetch(`${URL}?domain=1&page=0&perPage=100`, {
  headers: HEADERS,
});
console.log(await r1.json());

// 2) 历史榜单 + 详情一步到位
const r2 = await fetch(
  `${URL}?domain=1&date=2026-09-01&detail=1&page=0&perPage=50`,
  { headers: HEADERS },
);
console.log(await r2.json());

Python

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

URL = "https://mcp.keepamore.com/api/topseller"
HEADERS = {"X-API-Key": "km_xxx"}

# 1) 最新榜单前 100 名
r1 = requests.get(URL, params={"domain": 1, "page": 0, "perPage": 100},
                  headers=HEADERS, timeout=180)
print(r1.json())

# 2) 历史榜单（2026-09-01）
r2 = requests.get(URL, params={"domain": 1, "date": "2026-09-01",
                               "page": 0, "perPage": 100},
                  headers=HEADERS, timeout=180)
print(r2.json())

PHP

<?php
// 请将 km_xxx 替换为你的 API Key
require 'vendor/autoload.php';
use GuzzleHttp\Client;

$client = new Client();
$resp = $client->get('https://mcp.keepamore.com/api/topseller', [
    'headers' => ['X-API-Key' => 'km_xxx'],
    'query'   => ['domain' => 1, 'page' => 0, 'perPage' => 100],
    'timeout' => 180,
]);
echo $resp->getBody();

Java

// 请将 km_xxx 替换为你的 API Key（Java 11+ 标准库）
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://mcp.keepamore.com/api/topseller?domain=1&page=0&perPage=100"))
    .header("X-API-Key", "km_xxx")
    .timeout(Duration.ofSeconds(180))
    .GET()
    .build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

Go

// 请将 km_xxx 替换为你的 API Key（Go 标准库 net/http）
package main

import (
    "fmt"
    "io"
    "net/http"
    "time"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://mcp.keepamore.com/api/topseller?domain=1&page=0&perPage=100", nil)
    req.Header.Set("X-API-Key", "km_xxx")

    client := &http.Client{Timeout: 180 * time.Second}
    resp, err := client.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

典型工作流

1. topseller 拉卖家 ID 列表（20 units，快照零延迟；历史加 date）
2. 需要详情时：detail=1 一步拿全字段（50 units），或 seller 批量查实时数据（每 ID 1 unit）、seller + date 查任意日期的卖家档案
3. 对重点卖家单独 storefront=1 拉店铺 ASIN（10 units / 个，实时链路）

和 MCP 的对应

• MCP：kmore_get_top_sellers