SimilarWeb 集成实战指南：在 marketingskills 中用 REST API 与零依赖 CLI 完成竞品流量情报分析

• AI 技能
• 人工智能

本指南系统讲解如何在 AI Agent 工作流中集成 SimilarWeb——面向网站流量情报的竞争情报平台，覆盖 API 能力边界、认证方式、12 个核心数据端点的调用方法与返回字段解析，并深入剖析仓库自带的零依赖 CLI（similarweb.js）的底层实现，让 Agent 可以直接完成竞品流量趋势、流量来源构成、有机/付费关键词、相似站点与地理分布等分析任务。读完本文，你将掌握在 Claude Code 等 Agent 环境中直接调用 SimilarWeb 数据、并与seo-audit、competitors、ads、content-strategy等营销技能联动完成竞品对标与市场调研的完整方案。

SimilarWeb 集成能力总览

SimilarWeb 是竞争性流量情报平台，核心价值在于提供任意网站的访问量分析（website analytics）、流量来源构成（traffic sources）、关键词数据（keyword data）与竞品洞察（competitor insights）。在 marketingskills 仓库的 工具注册表 中，它被归入Competitive Intelligence（竞争情报）类别，定位为"网站流量、竞品分析"的首选工具，官方推荐语为：Similarweb for competitor traffic analysis and market benchmarking（用于竞品流量分析与市场基准对标）。

仓库对该集成的支持能力矩阵如下（出自 集成指南）：

关键结论：SimilarWeb 仅提供 REST API，仓库通过自研 CLI 弥补了 Agent 场景下的调用缺口；由于无 MCP 支持，Agent 集成时优先走 CLI 或直接构造 HTTP 请求。

认证方式：API Key 查询参数

SimilarWeb 使用最简单的认证方式——API Key，作为查询参数直接附加在请求 URL 上：

• 类型：API Key
• 传递方式：查询参数?api_key={key}
• 获取位置：SimilarWeb 账户后台的 Account Settings > API 页面

在仓库的 CLI 实现 similarweb.js 中，API Key 通过环境变量SIMILARWEB_API_KEY读取，未设置时立即报错退出：

const API_KEY = process.env.SIMILARWEB_API_KEY const BASE_URL = 'https://api.similarweb.com/v1' if (!API_KEY) { console.error(JSON.stringify({ error: 'SIMILARWEB_API_KEY environment variable required' })) process.exit(1) }

这与 CLI 使用说明 中所有营销 CLI 的统一安全规范一致：凭据只从环境变量读取，绝不硬编码在脚本中。推荐的密钥管理方式是写入 shell 配置文件（~/.bashrc）或.env文件（该文件已被仓库 gitignore）。

请求 URL 的拼接逻辑在api()函数中完成，自动处理路径中是否已带查询参数的情况：

const separator = path.includes('?') ? '&' : '?' const url = `${BASE_URL}${path}${separator}api_key=${API_KEY}`

也就是说，无论你调用的端点路径是否已经带start_date等参数，CLI 都会正确追加api_key。

Common Agent Operations：Agent 最常用的 12 个数据端点

集成指南按"Agent 常用操作"组织了完整的端点清单。下面逐一给出请求结构与语义，这些命令均可直接复制使用（将example.com替换为目标域名、{key}替换为你的 API Key）。

流量与参与度指标（Traffic & Engagement）

总访问量（Total Visits）——统计期内目标站点的总访问次数，支持按国家与粒度聚合：

GET https://api.similarweb.com/v1/website/example.com/total-traffic-and-engagement/visits?api_key={key}&start_date=2024-01&end_date=2024-03&country=us&granularity=monthly

单次访问页数（Pages Per Visit）：

GET https://api.similarweb.com/v1/website/example.com/total-traffic-and-engagement/pages-per-visit?api_key={key}&start_date=2024-01&end_date=2024-03

平均访问时长（Average Visit Duration），返回单位是秒：

GET https://api.similarweb.com/v1/website/example.com/total-traffic-and-engagement/average-visit-duration?api_key={key}&start_date=2024-01&end_date=2024-03

跳出率（Bounce Rate），即单页访问占比：

GET https://api.similarweb.com/v1/website/example.com/total-traffic-and-engagement/bounce-rate?api_key={key}&start_date=2024-01&end_date=2024-03

