linkfox-keepa-product-detail

Keepa 产品数据请求

此技能将指导你如何通过 Keepa 产品请求 API 获取 Amazon 商品详情，帮助 Amazon 卖家和分析师获取一个或多个 ASIN 在多个 Amazon 站点的结构化商品数据。

核心概念

Keepa 产品请求 API 会返回 Amazon 商品详情数据，数据来源于 Keepa。提供一个或多个 ASIN 和一个站点后，API 会返回全面的商品信息：价格、标题、主图、上架日期、材质、重量、尺寸、销售排名、月销量（当前值和最多 12 个月的历史数据）、FBA 费用、评分、评论数、分类树等。

要点：

• 在单次请求中，使用逗号分隔 ASIN，最多可查询 100 个 ASIN。
• domain 参数是数字形式的站点 ID（例如，1 = Amazon.com 美国站），而不是国家代码。
• 将 history 设为 1 可包含历史销售数据（月销量最多可追溯 12 个月、30/90/180 天的平均销售排名）。设为 0 则只返回当前商品信息。
• 响应不包含商品描述或评论内容。

参数指南

domain（必填）

数字形式的 Amazon 站点 ID。对应关系如下：

站点 ID	站点
1	Amazon.com（美国）
2	Amazon.co.uk（英国）
3	Amazon.de（德国）
4	Amazon.fr（法国）
5	Amazon.co.jp（日本）
6	Amazon.ca（加拿大）
8	Amazon.it（意大利）
9	Amazon.es（西班牙）
10	Amazon.in（印度）
11	Amazon.com.mx（墨西哥）
12	Amazon.com.br（巴西）

如果用户未指定站点，默认使用 1（美国）。

asin（必填）

一个或多个 Amazon 标准识别号。多个 ASIN 之间用逗号分隔。每次请求最多包含 100 个 ASIN，字符串总长度上限为 3000 个字符。

history（可选）

是否包含历史数据，例如过去 12 个月的月销量以及 30/90/180 天的平均销售排名。设为 1 可包含历史数据；设为 0（默认值）则仅返回基本信息。

使用示例

1. 查询单个 ASIN（美国站点，基本信息）

{"asin": "B0088PUEPK", "domain": "1"}

2. 查询单个 ASIN 及其历史销售数据

{"asin": "B0088PUEPK", "domain": "1", "history": 1}

3. 批量查询多个 ASIN（德国）

{"asin": "B0088PUEPK,B00U26V4VQ,B07M68S376", "domain": "3", "history": 1}

4. 查询 Amazon 日本站商品

{"asin": "B09V3KXJPB", "domain": "5", "history": 0}

5. 对比多个 ASIN 的竞品（美国，含销售历史）

{"asin": "B0CXYZ1234,B0CXYZ5678,B0CXYZ9012,B0CXYZABCD", "domain": "1", "history": 1}

API 使用方法

此工具会调用 LinkFox 工具网关 API。有关调用约定、请求参数和响应结构，请参阅 references/api.md。你也可以直接运行 scripts/keepa_product_detail.py 执行查询。

显示规则

1. 清晰呈现数据：使用结构清晰的表格展示商品详情。将相关字段分组（例如，将尺寸放在一起、销售数据放在一起），以便阅读。
2. 价格和货币：始终同时显示价格和货币（例如，“$29.99 USD”）。响应中的 currency 字段表示当地货币。
3. 销售趋势：包含历史数据时，使用表格展示 12 个月的销售趋势，或描述其走势（增长、下降、稳定），帮助用户快速评估销售势头。
4. 尺寸和重量：适当将毫米值换算为更直观的单位（例如，同时显示毫米和英寸，或毫米和厘米）。请注意，重量单位为克。
5. 数据不可用：值为 0 或 -1 的字段表示数据不可用。不要将其作为实际测量值显示；请改为注明“N/A”或省略。
6. 图片显示：如果存在 imageUrl，请显示商品图片，帮助用户直观识别商品。
7. 错误处理：查询失败时，根据响应说明问题并建议修正方式（例如，ASIN 格式无效或站点不受支持）。
8. 大量批量查询结果：对于包含多个 ASIN 的批量查询，先展示汇总表，并提供按需展示单个商品详情的选项。

