Back to Details

linkfox-keepa-product-request

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Keepa Product Data Request

Keepa 商品数据请求

This skill guides you on how to retrieve Amazon product details via the Keepa product request API, helping Amazon sellers and analysts obtain structured product data for one or more ASINs across multiple Amazon marketplaces.
本技能将指导您如何通过Keepa商品请求API获取亚马逊商品详情，帮助亚马逊卖家和分析师获取多个亚马逊站点中一个或多个ASIN的结构化商品数据。

Core Concepts

核心概念

The Keepa Product Request API returns detailed product listing data from Amazon, sourced through Keepa. Given one or more ASINs and a marketplace, it returns comprehensive product information: pricing, title, main image, listing date, material, weight, dimensions, sales rank, monthly sales units (current and up to 12 months of history), FBA fees, ratings, review counts, category tree, and more.
Key points:
  • You can query up to 5 ASINs in a single request by separating them with commas.
  • The 
    domain
    parameter is a numeric marketplace ID (e.g., 
    1
    = Amazon.com US), not a country code.
  • Setting 
    history
    to 
    1
    includes historical sales data (monthly sales for up to 12 prior months, average sales rank over 30/90/180 days). Setting it to 
    0
    returns only current product information.
  • The response does not include product descriptions or reviews content.
Keepa Product Request API 通过Keepa数据源返回亚马逊的详细商品Listing数据。给定一个或多个ASIN及站点信息，它会返回全面的商品信息：定价、标题、主图、上架日期、材质、重量、尺寸、销售排名、月销量（当前及最多12个月历史数据）、FBA费用、评分、评论数、类目树等。
关键点:
  • 单次请求最多可查询5个ASIN，使用逗号分隔。
  • domain
    参数为数字格式的站点ID（例如：
    1
    = 亚马逊美国站Amazon.com），而非国家代码。
  • 将
    history
    设为
    1
    会包含历史销售数据（过去12个月的月销量、30/90/180天平均销售排名）。设为
    0
    则仅返回当前商品信息。
  • 响应结果不包含商品描述或评论内容。

Parameter Guide

参数指南

domain (Required)

domain（必填）

Numeric Amazon marketplace ID. The mapping is:
Domain IDMarketplace
1Amazon.com (US)
2Amazon.co.uk (UK)
3Amazon.de (Germany)
4Amazon.fr (France)
5Amazon.co.jp (Japan)
6Amazon.ca (Canada)
8Amazon.it (Italy)
9Amazon.es (Spain)
10Amazon.in (India)
11Amazon.com.mx (Mexico)
12Amazon.com.br (Brazil)
Default to 1 (US) when the user does not specify a marketplace.
数字格式的亚马逊站点ID，对应关系如下：
站点ID亚马逊站点
1Amazon.com（美国）
2Amazon.co.uk（英国）
3Amazon.de（德国）
4Amazon.fr（法国）
5Amazon.co.jp（日本）
6Amazon.ca（加拿大）
8Amazon.it（意大利）
9Amazon.es（西班牙）
10Amazon.in（印度）
11Amazon.com.mx（墨西哥）
12Amazon.com.br（巴西）
当用户未指定站点时，默认使用1（美国站）。

asin (Required)

asin（必填）

One or more Amazon Standard Identification Numbers. For multiple ASINs, separate with commas. Maximum 5 ASINs per request, with a total string length limit of 300 characters.
一个或多个亚马逊标准识别码（ASIN）。多个ASIN使用逗号分隔，单次请求最多支持5个ASIN，且参数总字符串长度不超过300字符。

history (Optional)

history（可选）

Whether to include historical data such as monthly sales for the past 12 months and average sales rank over 30/90/180 days. Set to 
1
to include history, 
0
(default) for basic info only.
是否包含历史数据，如过去12个月的月销量及30/90/180天平均销售排名。设为
1
则包含历史数据，
0
（默认）仅返回基础信息。

Usage Examples

使用示例

