linkfox-sif-keyword-overview

SIF 关键词概览

本技能将指导你如何查询和分析 Amazon 上的关键词级竞争数据，帮助卖家评估特定关键词的市场竞争力和供需动态。

核心概念

SIF 关键词概览工具可全面展示 Amazon 上指定关键词的竞争指标。它会返回不同展示类型（自然搜索、赞助广告、视频广告、品牌广告等）下的竞争产品数量、预估每周搜索量、关键词热度排名以及供需比。

供需比：按 搜索结果产品总数 / 月搜索量 计算。比值越低，表示竞争越小、机会越大。这是识别蓝海关键词的关键指标。

关键词热度排名：表示该关键词按月搜索量在平台所有关键词中的排名。数值越小，搜索热度越高（排名第 1 表示最热门）。用户说“排名提升”时，表示数值降低；说“排名下降”时，表示数值升高。

数据字段

字段	API 名称	描述
关键词	keyword	查询的关键词文本
关键词热度排名	keywordPopularityRank	所有关键词中的月搜索量排名（数值越低 = 越热门）
预估每周搜索量	estimatedWeeklySearchVolume	Amazon 上的预估每周搜索次数
供需比	supplyDemandRatio	产品数量 / 月搜索量（数值越低 = 竞争越小）
搜索结果产品总数	totalSearchResultProductCount	此关键词下显示的产品总数（自然搜索 + 广告 + 推荐）
自然搜索产品数	naturalSearchProductCount	自然搜索结果中的产品数（不含广告）
赞助产品（SP）数量	sponsoredProductsCount	投放 Sponsored Products 广告的产品数
品牌广告产品数	brandAdProductCount	投放 Brand Ads 的产品数
视频广告产品数	videoAdProductCount	投放 Video Ads 的产品数
付费广告产品总数	paidAdvertisingProductCount	所有 PPC 广告产品的总数（SP + 品牌广告 + 视频广告等）
Amazon's Choice 产品数	amazonChoiceProductCount	带有 Amazon's Choice 标识的产品数
评分最高产品数	topRatedProductCount	“评分最高”推荐版块中的产品数
搜索推荐产品数	searchRecommendationProductCount	Amazon 在搜索过程中推荐的产品数
编辑推荐产品数	editorialRecommendationsProductCount	“编辑推荐”版块中的产品数
推荐位非广告产品数	recNonadProductCount	被归类为非广告的推荐位产品数（自然推荐）
推荐位广告产品数	recAdProductCount	推荐位中被归类为广告的产品数
SIF 跟踪的曝光 ASIN 数	trackedAsinTotalCount	SIF 跟踪过且具有任意曝光分数（自然搜索/广告/推荐）的去重 ASIN 数量 — 上游字段 totalAsinNum
平台关键词总数	totalMarketplaceKeywordCount	平台中的关键词总数
数据周期开始日期	dataPeriodStartDate	返回数据对应的 ABA 周开始日期（yyyy-MM-dd）
数据周期结束日期	dataPeriodEndDate	返回数据对应的 ABA 周结束日期（yyyy-MM-dd）
数据更新时间	keywordDataUpdateTime	此关键词数据的最后更新时间

支持的站点

13 个站点：US（美国）、UK（英国）、DE（德国）、CA（加拿大）、JP（日本）、FR（法国）、ES（西班牙）、IT（意大利）、MX（墨西哥）、AU（澳大利亚）、AE（阿联酋）、BR（巴西）、SA（沙特阿拉伯）。

默认站点为 US。用户未指定站点时使用 US。此列表之外的代码会被 API 模式拒绝。

重要：keyword 参数最好使用目标站点的语言。例如，DE 使用德语关键词，JP 使用日语关键词等。如果用户提供的关键词使用其他语言，请先将其翻译为站点的本地语言，再进行查询。

调用方式

• API 端点：POST /sif/keywordOverview（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/sif_keyword_overview.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sif-keyword-overview-<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 引导解决问题：

异常情况

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

参数指南

1. keyword（必填）：要分析的搜索关键词。为获得最佳结果，应将其翻译为目标站点的语言。最大长度：1000 个字符。
2. country（可选）：Amazon 站点代码。默认为 US。有效代码请参见上方的“支持的站点”。
3. last7d（可选，布尔值，默认 true）：使用最近 7 天的数据。设为 false 时，API 使用 startDate/endDate。
4. startDate（可选，yyyy-MM-dd）：自定义时间段的开始日期。在 last7d=false 时生效。
5. endDate（可选，yyyy-MM-dd）：与 startDate 配对的结束日期。

