linkfox-keepa-product-series

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Keepa Product Time-Series Data Explorer

Keepa 商品时序数据查询工具

This skill guides you on how to query and analyze Amazon product historical time-series data, helping Amazon sellers track price movements, BSR trends, rating changes, and other key product metrics over time.

本技能将指导您如何查询和分析亚马逊商品的历史时序数据，帮助亚马逊卖家追踪价格走势、BSR趋势、评分变化及其他关键商品指标随时间的变化情况。

Core Concepts

核心概念

This tool provides historical time-series data for individual Amazon products (ASINs) powered by Keepa. It returns timestamped data points for various metrics, allowing trend analysis over a configurable time window (up to 365 days). Each query targets a single ASIN in a specific Amazon marketplace.

Time-series format: All data series are returned as arrays of

{time, value}

objects, where

time

is a timestamp and

value

is the metric at that point. BSR data includes a

categoryName

field along with a

points

array.

BSR logic: A smaller BSR value means a better sales rank. Rank 1 is the top-selling product in its category. When a user says "BSR improved", it means the numeric value decreased; "BSR dropped" means the value increased.

本工具基于Keepa提供亚马逊单个商品（ASIN）的历史时序数据。它返回带时间戳的各类指标数据点，支持在可配置的时间窗口（最长365天）内进行趋势分析。每次查询针对特定亚马逊站点中的单个ASIN。

时序数据格式：所有数据序列均以

{time, value}

对象数组的形式返回，其中

time

为时间戳，

value

为该时间点的指标值。BSR数据包含

categoryName

字段及

points

数组。

BSR逻辑：BSR数值越小代表销售排名越靠前。排名1表示该品类中的最畅销商品。当用户提及‘BSR提升’时，意味着BSR数值下降；‘BSR下滑’则意味着BSR数值上升。

Available Data Series

可用数据序列

Series	Parameter	Description
Buy Box Price	(always returned)	Buy Box price over time
Lowest New Price	showPrice=1	Lowest marketplace new item price
List Price	showPriceList=1	Strikethrough / list price
Deal Price	showPriceDeal=1	Lightning deal price
Prime Exclusive Price	showPricePrime=1	Prime-exclusive new item price
FBA Price	showPriceFba=1	Third-party FBA new item price
FBM Price	showPriceFbm=1	Third-party FBM new item price
Coupon Price	showPriceCoupon=1	Post-coupon Buy Box price
Main Category BSR	showBsrMain=1	Best Sellers Rank in the main (root) category
Seller Count	showSellerCount=1	Number of active sellers
Rating	(always returned)	Product star rating over time
Rating Count	(always returned)	Number of ratings over time
Monthly Sales	(always returned)	Monthly unit sales volume
Sub-category BSR	(always returned)	Best Sellers Rank in sub-categories

数据序列	参数	描述
Buy Box价格	(默认返回)	随时间变化的Buy Box价格
最低全新商品价格	showPrice=1	市场上全新商品的最低价格
标价	showPriceList=1	划掉的原价/标价
促销价格	showPriceDeal=1	限时秒杀价格
Prime专属价格	showPricePrime=1	Prime会员专属的全新商品价格
FBA价格	showPriceFba=1	第三方FBA卖家的全新商品价格
FBM价格	showPriceFbm=1	第三方FBM卖家的全新商品价格
优惠券后价格	showPriceCoupon=1	使用优惠券后的Buy Box价格
主品类BSR	showBsrMain=1	主（根）品类中的畅销排名
卖家数量	showSellerCount=1	活跃卖家数量
评分	(默认返回)	随时间变化的商品星级评分
评分数量	(默认返回)	随时间变化的评分总数
月销量	(默认返回)	月度商品销量
子品类BSR	(默认返回)	子品类中的畅销排名

Supported Marketplaces

支持的亚马逊站点

Domain ID	Marketplace
1	Amazon.com (US)
2	Amazon.co.uk (UK)
3	Amazon.de (Germany)
4	Amazon.fr (France)
5	Amazon.co.jp (Japan)
6	Amazon.ca (Canada)
8	Amazon.it (Italy)
9	Amazon.es (Spain)
10	Amazon.in (India)
11	Amazon.com.mx (Mexico)
12	Amazon.com.br (Brazil)

