linkfox-sif-keyword-summary

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SIF Keyword Traffic Source Summary

SIF关键词流量来源汇总

This skill guides you on how to query and analyze keyword traffic source data for Amazon products, helping sellers understand the traffic structure behind keywords — including organic search, Sponsored Products (SP) ads, brand ads, video ads, and various Amazon recommendation placements.

本技能将指导您查询和分析亚马逊产品的关键词流量来源数据，帮助卖家了解关键词背后的流量结构——包括自然搜索、Sponsored Products（SP）广告、品牌广告、视频广告以及各类亚马逊推荐位。

Core Concepts

核心概念

The SIF Keyword Summary tool returns, for one given keyword, the list of ASINs appearing under that keyword along with their per-keyword traffic exposure breakdown and their product-level cross-channel traffic mix. It answers: Who is taking traffic under this keyword, and through which channels?

Traffic channels analyzed:

Natural Search — organic search result positions
SP Ads (Sponsored Products) — paid product ad placements (regular slot)
Brand Ads (SB) — top and bottom brand ad placements on the search results page
Video Ads (SBV) — Sponsored Brands Video placements
SP Recommendation slots — Trending now / Seen on social media / Customers frequently viewed / 4 stars and above
Amazon's Choice (AC) — Amazon's Choice badge recommendations
Editorial Recommendations (ER) — editorial/curated recommendation placements
Top Rated (TR) — high-rating recommendation placements

Two score families (important — do not mix):

Product-level fields (no prefix, e.g.
```
naturalSearchExposureScore
```
): the ASIN's overall exposure across all keywords.
Keyword-level fields (
```
keyword…
```
prefix, e.g.
```
keywordNaturalExposureScore
```
): the ASIN's exposure on just this one queried keyword.

SIF关键词汇总工具针对单个给定关键词，返回该关键词下出现的ASIN列表，以及每个ASIN在该关键词下的流量曝光拆解，还有产品层面的跨渠道流量组合。它可以解答：该关键词下哪些竞品在抢占流量，以及通过哪些渠道？

分析的流量渠道：

自然搜索——自然搜索结果位置
SP广告（Sponsored Products）——付费产品广告位（常规插槽）
品牌广告（SB）——搜索结果页顶部和底部的品牌广告位
视频广告（SBV）——Sponsored Brands Video广告位
SP推荐位——Trending now / Seen on social media / Customers frequently viewed / 4 stars and above（当下热门/社交媒体热门/客户常看/4星及以上）
Amazon's Choice（AC）——Amazon's Choice标识推荐位
编辑推荐（ER）——编辑精选推荐位
Top Rated（TR）——高评分推荐位

两类评分体系（重要——请勿混淆）：

产品层面字段（无前缀，例如
```
naturalSearchExposureScore
```
）：该ASIN在所有关键词下的整体曝光情况。
关键词层面字段（带
```
keyword…
```
前缀，例如
```
keywordNaturalExposureScore
```
）：该ASIN仅在当前查询关键词下的曝光情况。

Parameter Guide

参数指南

Required Parameter

必填参数

Parameter	Type	Description
searchKeyword	string	The search keyword to analyze. Translate to the target marketplace's language when applicable. Max 1000 characters.

参数	类型	描述
searchKeyword	string	要分析的搜索关键词。适用时需转换为目标站点的语言。最多1000字符。

Optional Parameters

可选参数

Parameter	Type	Default	Description
country	string	US	Marketplace code (13 supported — see list below).
asins	string	(none)	Comma-separated ASIN filter; if omitted, returns all ASINs appearing under the keyword. Max 1000 chars.
condition	string	(none)	Filter by a specific traffic source. Only one value per request. See Condition Filters below.
last7d	boolean	true	Use the latest 7 days. When `false` , the API uses `startDate` / `endDate` .
startDate	string	—	`yyyy-MM-dd` . Takes effect when `last7d=false` ; if omitted, the system's latest integral week is used.
endDate	string	—	`yyyy-MM-dd` , paired with `startDate` .
sortBy	string	(default)	Sort field. See sortBy section below.
pageNum	integer	1	Page number for pagination.
pageSize	integer	100	Results per page. Min 10, max 100.
desc	boolean	true	Sort in descending order.