流量来源（Traffic Sources）

流量来源构成总览（Traffic Sources Breakdown）——各渠道流量占比，是理解竞品获客结构的核心数据：

GET https://api.similarweb.com/v1/website/example.com/traffic-sources/overview?api_key={key}&start_date=2024-01&end_date=2024-03

热门引荐站点（Top Referral Sites）——带来流量的外部网站名单：

GET https://api.similarweb.com/v1/website/example.com/traffic-sources/referrals?api_key={key}&start_date=2024-01&end_date=2024-03

搜索关键词（Search Keywords）

有机关键词（Organic Keywords）——竞品从自然搜索获得流量的关键词列表：

GET https://api.similarweb.com/v1/website/example.com/search/organic-search-keywords?api_key={key}&start_date=2024-01&end_date=2024-03

付费关键词（Paid Keywords）——竞品正在投放的付费搜索关键词：

GET https://api.similarweb.com/v1/website/example.com/search/paid-search-keywords?api_key={key}&start_date=2024-01&end_date=2024-03

竞品与品类（Competitors & Category）

相似站点/竞品列表（Similar Sites / Competitors）——与目标站点最相似的其他网站，用于界定竞争格局：

GET https://api.similarweb.com/v1/website/example.com/similar-sites/similarsites?api_key={key}

品类排名（Category Ranking）——目标站点在其行业分类中的排名位置：

GET https://api.similarweb.com/v1/website/example.com/category-rank/category-rank?api_key={key}

地理分布（Geography）

按国家流量分布（Traffic by Country）——流量来源国的占比构成：

GET https://api.similarweb.com/v1/website/example.com/geo/traffic-by-country?api_key={key}&start_date=2024-01&end_date=2024-03

注意：similarsites与category-rank两个端点不需要时间范围参数，其余端点均要求start_date与end_date。

使用仓库 CLI 执行同类操作

上述 12 个端点全部被封装进仓库自带的 similarweb.js 中，采用统一的命令模式{tool} <resource> <action> [options]。CLI 为零依赖单文件 Node.js 脚本（Node 18+，使用原生fetch），无需npm install，可直接运行或软链到 PATH。

安装与运行方式

根据 CLI 使用说明，有三种使用方式：

# 方式一：直接运行 node tools/clis/similarweb.js traffic visits --domain example.com --start 2024-01 --end 2024-03 # 方式二：软链到全局 ln -sf "$(pwd)/tools/clis/similarweb.js" ~/.local/bin/similarweb similarweb search keywords-organic --domain example.com --start 2024-01 --end 2024-03 # 方式三：加入 PATH export PATH="$PATH:/path/to/marketingskills/tools/clis"

命令全景与参数校验

从源码main()的 switch 分支可梳理出完整的命令树（源码中default分支还内置了完整的 usage 帮助信息）：

每个子命令在发起请求前都会做参数校验（如visits分支中的三段式检查）：

case 'visits': { const domain = args.domain if (!domain) { result = { error: '--domain required' }; break } if (!args.start) { result = { error: '--start required (YYYY-MM)' }; break } if (!args.end) { result = { error: '--end required (YYYY-MM)' }; break } const params = new URLSearchParams({ start_date: args.start, end_date: args.end }) if (args.country) params.set('country', args.country) if (args.granularity) params.set('granularity', args.granularity) result = await api('GET', `/website/${encodeURIComponent(domain)}/total-traffic-and-engagement/visits?${params.toString()}`) break }

值得注意的实现细节：

• 域名自动编码：encodeURIComponent(domain)保证特殊字符域名不会破坏 URL 结构；
• 可选参数按需注入：--country、--granularity、--limit仅在显式传入时才加入查询串，不传则使用 API 默认行为；
• 统一 JSON 输出：所有结果经JSON.stringify(result, null, 2)输出到 stdout，可直接用jq解析或重定向保存：

  node tools/clis/similarweb.js search keywords-organic --domain example.com --start 2024-01 --end 2024-03 | jq '.organic_search_keywords[].search_term'

dry-run 预演模式：安全调试

CLI 支持--dry-run参数，用于预览将要发出的请求而不真正调用 API（credentials 会被掩码为***）。源码实现位于api()函数：