1. Single ASIN lookup (US marketplace, basic info)
json
{"asin": "B0088PUEPK", "domain": "1"}
2. Single ASIN with historical sales data
json
{"asin": "B0088PUEPK", "domain": "1", "history": 1}
3. Batch lookup of multiple ASINs (Germany)
json
{"asin": "B0088PUEPK,B00U26V4VQ,B07M68S376", "domain": "3", "history": 1}
4. Product lookup on Amazon Japan
json
{"asin": "B09V3KXJPB", "domain": "5", "history": 0}
5. Competitor comparison across multiple ASINs (US, with sales history)
json
{"asin": "B0CXYZ1234,B0CXYZ5678,B0CXYZ9012,B0CXYZABCD", "domain": "1", "history": 1}
1. 单个ASIN查询（美国站，基础信息）
json
{"asin": "B0088PUEPK", "domain": "1"}
2. 单个ASIN查询（含历史销售数据）
json
{"asin": "B0088PUEPK", "domain": "1", "history": 1}
3. 批量ASIN查询（德国站）
json
{"asin": "B0088PUEPK,B00U26V4VQ,B07M68S376", "domain": "3", "history": 1}
4. 亚马逊日本站商品查询
json
{"asin": "B09V3KXJPB", "domain": "5", "history": 0}
5. 多ASIN竞品对比（美国站，含销售历史）
json
{"asin": "B0CXYZ1234,B0CXYZ5678,B0CXYZ9012,B0CXYZABCD", "domain": "1", "history": 1}

调用方式

调用方式

  • API 端点：
    POST /keepa/productRequest
    （完整参数/响应/错误码见 
    references/api.md
    ）
  • Python 脚本：
    python scripts/keepa_product_detail.py '<JSON 参数>' [--inline]
  • 成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。
输出策略（脚本默认行为）：
  • 始终将完整响应写入 
    <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-request-<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/productRequest
    （完整参数/响应/错误码见 
    references/api.md
    ）
  • Python 脚本：
    python scripts/keepa_product_detail.py '<JSON 参数>' [--inline]
  • 成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带24小时本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。
输出策略（脚本默认行为）：
  • 始终将完整响应写入 
    <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-request-<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进入上下文。

解决认证和积分问题

解决认证和积分问题

发生以下异常情况时，采用 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/套餐到期/需充值/请充值"，或类似含义的内容。

Display Rules

展示规则

  1. Present data clearly: Show product details in well-structured tables. Group related fields (e.g., dimensions together, sales data together) for readability.
  2. Price and currency: Always display the price alongside its currency (e.g., "$29.99 USD"). The 
    currency
    field in the response indicates the local currency.
  3. Sales trend: When historical data is included, present the 12-month sales trend in a table or describe the trajectory (growing, declining, stable) to help users quickly assess momentum.
  4. Dimensions and weight: Convert millimeter values to more intuitive units when appropriate (e.g., show both mm and inches, or mm and cm). Note that weight is in grams.
  5. Unavailable data: Fields with value 
    0
    or 
    -1
    indicate data is unavailable. Do not display these as actual measurements; instead note "N/A" or omit them.
  6. Image display: If 
    imageUrl
    is present, display the product image to help users visually identify the product.
  7. Error handling: When a query fails, explain the issue based on the response and suggest corrections (e.g., invalid ASIN format, unsupported marketplace).
  8. Large batch results: For batch queries with many ASINs, present a summary table first and offer to show individual product details on request.
  1. 清晰呈现数据：使用结构清晰的表格展示商品详情，将相关字段分组（如尺寸类字段放在一起、销售数据放在一起）以提升可读性。
  2. 价格与货币：始终显示价格对应的货币（例如："$29.99 USD"）。响应中的
    currency
    字段表示当地货币。
  3. 销售趋势：当包含历史数据时，将12个月的销售趋势以表格形式呈现，或描述其走势（增长、下降、稳定），帮助用户快速评估商品势头。
  4. 尺寸与重量：适当将毫米单位转换为更直观的单位（例如：同时显示毫米和英寸，或毫米和厘米）。注意重量单位为克。
  5. 缺失数据：值为
    0
    或
    -1
    的字段表示数据不可用，请勿将其作为实际数值展示，应标注为"N/A"或省略。
  6. 图片展示：如果
    imageUrl
    存在，展示商品图片以帮助用户直观识别商品。
  7. 错误处理：当查询失败时，根据响应信息解释问题并建议修正方案（例如：ASIN格式无效、不支持的站点）。
  8. 批量查询结果：对于包含多个ASIN的批量查询，先展示汇总表格，再根据用户请求提供单个商品的详细信息。

Important Limitations