参数	类型	默认值	描述
country	string	US	站点代码（支持13个——见下方列表）。
asins	string	无	逗号分隔的ASIN筛选条件；若省略，返回该关键词下出现的所有ASIN。最多1000字符。
condition	string	无	按特定流量来源筛选。每次请求仅支持一个值。见下方条件筛选器。
last7d	boolean	true	使用最近7天的数据。当 `false` 时，API将使用 `startDate` / `endDate` 。
startDate	string	—	`yyyy-MM-dd` 格式。当 `last7d=false` 时生效；若省略，系统将使用最近的完整周数据。
endDate	string	—	`yyyy-MM-dd` 格式，需与 `startDate` 配合使用。
sortBy	string	默认	排序字段。见下方sortBy部分。
pageNum	integer	1	分页页码。
pageSize	integer	100	每页结果数。最小值10，最大值100。
desc	boolean	true	降序排序。

Supported Marketplaces

支持的站点

13 marketplaces: US (United States), UK (United Kingdom), DE (Germany), CA (Canada), JP (Japan), FR (France), ES (Spain), IT (Italy), MX (Mexico), AU (Australia), AE (United Arab Emirates), BR (Brazil), SA (Saudi Arabia).

Default marketplace is US. Codes outside this list will be rejected by the API pattern.

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

默认站点为US。不在此列表中的代码会被API拒绝。

Condition Filters

条件筛选器

Each request can include at most one condition filter. Flag-style:

Value	Meaning
nfPosition	Natural search traffic keywords
isSpAd	SP ad keywords
isVedioAd	Video ad keywords
isBrandAd	Brand ad keywords
isPPCAd	PPC ad keywords (all paid ad types)
isSearchRecommend	Search recommendation keywords
acAd	SP recommendation (Trending now / Customers frequently viewed / etc.)

Period-count filters (

.total

full /

.in

new-in):

Value	Meaning
totalPeriod.in	Newly-entered traffic keywords this period
nfKeywordCnt.total / nfKeywordCnt.in	Keywords with (new) organic exposure
adKeywordCnt.total / adKeywordCnt.in	Keywords with (new) ad exposure
allSpKeywordCnt.total / allSpKeywordCnt.in	(New) SP-ad keywords (regular + recommendation)
spKeywordCnt.total / spKeywordCnt.in	(New) SP regular keywords
recSpKeywordCnt.total / recSpKeywordCnt.in	(New) SP recommendation keywords
allSbKeywordCnt.total / allSbKeywordCnt.in	(New) SB-ad keywords
sbKeywordCnt.total / sbKeywordCnt.in	(New) SB regular keywords
sbvKeywordCnt.total / sbvKeywordCnt.in	(New) SBV keywords

每次请求最多可包含一个条件筛选器，采用标识式：

值	含义
nfPosition	自然搜索流量关键词
isSpAd	SP广告关键词
isVedioAd	视频广告关键词
isBrandAd	品牌广告关键词
isPPCAd	PPC广告关键词（所有付费广告类型）
isSearchRecommend	搜索推荐关键词
acAd	SP推荐位（当下热门/客户常看等）

周期计数筛选器（

.total

全部 /

.in

新增）：

值	含义
totalPeriod.in	本周期新增的流量关键词
nfKeywordCnt.total / nfKeywordCnt.in	有（新增）自然曝光的关键词
adKeywordCnt.total / adKeywordCnt.in	有（新增）广告曝光的关键词
allSpKeywordCnt.total / allSpKeywordCnt.in	（新增）SP广告关键词（常规+推荐位）
spKeywordCnt.total / spKeywordCnt.in	（新增）SP常规关键词
recSpKeywordCnt.total / recSpKeywordCnt.in	（新增）SP推荐位关键词
allSbKeywordCnt.total / allSbKeywordCnt.in	（新增）SB广告关键词
sbKeywordCnt.total / sbKeywordCnt.in	（新增）SB常规关键词
sbvKeywordCnt.total / sbvKeywordCnt.in	（新增）SBV关键词