Default marketplace is 1 (US). Use domain=1 when the user does not specify a marketplace.

域名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（美国）。当用户未指定站点时，使用domain=1。

调用方式

API 端点：
```
POST /keepa/productSeries
```
（完整参数/响应/错误码见
```
references/api.md
```
）

Python 脚本：

python scripts/keepa_product_history.py '<JSON 参数>' [--inline]

成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

始终将完整响应写入
```
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-series-<timestamp>.json
```
（
```
<cwd>
```
为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；
```
<session>
```
取自环境变量
```
SESSION_ID
```
，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如
```
total
```
/
```
costToken
```
、最大列表字段的长度 + 前 3 条样本）
加
```
--inline
```
强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用

jq

或

ConvertFrom-Json

从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

API 端点：
```
POST /keepa/productSeries
```
（完整参数/响应/错误码详见
```
references/api.md
```
）

Python 脚本：

python scripts/keepa_product_history.py '<JSON 参数>' [--inline]

成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带有24小时本地缓存。失败/空结果不得自动更换关键词、翻页或修改邮编连续试探；需要继续检索时需先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

始终将完整响应写入
```
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-series-<timestamp>.json
```
（
```
<cwd>
```
为脚本执行时的工作目录，在Claude Code中即当前项目目录；
```
<session>
```
取自环境变量
```
SESSION_ID
```
，按用户任务自动聚合；禁止写入/tmp目录，若当前目录不可写则报错）
响应体 ≤ 8 KB：落盘后将完整JSON打印到标准输出（stdout）
响应体 > 8 KB：落盘后标准输出仅打印摘要（顶层字段、常见计数如
```
total
```
/
```
costToken
```
、最大列表字段的长度 + 前3条样本）
添加
```
--inline
```
参数可强制将全量内容打印到标准输出（同样会落盘）

读数据建议：先查看摘要判断是否满足需求；需要具体字段时优先使用

jq

或

ConvertFrom-Json

从保存的JSON文件中按需抽取，避免完整JSON进入上下文。

解决认证和积分问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

发生以下异常情况时，按照

references/onboarding.md

中的指引解决：

异常情况

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息包含“积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义的内容。

Parameter Guide

参数指南

Required Parameters

必填参数

asin: The Amazon Standard Identification Number to query. Only a single ASIN per request is supported.
domain: The Amazon marketplace domain ID (see table above). Always map the user's marketplace mention to the correct numeric ID.

asin: 要查询的亚马逊标准识别码（Amazon Standard Identification Number）。每次请求仅支持单个ASIN。
domain: 亚马逊站点的域名ID（见上方表格）。需将用户提及的站点映射为正确的数字ID。

Optional Parameters

可选参数

days: Number of historical days to retrieve (1-365, default 90). Use 30 for short-term, 90 for medium-term, 365 for long-term analysis.
show* flags: Set any
```
show*
```
parameter to
```
1
```
to include that data series. By default, only the core series (Buy Box price, rating, rating count, monthly sales, sub-category BSR) are returned.

days: 要获取的历史天数（1-365，默认90）。短期分析用30天，中期用90天，长期分析用365天。
show 标志位*: 将任意
```
show*
```
参数设为
```
1
```
即可包含对应的数据序列。默认仅返回核心序列（Buy Box价格、评分、评分数量、月销量、子品类BSR）。

How to Choose Parameters

参数选择方法

Price analysis: Enable
```
showPrice
```
,
```
showPriceList
```
,
```
showPriceDeal
```
,
```
showPriceCoupon
```
as needed for the specific price comparison the user wants.
FBA vs FBM comparison: Enable both
```
showPriceFba
```
and
```
showPriceFbm
```
.
BSR deep-dive: Enable
```
showBsrMain
```
to get the root category BSR alongside the always-returned sub-category BSR.
Competitive landscape: Enable
```
showSellerCount
```
to see how many sellers are competing.
Full product overview: Enable all show flags for a comprehensive historical snapshot.