重要限制

  • No product descriptions or reviews: The API does not return product description text or review content.
  • Maximum 5 ASINs per request: Batch queries are capped at 5 ASINs.
  • ASIN string length limit: The 
    asin
    parameter has a maximum length of 300 characters.
  • Historical data is optional: Monthly sales history is only returned when 
    history
    is set to 
    1
    .
  • Data freshness: The 
    lastUpdate
    field indicates when the product data was last refreshed.
  • 无商品描述或评论：API不返回商品描述文本或评论内容。
  • 单次请求最多5个ASIN：批量查询上限为5个ASIN。
  • ASIN字符串长度限制：
    asin
    参数的最大长度为300字符。
  • 历史数据为可选项：仅当
    history
    设为
    1
    时才会返回月销量历史数据。
  • 数据新鲜度：
    lastUpdate
    字段表示商品数据的最后更新时间。

User Expression & Scenario Quick Reference

用户表述与场景速查

Applicable -- Product data retrieval by ASIN:
User SaysScenario
"Look up this ASIN", "Get product details for B0XXXXXXXX"Single ASIN lookup
"What's the price of this product on Amazon"Price query
"How many units does this product sell per month"Monthly sales check
"Compare these ASINs", "batch lookup these products"Multi-ASIN comparison
"Show me the sales trend for this ASIN"Historical sales analysis
"What category is this product in"Category / classification lookup
"Product dimensions", "how much does it weigh"Physical specs query
"FBA fees for this product"Fee estimation
"When was this product listed", "listing date"Listing age / launch date
"Is this product FBA or FBM"Fulfillment method check
Not applicable -- Needs beyond ASIN-level product data:
  • Search term / keyword analysis (use ABA data tools instead)
  • Product reviews or listing copywriting content
  • Advertising / PPC campaign data
  • Seller account or store-level analytics
  • Product research without specific ASINs (e.g., "find trending products in kitchen category")
  • Price history charts or Buy Box history over time (only current and average rank data are available)
Boundary judgment: When users say "product research" or "competitor analysis", if they have specific ASINs and want structured product data (price, sales, dimensions, category), this skill applies. If they want keyword-level analysis, market-wide trends without specific ASINs, or advertising metrics, this skill does not apply.
适用场景 -- 通过ASIN获取商品数据：
用户表述场景
"查询这个ASIN"、"获取B0XXXXXXXX的商品详情"单个ASIN查询
"这个商品在亚马逊上的价格是多少"价格查询
"这个商品每月销量是多少"月销量查询
"对比这些ASIN"、"批量查询这些商品"多ASIN对比
"展示这个ASIN的销售趋势"历史销售分析
"这个商品属于什么类目"类目/分类查询
"商品尺寸"、"它有多重"物理规格查询
"这个商品的FBA费用是多少"费用估算
"这个商品什么时候上架的"、"上架日期"上架时长/发布日期查询
"这个商品是FBA还是FBM发货"配送方式查询
不适用场景 -- 超出ASIN级商品数据的需求：
  • 搜索词/关键词分析（请使用ABA数据工具）
  • 商品评论或Listing文案内容
  • 广告/PPC推广数据
  • 卖家账号或店铺级分析
  • 无特定ASIN的商品调研（例如："查找厨房类目的热门商品"）
  • 价格历史图表或Buy Box历史数据（仅提供当前及平均排名数据）
边界判断：当用户提及"商品调研"或"竞品分析"时，如果他们提供了特定ASIN并需要结构化商品数据（价格、销量、尺寸、类目），则适用本技能。如果他们需要关键词级分析、无特定ASIN的市场趋势或广告指标，则不适用本技能。

积分消耗规则

积分消耗规则

按动态规则计费：消耗积分 = 0.045 × 本次商品详情查询消耗的 Keepa token。
重要：本技能的服务按倍数动态计算，可能一次性消耗大量积分，必须提醒用户，由用户决定是否继续。
Feedback:
Auto-detect and report feedback via the Feedback API when any of the following apply:
  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. 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自动检测并上报反馈：
  1. 本技能描述的功能或用途与实际行为不符
  2. 技能结果与用户意图不匹配
  3. 用户表达了对本技能的不满或赞扬
  4. 任何您认为可以改进的地方
按照
references/api.md
中的说明调用反馈API，请勿打断用户的操作流程。
如需更多高质量、专业的跨境电商技能，请访问 LinkFox Skills.