重要限制

• 不提供商品描述或评论：API 不会返回商品描述文本或评论内容。
• 每次请求最多 100 个 ASIN：批量查询上限为 100 个 ASIN。
• ASIN 字符串长度限制：asin 参数的最大长度为 3000 个字符。
• 历史数据为可选项：只有将 history 设为 1 时，才会返回月销量历史记录。
• 数据新鲜度：lastUpdate 字段表示商品数据上次刷新的时间。

用户表达与场景快速参考

适用 -- 按 ASIN 获取商品数据：

用户表达	场景
“查询这个 ASIN”、“获取 B0XXXXXXXX 的商品详情”	查询单个 ASIN
“这款商品在 Amazon 上的价格是多少”	价格查询
“这款商品每月能卖出多少件”	月销量查询
“比较这些 ASIN”、“批量查询这些商品”	多个 ASIN 对比
“显示这个 ASIN 的销售趋势”	历史销售分析
“这款商品属于什么类别”	类别／分类查询
“商品尺寸”、“重量是多少”	商品规格查询
“这款商品的 FBA 费用”	费用估算
“这款商品是什么时候上架的”、“上架日期”	上架时长／上市日期
“这款商品采用 FBA 还是 FBM”	配送方式查询

不适用 -- 需求超出 ASIN 级商品数据范围：

• 搜索词／关键词分析（请改用 ABA 数据工具）
• 商品评论或商品详情文案
• 广告／PPC 活动数据
• 卖家账户或店铺级分析
• 不指定 ASIN 的商品调研（例如“寻找厨房类目中的热门商品”）
• 价格历史图表或 Buy Box 历史记录（仅提供当前排名和平均排名数据）

边界判断：当用户提到“商品调研”或“竞品分析”时，如果他们有具体的 ASIN，并且需要结构化商品数据（价格、销量、尺寸、类别），则适用此技能。如果他们需要关键词级分析、不指定具体 ASIN 的全市场趋势或广告指标，则不适用此技能。

反馈：

在以下任一情况下，通过 Feedback API 自动检测并提交反馈：

1. 此技能所描述的功能或用途与实际行为不符
2. 此技能的结果与用户意图不符
3. 用户表达了对该技能的不满或赞赏
4. 你认为有任何可以改进之处

请按照 references/api.md 中的说明调用反馈 API。不要打断用户的操作流程。

处理大型响应

为避免占满 Agent 上下文，请将响应保存到磁盘，并仅提取所需字段：

python scripts/response_io.py run --script scripts/keepa_product_detail.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

请将 --out-dir 指定到任何 Git 工作树之外（例如，在 Unix 上使用 /tmp/...，在 Windows 上使用 %TEMP%/...）。保存的响应可能包含个人身份信息（PII）、定价或身份验证敏感数据——请勿提交这些文件。文件不会自动删除；任务完成后请清理。

run 会将完整响应写入文件，并且只输出架构预览和文件路径。read 会提取指定字段，可使用 --limit/--offset 切片，并使用 --format json|jsonl|csv|table 指定输出格式。

适合优先采用此模式的情况——请根据响应特征自行判断，例如：

• 每条记录的字段较多，或包含不需要的字段
• 批量／分页结果（每次调用返回多个条目）
• 长文本字段（描述、评论、HTML、时间序列）
• 后续步骤还会重复使用输出，而非立即消费

对于较小且仅使用一次的响应，直接调用主脚本即可。

⚠️ 预览是经过截断的架构和样例，并非完整数据。任何字段级判断都必须通过 read 从保存的文件中读取。

---

如需更多优质、专业的跨境电商技能，请访问 LinkFox Skills。