价格分析：根据用户所需的具体价格对比需求，启用
```
showPrice
```
、
```
showPriceList
```
、
```
showPriceDeal
```
、
```
showPriceCoupon
```
。
FBA与FBM对比：同时启用
```
showPriceFba
```
和
```
showPriceFbm
```
。
BSR深度分析：启用
```
showBsrMain
```
以获取根品类BSR数据，配合默认返回的子品类BSR数据。
竞争格局分析：启用
```
showSellerCount
```
查看当前有多少卖家在竞争。
商品全面概况：启用所有show标志位以获取完整的历史快照。

Usage Examples

使用示例

1. Basic price history for a US product

asin: B0XXXXXXXX, domain: 1, days: 90

2. Long-term BSR trend (1 year) on the German marketplace

asin: B0XXXXXXXX, domain: 3, days: 365, showBsrMain: 1

3. Price comparison across fulfillment channels

asin: B0XXXXXXXX, domain: 1, days: 30, showPriceFba: 1, showPriceFbm: 1, showPrice: 1

4. Deal and coupon price tracking

asin: B0XXXXXXXX, domain: 1, days: 90, showPriceDeal: 1, showPriceCoupon: 1

5. Full product health check

asin: B0XXXXXXXX, domain: 1, days: 90, showPrice: 1, showPriceList: 1, showPriceDeal: 1, showPricePrime: 1, showPriceFba: 1, showPriceFbm: 1, showPriceCoupon: 1, showBsrMain: 1, showSellerCount: 1

1. 美国站点商品的基础价格历史查询

asin: B0XXXXXXXX, domain: 1, days: 90

2. 德国站点商品的长期BSR趋势（1年）

asin: B0XXXXXXXX, domain: 3, days: 365, showBsrMain: 1

3. 不同配送渠道的价格对比

asin: B0XXXXXXXX, domain: 1, days: 30, showPriceFba: 1, showPriceFbm: 1, showPrice: 1

4. 促销与优惠券价格追踪

asin: B0XXXXXXXX, domain: 1, days: 90, showPriceDeal: 1, showPriceCoupon: 1

5. 商品健康状况全面检查

asin: B0XXXXXXXX, domain: 1, days: 90, showPrice: 1, showPriceList: 1, showPriceDeal: 1, showPricePrime: 1, showPriceFba: 1, showPriceFbm: 1, showPriceCoupon: 1, showBsrMain: 1, showSellerCount: 1

Display Rules

展示规则

Present data clearly: Show time-series data in tables or describe trends; avoid subjective business advice unless the user explicitly asks for it.
BSR clarification: When showing BSR data, remind users that lower values mean better (higher) sales ranks.
Price formatting: Display prices with proper currency symbols matching the marketplace ($ for US, EUR for DE/FR/ES/IT, GBP for UK, JPY for JP, etc.).
Time formatting: Present timestamps in a human-readable date format.
Trend summarization: When data series are long, summarize the overall trend (e.g., "price decreased from $29.99 to $24.99 over 90 days") and highlight significant changes such as price drops, BSR spikes, or rating shifts.
Error handling: When a query fails, explain the reason and suggest corrections (e.g., verify the ASIN is valid, check the marketplace domain ID).
Single ASIN limitation: If the user asks about multiple ASINs, inform them that queries must be made one ASIN at a time, and run multiple sequential calls.

清晰呈现数据：以表格形式展示时序数据或描述趋势；除非用户明确要求，否则避免提供主观业务建议。
BSR说明：展示BSR数据时，提醒用户数值越小代表销售排名越靠前。
价格格式：显示价格时使用与站点匹配的正确货币符号（美国用$，德国/法国/西班牙/意大利用EUR，英国用GBP，日本用JPY等）。
时间格式：以人类可读的日期格式呈现时间戳。
趋势总结：当数据序列较长时，总结整体趋势（例如：“90天内价格从$29.99降至$24.99”），并突出显著变化，如价格下跌、BSR骤变或评分波动。
错误处理：查询失败时，说明原因并建议修正方案（例如：验证ASIN是否有效，检查站点域名ID是否正确）。
单个ASIN限制：若用户查询多个ASIN，告知用户每次只能查询一个ASIN，需进行多次连续调用。

Important Limitations