sortBy

Leave empty for system default. Valid values:

totalKeywordNum

(total keyword count),

naturalKeywordNum

brandKeywordNum

vedioKeywordNum

acKeywordNum

erKeywordNum

trKeywordNum

sumScore

(total exposure across all keywords),

totalNfScore

totalSpSocre

(note spelling),

totalBrandScore

totalVedioScore

totalAcScore

totalTrScore

totalErScore

留空则使用系统默认值。有效值：

totalKeywordNum

（关键词总数）、

naturalKeywordNum

、

brandKeywordNum

、

vedioKeywordNum

、

acKeywordNum

、

erKeywordNum

、

trKeywordNum

、

sumScore

（所有关键词的总曝光量）、

totalNfScore

、

totalSpSocre

（注意拼写）、

totalBrandScore

、

totalVedioScore

、

totalAcScore

、

totalTrScore

、

totalErScore

。

调用方式

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

Python 脚本：

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

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

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

始终将完整响应写入
```
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sif-keyword-summary-<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 /sif/keywordSummary
```
（完整参数/响应/错误码见
```
references/api.md
```
）

Python 脚本：

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

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

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

始终将完整响应写入
```
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sif-keyword-summary-<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/套餐到期/需充值/请充值”或类似含义的内容。

Usage Examples

使用示例

1. Basic keyword traffic overview Query the traffic source breakdown for a keyword in the US marketplace:

searchKeyword: "wireless charger", country: "US"

2. Filter for organic search traffic only See only ASINs that appear in natural search results for a keyword:

searchKeyword: "wireless charger", country: "US", condition: "nfPosition"

3. Analyze SP ad competition Find which ASINs are running SP ads for a keyword:

searchKeyword: "wireless charger", country: "US", condition: "isSpAd"

4. SP recommendation slots Find ASINs surfacing in SP recommendation slots (Trending now, Customers frequently viewed, etc.):

searchKeyword: "wireless charger", country: "US", condition: "acAd"

5. Keyword analysis for a non-US marketplace Analyze traffic sources in the Japan marketplace (use the local language keyword):

searchKeyword: "ワイヤレス充電器", country: "JP"

6. Focus on specific competitor ASINs Limit results to a small set of competing ASINs:

searchKeyword: "wireless charger", country: "US", asins: "B01NBNDC1T,B09VLJJPL6"

7. Custom date range

searchKeyword: "wireless charger", country: "US", last7d: false, startDate: "2026-04-05", endDate: "2026-04-11"

8. Rank ASINs by their overall SP exposure

searchKeyword: "wireless charger", country: "US", sortBy: "totalSpSocre", desc: true

9. Newly-entered traffic keywords this period

searchKeyword: "wireless charger", country: "US", condition: "totalPeriod.in"

1. 基础关键词流量概览 查询美国站点某关键词的流量来源拆解：

searchKeyword: "wireless charger", country: "US"

2. 仅筛选自然搜索流量 查看该关键词下仅出现在自然搜索结果中的ASIN：

searchKeyword: "wireless charger", country: "US", condition: "nfPosition"

3. 分析SP广告竞争情况 找出哪些ASIN在该关键词下投放了SP广告：

searchKeyword: "wireless charger", country: "US", condition: "isSpAd"

4. SP推荐位分析 找出出现在SP推荐位（当下热门、客户常看等）的ASIN：

searchKeyword: "wireless charger", country: "US", condition: "acAd"

5. 非美国站点的关键词分析 分析日本站点的流量来源（需使用当地语言关键词）：

searchKeyword: "ワイヤレス充電器", country: "JP"

6. 聚焦特定竞品ASIN 将结果限定在少量竞品ASIN范围内：

searchKeyword: "wireless charger", country: "US", asins: "B01NBNDC1T,B09VLJJPL6"

7. 自定义日期范围

searchKeyword: "wireless charger", country: "US", last7d: false, startDate: "2026-04-05", endDate: "2026-04-11"

8. 按整体SP曝光量对ASIN排序

searchKeyword: "wireless charger", country: "US", sortBy: "totalSpSocre", desc: true

9. 本周期新增流量关键词

searchKeyword: "wireless charger", country: "US", condition: "totalPeriod.in"

Display Rules

展示规则

Present data clearly: Show query results in well-structured tables. Group data by traffic channel exposure ratios for easy comparison.
Distinguish product-level vs keyword-level scores: Do not mix
```
naturalSearchExposureScore
```
(product-wide) with
```
keywordNaturalExposureScore
```
(this keyword only). Label columns so users know which scope they are reading.
Highlight key ratios: When displaying results, emphasize the natural search exposure ratio vs. paid ad exposure ratio to help users quickly assess the organic-to-paid balance.
Translate field names: Present field names in user-friendly language rather than raw API field names (e.g., "Natural Search Exposure Ratio" instead of "naturalSearchExposureRatio").
Volume notice: When results are large (high total count), show core data and remind users they can paginate to see more results.
Period annotation: When comparing exposure/counts, label the resolved window — default
```
last7d
```
; or
```
startDate ~ endDate
```
if a custom range was set. Also surface
```
dataPeriodStartDate
```
on each row.
Error handling: When a query fails, explain the reason based on the
```
msg
```
field and suggest adjusting query parameters (e.g., checking keyword spelling or marketplace code).
Percentage formatting: Display exposure ratios as percentages (e.g., 0.45 as "45%") for readability.
Traffic source summary: When presenting a single ASIN's data, provide a brief traffic composition summary (e.g., "This product gets 60% of its exposure from organic search, 25% from SP ads, and 15% from brand ads"); prefer keyword-level fields when the user asks specifically about this keyword.

清晰呈现数据：使用结构清晰的表格展示查询结果。按流量渠道曝光占比分组，便于对比。
区分产品层面与关键词层面评分：请勿混淆
```
naturalSearchExposureScore
```
（全产品范围）与
```
keywordNaturalExposureScore
```
（仅当前关键词）。为列添加标签，让用户清楚了解数据范围。
突出关键占比：展示结果时，强调自然搜索曝光占比与付费广告曝光占比，帮助用户快速评估自然流量与付费流量的平衡情况。
字段名称翻译：使用用户友好的语言展示字段名称，而非原始API字段名（例如，用“自然搜索曝光占比”代替“naturalSearchExposureRatio”）。
数据量提示：当结果数量较多（总计数较高）时，展示核心数据并提醒用户可分页查看更多结果。
周期标注：对比曝光量/计数时，标注解析的时间窗口——默认是
```
last7d
```
；若使用自定义范围则标注
```
startDate ~ endDate
```
。同时需显示每行的
```
dataPeriodStartDate
```
。
错误处理：查询失败时，根据
```
msg
```
字段解释原因并建议调整查询参数（例如，检查关键词拼写或站点代码）。
百分比格式：将曝光占比以百分比形式展示（例如，0.45显示为“45%”），提升可读性。
流量来源汇总：展示单个ASIN的数据时，提供简要的流量构成总结（例如，“该产品60%的曝光来自自然搜索，25%来自SP广告，15%来自品牌广告”）；当用户明确询问当前关键词时，优先使用关键词层面的字段。

Important Limitations

重要限制

Single condition filter: Only one
```
condition
```
value can be used per request. To compare multiple traffic sources, make separate requests.
Marketplace coverage: 13 marketplaces only — IN / NL / SE / PL / TR / SG are no longer available.
Keyword language: The
```
searchKeyword
```
should be in the language of the target marketplace for best results.
Result cap: Each page returns at most 100 records.
Scope: This endpoint focuses on per-keyword ASIN traffic; it does not return whole-ASIN metadata, cross-channel keyword counts, or variant aggregation. Use the ASIN traffic-source tool for those.

单一条件筛选：每次请求仅能使用一个
```
condition
```
值。如需对比多个流量来源，请发起单独请求。
站点覆盖范围：仅支持13个站点——IN/NL/SE/PL/TR/SG不再可用。
关键词语言：
```
searchKeyword
```
应使用目标站点的语言，以获得最佳结果。
结果上限：每页最多返回100条记录。
范围限制：该端点专注于单个关键词下的ASIN流量分析；不返回ASIN的完整元数据、跨渠道关键词计数或变体聚合。如需这些功能，请使用ASIN流量来源工具。

User Expression & Scenario Quick Reference

用户表述与场景速查

Applicable — Traffic source and competition structure analysis for Amazon keywords:

User Says	Scenario
"Where does the traffic come from for this keyword"	Traffic source breakdown
"How much organic vs paid traffic"	Organic/paid ratio analysis
"Who's running SP ads for this keyword"	SP ad competition analysis ( `condition=isSpAd` )
"Which products are in SP recommendation slots"	SP recommendation lookup ( `condition=acAd` )
"Which products have Amazon's Choice"	AC badge analysis (via `amazonsChoiceExposureScore` )
"Is this keyword dominated by ads"	Ad saturation assessment
"Show me the brand ad competition"	Brand ad landscape analysis
"Traffic structure for my competitor's keyword"	Competitive traffic analysis
"Which products get editorial recommendations"	ER placement analysis
"Compare these 2 ASINs on this keyword"	ASIN filter via `asins="B0A,B0B"`
"For the week of March 8, traffic under this keyword"	Custom `startDate` / `endDate` window
"Newly-entered traffic keywords this period"	New-in filter ( `condition=totalPeriod.in` )

Not applicable — Needs beyond keyword traffic source analysis:

Historical keyword ranking trends beyond current + custom window (use ABA data tools)
Advertising bid/budget optimization
Product reviews or listing content
Sales volume estimation
Full keyword search volume curve over time
Whole-ASIN traffic structure across all keywords (use the SIF ASIN traffic-source tool)

适用场景——亚马逊关键词的流量来源与竞争结构分析：

用户表述	场景
“这个关键词的流量来自哪里”	流量来源拆解
“自然流量和付费流量各占多少”	自然/付费占比分析
“哪些竞品在这个关键词上投放SP广告”	SP广告竞争分析（ `condition=isSpAd` ）
“哪些产品出现在SP推荐位”	SP推荐位查询（ `condition=acAd` ）
“哪些产品带有Amazon's Choice标识”	AC标识分析（通过 `amazonsChoiceExposureScore` ）
“这个关键词是否被广告主导”	广告饱和度评估
“展示品牌广告的竞争情况”	品牌广告格局分析
“竞品关键词的流量结构”	竞品流量分析
“哪些产品获得编辑推荐”	ER推荐位分析
“对比这两个ASIN在该关键词下的表现”	通过 `asins="B0A,B0B"` 筛选ASIN
“3月8日那周，这个关键词的流量情况”	自定义 `startDate` / `endDate` 时间窗口
“本周期新增的流量关键词”	新增筛选（ `condition=totalPeriod.in` ）

不适用场景——超出关键词流量来源分析的需求：

当前及自定义窗口之外的历史关键词排名趋势（使用ABA数据工具）
广告出价/预算优化
产品评论或listing内容
销量估算
关键词搜索量随时间变化的完整曲线
ASIN在所有关键词下的整体流量结构（使用SIF ASIN流量来源工具）

积分消耗规则

消耗 9 积分。

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

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.

消耗9积分。

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

反馈：

当出现以下任何情况时，通过反馈API自动检测并提交反馈：

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

按照

references/api.md

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

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