使用示例

1. 基础关键词竞争检查 查询：“Amazon US 上关键词 'wireless charger' 的竞争有多激烈？”

{"keyword": "wireless charger", "country": "US"}

2. 检查美国以外站点的竞争情况 查询：“Amazon Germany 上 'Handyhulle' 有多少竞争对手？”

{"keyword": "Handyhulle", "country": "DE"}

3. 产品调研供需分析 查询：“US 的 'yoga mat' 供需比是多少？”

{"keyword": "yoga mat", "country": "US"}

4. 广告竞争评估 查询：“UK 上有多少卖家在为 'dog leash' 投放广告？”

{"keyword": "dog leash", "country": "UK"}

5. 多站点比较（多次调用） 查询：“比较 'bluetooth speaker' 在 US、UK 和 DE 的竞争情况”

• 调用 1：{"keyword": "bluetooth speaker", "country": "US"}
• 调用 2：{"keyword": "bluetooth speaker", "country": "UK"}
• 调用 3：{"keyword": "Bluetooth Lautsprecher", "country": "DE"}

6. 指定日期范围 查询：“2026-03-08 至 2026-03-14 期间 'yoga mat' 的竞争情况”

{"keyword": "yoga mat", "country": "US", "last7d": false, "startDate": "2026-03-08", "endDate": "2026-03-14"}

显示规则

1. 清晰呈现数据：以结构清晰的表格形式展示查询结果，并包含用户要求的所有相关指标。
2. 突出关键指标：展示结果时，突出供需比、关键词热度排名和商品总数，因为这些指标最具参考价值。
3. 排名说明：展示关键词热度排名时，提醒用户数值越低，搜索热度越高。
4. 供需比解读：展示供需比时，提供背景说明：低于 1 表示相对供给而言需求较高（存在机会）；高于 5 表示市场已趋于饱和。
5. 广告竞争细分：用户询问广告竞争情况时，将付费广告总数按 SP、Brand、Video 分项列出，以便更详细地了解情况。
6. 错误处理：查询失败时，根据 msg 字段说明原因，并建议调整查询参数（例如，检查关键词拼写或尝试其他商城）。
7. 数据时效性与周期：始终展示 keywordDataUpdateTime（上次刷新时间），以及 dataPeriodStartDate ~ dataPeriodEndDate（计数对应的 ABA 周）。展示商品数量时必须注明对应周期。
8. 不提供主观建议：客观呈现数据，除非用户明确要求，否则不要提供业务建议。

重要限制

• 每次请求仅支持一个关键词：每次 API 调用只查询一个关键词。比较多个关键词时，需分别调用。
• 响应通常仅含一条记录：API 通常针对每个关键词返回一条数据记录（total 通常为 1）。
• 商城覆盖范围：支持 13 个 Amazon 商城；IN / NL / SE / PL / TR / SG 已不再支持。在所查询商城中找不到的关键词将返回空结果。
• 时间范围：默认查询最近 7 天。如需自定义 ABA 周范围，请传入 last7d=false 以及 startDate/endDate。
• 关键词语言：为获得最佳准确度，关键词应使用目标商城的当地语言。

用户表达与场景快速参考

适用——关键词级别的竞争与市场评估：

用户表达	场景
"How competitive is XX keyword"	竞争强度检查
"How many products are there for XX"	搜索结果商品数量
"What's the supply-demand ratio for XX"	供需分析
"How many sellers are advertising on XX"	广告竞争评估
"Is XX keyword a blue ocean"	市场机会评估
"Search volume for XX keyword"	搜索热度估算
"How popular is XX keyword on Amazon"	关键词热度排名
"Compare competition across marketplaces"	多商城竞争比较
"How many SIF-tracked ASINs are active on this keyword"	SIF 跟踪的去重 ASIN 数量（trackedAsinTotalCount）
"Competition for this keyword in a specific week"	通过 startDate/endDate 设置自定义日期范围

不适用——超出关键词竞争概览的需求：

• 随时间变化的历史关键词排名趋势（改用 ABA Data Explorer）
• 按 ASIN 划分的点击份额和转化份额（改用 ABA Data Explorer）
• 广告竞价策略和 PPC 优化
• 商品评论、商品详情页优化
• ASIN 级别的销售额估算
• 按周或按月进行的详细关键词搜索趋势分析

算力消耗规则

消耗 9 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

在以下任一情况出现时，通过 Feedback API 自动检测并报告反馈：

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

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

---

如需获取更多高质量、专业的跨境电商技能，请设置 LinkFox Skills。