重要限制

Single ASIN per query: Only one ASIN can be queried at a time. For multi-ASIN comparisons, make separate requests.
Maximum 365 days: Historical data is limited to at most 365 days back.
Data granularity: Data points are at irregular intervals depending on when Keepa captured changes, not at fixed daily intervals.

每次查询单个ASIN：每次仅能查询一个ASIN。如需多ASIN对比，需发起单独请求。
最长365天：历史数据最多可追溯至365天前。
数据粒度：数据点的间隔不固定，取决于Keepa捕获数据变化的时间，并非每日固定间隔。

User Expression & Scenario Quick Reference

用户表述与场景速查

Applicable -- Historical product-level data queries on Amazon:

User Says	Scenario
"What's the price history for this ASIN"	Price trend analysis
"Show me the BSR trend", "how is it ranking"	BSR tracking
"Has the price dropped recently", "any deals"	Price drop / deal detection
"How many sellers are on this listing"	Seller count trend
"What's the rating trend", "review count over time"	Rating / review tracking
"FBA vs FBM price", "who has the Buy Box"	Fulfillment price comparison
"Monthly sales for this product"	Sales volume trend
"Was there a price war on this ASIN"	Competitive pricing analysis
"Show me the Keepa chart", "Keepa data"	Explicit Keepa data requests

Not applicable -- Needs beyond product-level historical data:

Search term / keyword analysis (use ABA data instead)
Advertising / PPC campaign data
Listing copywriting or content optimization
Category-wide or market-level aggregate trends (this tool is per-ASIN only)
Real-time inventory or stock level checks
Product reviews text or sentiment analysis

Boundary judgment: When users say "product research" or "competitor analysis", if it boils down to examining a specific ASIN's historical price, BSR, or sales data, this skill applies. If they need keyword data, market-wide trends, or advertising metrics, it does not apply.

适用场景 -- 亚马逊商品级历史数据查询：

用户表述	场景
"这个ASIN的价格历史是怎样的"	价格趋势分析
"展示BSR趋势"、"排名情况如何"	BSR追踪
"最近价格有没有下降"、"有没有促销活动"	价格下跌/促销活动检测
"这个Listing有多少卖家"	卖家数量趋势查询
"评分趋势如何"、"评论数量随时间变化情况"	评分/评论追踪
"FBA与FBM价格对比"、"谁拥有Buy Box"	配送渠道价格对比
"这个商品的月销量"	销量趋势查询
"这个ASIN有没有价格战"	竞争定价分析
"展示Keepa图表"、"Keepa数据"	明确请求Keepa数据

不适用场景 -- 超出商品级历史数据的需求：

搜索词/关键词分析（请使用ABA数据）
广告/PPC活动数据
Listing文案优化
品类或市场层面的整体趋势（本工具仅支持单个ASIN查询）
实时库存检查
商品评论文本或情感分析

边界判断：当用户提及“商品调研”或“竞品分析”时，若核心需求是查看特定ASIN的历史价格、BSR或销量数据，则适用本技能；若需要关键词数据、市场整体趋势或广告指标，则不适用。

积分消耗规则

按动态规则计费：消耗积分 = 0.045 × 本次历史趋势查询消耗的 Keepa token。

重要：本技能的服务按倍数动态计算，可能一次性消耗大量积分，必须提醒用户，由用户决定是否继续。

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

The functionality or purpose described in this skill does not match actual behavior
The skill's results do not match the user's intent
The user expresses dissatisfaction or praise about this skill
Anything you believe could be improved

Call the feedback API as specified in

references/api.md

. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, set LinkFox Skills.

按动态规则计费：消耗积分 = 0.045 × 本次历史趋势查询消耗的Keepa token。

重要：本技能的服务费用按倍数动态计算，可能一次性消耗大量积分，必须提前提醒用户，由用户决定是否继续。

反馈：

当出现以下任意情况时，通过反馈API自动检测并上报：

本技能描述的功能或用途与实际行为不符
技能结果不符合用户意图
用户表达了对本技能的不满或赞扬
任何您认为可以改进的地方

按照

references/api.md

中的说明调用反馈API，请勿打断用户的操作流程。

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