aba_get_rank_list

查询 ABA 周榜单关键词排名。数据来源：Amazon Brand Analytics 关键词周榜。

用途

• 查看某个站点某一周的关键词排名榜单（Top N）
• 按品牌、类目、排名变化类型、点击/转化量等维度筛选
• 发现新上榜的关键词（fluctuationType: "new"）
• 监控竞品品牌的排名变化（brand 筛选）
• 发现高点击低转化 / 高转化低点击的机会词（clickSumMin / convSumMin）

参数

名称	类型	必填	默认	约束	说明
country	enum	✅	—	—	Amazon 站点代码（ABA 支持 9 个站点）
reportDate	string		—	YYYY-MM-DD	报告日期。不传则使用最新一期数据。可用日期通过 aba_get_countries 查看
rankMin	integer		—	≥ 1	最低排名（含）
rankMax	integer		—	≥ 1	最高排名（含）
keyword	string		—	—	关键词模糊筛选（英文匹配 word，中文匹配 word_cn）
fluctuationType	enum		—	—	排名变化类型：new=新上榜, rising=上升, falling=下降, stable=稳定
brand	string		—	—	品牌精确筛选（JSON_CONTAINS 匹配）
category	string		—	—	类目精确筛选（JSON_CONTAINS 匹配）
clickSumMin	integer		—	≥ 0	最低点击量
convSumMin	integer		—	≥ 0	最低转化量
limit	integer		200	1–1000	返回条数
offset	integer		—	≥ 0	分页偏移量。与 afterRank 互斥，传了 offset 则忽略 afterRank
afterRank	integer		—	≥ 0	keyset 分页：传入上一页最后一行的 new_rank，获取下一页。仅在未传 offset 时生效

分页说明：offset 和 afterRank 二选一。keyset 分页（afterRank）利用聚簇索引，大翻页时性能远优于 offset。推荐 Keyset 分页用法：第一次不带分页参数，拿到结果后用最后一行的 new_rank 作为下轮 afterRank。

计费

• ceil(limit / 1000) units。默认 200 条 = 1 unit，上限 1000 条时仍为 1 unit。

使用示例

获取美国站最新一期前 20 名关键词：

{ "country": "us", "limit": 20 }

发现美国站新上榜关键词（前 100 名内）：

{ "country": "us", "rankMax": 100, "fluctuationType": "new", "limit": 50 }

查找 Anker 品牌在德国站前 500 名的关键词：

{ "country": "de", "brand": "Anker", "rankMax": 500, "limit": 100 }

Keyset 翻页（获取下一页）：

{ "country": "us", "limit": 50, "afterRank": 50 }

返回结构

{
  "success": true,
  "data": {
    "country": "us",
    "reportDate": "2026-05-11",
    "rows": [
      {
        "word_id": "1234567890123456789",
        "word": "bluetooth speaker",
        "word_cn": "蓝牙音箱",
        "new_rank": 1,
        "old_rank": 2,
        "fluctuation": 1,
        "click_sum": 150000,
        "conv_sum": 12000,
        "brands": ["Anker", "JBL"],
        "categories": ["Electronics", "Portable Speakers"]
      }
    ],
    "hasMore": true,
    "nextAfterRank": 50,
    "total": 150000,
    "amazonTld": "com"
  }
}

字段	说明
word_id	关键词唯一 ID（xxHash64，可用于 [aba_get_word_detail]）
word	关键词原文
word_cn	中文翻译（可能为 null）
new_rank	本期排名
old_rank	上期排名（新词时为 null）
fluctuation	排名变化量（正值=上升，负值=下降，null=无上期数据）
click_sum	该词此周总点击量
conv_sum	该词此周总转化量
brands	关联品牌列表（JSON 数组）
categories	关联类目列表（JSON 数组）
hasMore	是否还有更多数据
nextAfterRank	下一页的 afterRank 值（hasMore=true 时有值）
total	符合条件的总行数

相关工具

• aba_get_countries —— 查看可用站点和日期
• aba_get_word_detail —— 查看某个关键词的详细信息和历史趋势
• aba_search_keywords —— 按关键词全文搜索

和 HTTP API 的对应

• HTTP：GET /api/aba/rank