linkfox-google-trend-get-trend-by-keys

Google Trends 关键词趋势分析

此技能将指导你如何查询和分析 Google Trends 关键词搜索兴趣数据，帮助用户了解关键词热度如何随时间在不同地区变化。

核心概念

Google Trends 提供经过标准化的搜索兴趣数据（0-100 分），反映给定搜索词在所选地区和时间范围内相对于其热度峰值的受欢迎程度。数值为 100 表示热度峰值，50 表示该词的热度为峰值的一半，0 表示数据不足。

重要的语言规则：关键词必须使用目标国家的语言。例如，美国使用英语关键词，德国使用德语关键词，日本使用日语关键词。如果用户提供的关键词语言不正确，请在查询前先翻译。

参数

参数	类型	必填	说明
keyword	字符串	是	要分析的搜索关键词（最多 100 个字符）。必须使用目标国家的语言。
region	字符串	否	国家/地区代码。默认为 US。
dayRangeStart	字符串	否	时间范围的开始日期（格式：YYYY-MM-DD，自 2004 年起）。
dayRangeEnd	字符串	否	时间范围的结束日期（格式：YYYY-MM-DD，自 2004 年起）。

同时提供 dayRangeStart 和 dayRangeEnd 时，优先使用自定义时间范围。

支持的地区

US（美国）、GB（英国）、JP（日本）、CA（加拿大）、MX（墨西哥）、DE（德国）、FR（法国）、IT（意大利）、ES（西班牙）、NL（荷兰）、AU（澳大利亚）、SG（新加坡）、AE（阿联酋）、BR（巴西）、IN（印度）、TR（土耳其）、PL（波兰）、SE（瑞典）

默认地区为 US。用户未指定地区时使用 US。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-google-trend-get-trend-by-keys-<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. 使用正确的语言：始终确保关键词与目标地区的语言一致。必要时先翻译。
2. 指定地区：默认地区为 US，但始终确认用户预期的市场。
3. 使用日期范围进行聚焦分析：针对季节性趋势或特定事件分析，请提供 dayRangeStart 和 dayRangeEnd。
4. 关键词保持简洁：Google Trends 最适合短小、聚焦的搜索词。

使用示例

1. 基本关键词趋势（默认地区和时间）

{"keyword": "wireless charger"}

查询美国“wireless charger”的整体搜索兴趣趋势。

2. 查询特定地区的关键词趋势

{"keyword": "Ladekabel", "region": "DE"}

查询德国“Ladekabel”（充电线）的搜索兴趣。

3. 自定义日期范围分析

{"keyword": "christmas gifts", "region": "US", "dayRangeStart": "2024-09-01", "dayRangeEnd": "2025-01-31"}

分析美国“christmas gifts”从 2024 年 9 月到 2025 年 1 月的季节性趋势。

4. 年度对比

{"keyword": "sunscreen", "region": "AU", "dayRangeStart": "2023-01-01", "dayRangeEnd": "2025-12-31"}

比较澳大利亚“sunscreen”的多年季节性趋势。

5. 区域市场研究

{"keyword": "yoga mat", "region": "GB"}

查看英国“yoga mat”的热度趋势。

6. 新兴趋势检测

{"keyword": "AI glasses", "region": "US", "dayRangeStart": "2024-01-01", "dayRangeEnd": "2025-12-31"}

追踪过去两年美国“AI glasses”的搜索兴趣增长情况。

展示规则

1. 清晰呈现数据：使用格式清晰的表格展示趋势数据，或描述趋势曲线。包含峰值、低谷和显著变化等关键数据点。
2. 说明数值范围：提醒用户，Google Trends 的数值采用 0-100 标准化尺度，其中 100 表示所选范围内的最高热度。
3. 突出趋势模式：指出数据中可见的季节性模式、突然飙升或持续增长／下降。
4. 图表数据可用性：当响应包含 chartOption 时，说明可提供可视化数据，并描述趋势形态。
5. 错误处理：查询失败时，说明原因并建议调整方式（例如检查关键词拼写、尝试不同的日期范围、确认关键词使用了正确的语言）。

重要限制

• 数据分析：响应为 JSON。请读取已保存响应中的 trendInfoForKeys[].trendValues[]；保留 timeRange 以及 "<1" 等数值，不要将其转换为零。_dataQuery_executeDynamicQuery 查询的是存储在 SLS 中的 Linkfox 会话数据，而不是任意 JSON 文件；只有在存在所需的存储数据映射时才使用它。
• 标准化数值：趋势数值为相对值（0-100），并非绝对搜索量。
• 数据可用性：数据自 2004 年起提供，但非常冷门的词可能只有稀疏数据。
• 每次调用一个关键词：每次 API 调用处理一个关键词。要比较多个关键词，请分别调用并比较结果。
• 语言要求：关键词必须符合目标地区所用的语言，才能获得准确结果。

用户表达与场景速查

适用 -- 查询关键词搜索热度趋势：

用户表达	场景
“XX 关键词在 Google 上有多热门？”	基本趋势查询
“XX 的趋势是在上升还是下降？”	趋势方向分析
“XX 的搜索量何时达到峰值？”	季节性峰值检测
“比较 XX 在不同月份的热度”	季节性模式分析
“XX 在德国的热度是否正在上升？”	区域趋势查询
“过去一年 XX 的搜索趋势如何？”	历史趋势分析
“XX 的节日搜索趋势”	季节性／事件驱动分析

不适用 -- 需求超出 Google Trends 搜索兴趣数据范围：

• Google Ads 关键词规划师或出价／CPC 数据
• 绝对搜索量（Google Trends 提供的是相对数据，而非绝对数据）
• 社交媒体热门话题（Twitter/X、TikTok 等）
• Amazon 专属搜索词数据（请改用 ABA Data Explorer）
• 网站流量分析（Google Analytics、SimilarWeb 等）
• 搜索引擎结果页上的关键词排名（SEO 排名跟踪）

边界判断：当用户提到“关键词研究”或“市场趋势分析”时，如果具体指从 Google 的角度分析一段时间内的搜索兴趣热度，则适用此技能。如果用户需要绝对流量数据、广告指标或特定电商平台的数据，则不适用。

算力消耗规则

消耗 6 算力。

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

反馈：

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

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

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

---

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