if (args['dry-run']) { return { _dry_run: true, method, url: url.replace(API_KEY, '***'), headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' }, body: body || undefined } }

这是 CLI 使用说明 中统一强调的安全调试手段：在任何真正消耗配额的请求之前，先用 dry-run 检查 URL 拼装是否正确、参数是否到位。由于 SimilarWeb 部分端点按调用计费，先 dry-run 后实调是成本控制的好习惯。

关键指标字段解析

理解 API 返回的指标字段，是正确解读竞品数据的前提。集成指南按四类给出了字段语义：

Traffic & Engagement（流量与参与度）

Traffic Sources（流量来源构成）

这组字段是判断竞品增长引擎的关键：若竞品search占比高，说明其依赖内容/SEO 获客；display_ads占比高则表明其在大力投放品牌广告，往往与融资扩张期相关。

Search Keywords（搜索关键词）

Geography（地理分布）

参数说明

公共参数（Common Parameters）

搜索类参数（Search Parameters）

在 CLI 中，--limit参数仅对search命令生效（源码中只有keywords-organic与keywords-paid分支读取args.limit），--granularity仅对四个流量参与度命令生效，这与 API 的端点能力一一对应。

使用场景与技能联动

集成指南明确了 SimilarWeb 在营销工作流中的 8 类典型场景：

• 分析竞品网站流量与参与度指标（Analyzing competitor website traffic and engagement metrics）
• 将自有站点与竞品做基准对标（Benchmarking your site against competitors）
• 识别任意网站的头部流量来源（Identifying top traffic sources for any website）
• 挖掘竞品有机/付费关键词（Discovering competitor organic and paid keywords）
• 发现相似站点、勾勒竞争格局（Finding similar sites and competitive landscape）
• 理解流量地理分布（Understanding geographic traffic distribution）
• 相对竞品审计自身 SEO 表现（Auditing SEO performance relative to competitors）
• 按流量规模研究市场份额（Researching market share by traffic volume）

指南还给出了与该集成联动最紧密的四个技能：

• seo-audit：用竞品流量与关键词数据反推自身 SEO 差距，识别关键词覆盖盲区；
• competitors：生成竞品对比页/替代方案页前，用 SimilarWeb 流量数据验证"竞品候选名单"与竞争格局（配合similarsites端点发现潜在竞品）；
• ads：从竞品paid-search-keywords与display_ads占比判断其投放策略，为自有投放做反向参考；
• content-strategy：依据竞品organic-search-keywords与引荐来源规划内容选题与内容分发渠道。

一个典型的 Agent 工作流示例：先用competitors命令获取相似站点，再对每个站点依次调用traffic visits、traffic sources、search keywords-organic，汇总成竞品流量档案，最后交由competitors技能生成结构化对比页——全程只需 CLI 的 JSON 输出与jq即可完成数据管道。

速率限制与计划限制

使用 SimilarWeb API 前必须了解其限流与数据可用性边界（见 集成指南）：

• 限流按套餐分级：不同套餐的请求速率上限不同；
• 标准套餐基准：10 次请求/秒；
• 历史数据深度受套餐约束：可查询的历史范围从 3 个月到 36 个月不等；
• 端点分级：部分端点（如某些高级搜索/地理端点）需要 Premium 或 Enterprise 套餐才能访问。

实战提示：在 Agent 批量分析多个域名时，应在 CLI 调用之间加入节流（如每个域名间隔 100ms 以上），避免触碰每秒 10 次的硬限制；同时优先从套餐支持的时间窗内取数，防止因历史深度不足导致 4xx 错误。

小结

SimilarWeb 集成是 marketingskills 竞争情报能力的关键一环：API 层提供五类数据端点，CLI 层通过 similarweb.js 提供零依赖、环境变量认证、dry-run 调试、统一 JSON 输出的 Agent 友好封装，再配合 seo-audit、competitors、ads、content-strategy 四个技能，即可在 Claude Code 等环境中完成从"竞品流量画像"到"SEO/投放策略输出"的闭环。接入时只需记住三件事：设置SIMILARWEB_API_KEY环境变量、按{tool} <resource> <action> [options]模式调用、留意套餐限流与数据深度边界。

• AI 技能
• 人工智能