brand-monitor

品牌监测

使用 Brand.dev API 跟踪品牌提及、分析情感倾向并发现公关机会。

前提条件

需要在 .env、.env.local 或 ~/.claude/.env.global 中设置 BRANDDEV_API_KEY。

echo "BRANDDEV_API_KEY is ${BRANDDEV_API_KEY:+set}"

如果未设置密钥，请告知用户：

你需要 Brand.dev API 密钥。请前往 https://brand.dev/ 获取。 然后将 BRANDDEV_API_KEY=your_key 添加到 .env 文件中。

API 基础地址

所有请求均发送至 https://api.brand.dev/v1/，并携带请求头 Authorization: Bearer {BRANDDEV_API_KEY}。

---

1. 品牌搜索

在全网搜索品牌名称的提及。

端点

GET https://api.brand.dev/v1/brand/search

参数

参数	类型	说明
query	字符串	要搜索的品牌名称或短语
limit	整数	结果数量（默认 20，最多 100）
offset	整数	分页偏移量
sort	字符串	relevance 或 date
from_date	字符串	开始日期（YYYY-MM-DD）
to_date	字符串	结束日期（YYYY-MM-DD）

curl 示例

curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  "https://api.brand.dev/v1/brand/search?query=YourBrand&limit=20&sort=date"

响应解析

curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  "https://api.brand.dev/v1/brand/search?query=YourBrand&limit=20" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for m in data.get('results', []):
    print(f\"Source: {m.get('source','')}  |  Title: {m.get('title','')}  |  Sentiment: {m.get('sentiment','n/a')}  |  Date: {m.get('published_at','')}\")
    print(f\"  URL: {m.get('url','')}\")
    print()
"

---

2. 品牌信息查询

获取任何公司或产品的结构化品牌信息。

端点

GET https://api.brand.dev/v1/brand/info

参数

参数	类型	说明
domain	字符串	公司域名（例如 stripe.com）
name	字符串	品牌名称（可替代 domain）

curl 示例

curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  "https://api.brand.dev/v1/brand/info?domain=stripe.com"

响应字段

• name：官方品牌名称
• domain：主域名
• description：品牌描述
• industry：行业分类
• founded：成立年份
• headquarters：所在地
• social_profiles：社交媒体链接
• logos：品牌 Logo URL
• colors：品牌配色方案
• employees_range：公司规模估算

---

3. Logo 检测

检测全网图片中的品牌 Logo。

端点

GET https://api.brand.dev/v1/logo/search

参数

参数	类型	说明
brand	字符串	要搜索的品牌名称
domain	字符串	限定特定域名
limit	整数	结果数量

curl 示例

curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  "https://api.brand.dev/v1/logo/search?brand=YourBrand&limit=20"

使用 Logo 检测查找：

• 未经授权使用 Logo 的情况
• 合作伙伴和赞助商的曝光情况
• 活动报道和媒体刊载情况
• 假冒产品列表

---

4. 提及跟踪

设置持续的品牌提及跟踪。

创建监测器

POST https://api.brand.dev/v1/monitors

请求正文

{
  "name": "My Brand Monitor",
  "keywords": ["YourBrand", "Your Brand", "yourbrand.com"],
  "exclude_keywords": ["unrelated term"],
  "sources": ["news", "blogs", "social", "forums", "reviews"],
  "languages": ["en"],
  "notify_email": "[email protected]"
}

curl 示例

curl -s -X POST -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  -H "Content-Type: application/json" \
  "https://api.brand.dev/v1/monitors" \
  -d '{
    "name": "Brand Alert",
    "keywords": ["YourBrand"],
    "sources": ["news", "blogs", "social"],
    "languages": ["en"]
  }'

列出监测器

curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  "https://api.brand.dev/v1/monitors"

获取监测器结果

curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  "https://api.brand.dev/v1/monitors/{monitor_id}/mentions?limit=50&sort=date"

---

5. 情感分析

分析品牌提及的情感倾向。

端点

GET https://api.brand.dev/v1/brand/sentiment

参数

参数	类型	说明
query	字符串	品牌名称
from_date	字符串	开始日期
to_date	字符串	结束日期
granularity	字符串	day、week 或 month

curl 示例

curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
  "https://api.brand.dev/v1/brand/sentiment?query=YourBrand&from_date=2024-01-01&to_date=2024-03-31&granularity=week"

情感评分

• 正面（> 0.3）：赞扬、推荐、好评
• 中性（-0.3 至 0.3）：事实性提及、新闻报道
• 负面（< -0.3）：投诉、批评、差评

---

6. 竞争对手提及对比

将品牌提及量和情感倾向与竞争对手进行对比。

工作流

1. 搜索你的品牌和每个竞争对手的提及
2. 对比相同时间段内的提及数量
3. 对比情感分布
4. 找出提及竞争对手但未提及你的来源

# For each brand, get mention counts
for brand in "YourBrand" "Competitor1" "Competitor2"; do
  count=$(curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
    "https://api.brand.dev/v1/brand/search?query=${brand}&limit=1" \
    | python3 -c "import json,sys; print(json.load(sys.stdin).get('total',0))")
  echo "${brand}: ${count} mentions"
done

---

工作流：完整品牌审查

收到全面品牌监测报告的请求时：

步骤 1：品牌信息

获取结构化品牌数据作为背景信息。

步骤 2：提及量

搜索过去 30/90 天内的品牌提及。统计提及总数，并按来源类型分类。

步骤 3：情感分析

获取情感趋势。标记任何负面峰值并调查其根本原因。

步骤 4：公关机会

根据提及数据，找出：

• 高权威网站：提及竞争对手但未提及你的品牌
• 记者：报道你所在行业的记者
• 热门话题：你的品牌可以参与讨论的话题
• 未解答的问题：论坛上有关你品牌但尚未得到解答的问题

步骤 5：Logo/视觉形象展示

搜索 Logo 的展示情况。标记未经授权的使用。

步骤 6：报告

按以下格式呈现调查结果：

## Brand Monitoring Report: {Brand}

### Overview
- Total mentions (last 30 days): X
- Sentiment breakdown: X% positive, X% neutral, X% negative
- Top sources: ...

### Sentiment Trend
[Weekly trend data]

### Top Positive Mentions
1. [Source] - [Title] - [URL]
2. ...

### Negative Mentions Requiring Attention
1. [Source] - [Title] - [URL] - [Issue summary]
2. ...

### PR Opportunities
1. [Publication] covers [topic] - pitch angle: ...
2. [Journalist] recently wrote about [topic] - pitch angle: ...

### Competitor Comparison
| Metric | Your Brand | Competitor A | Competitor B |
|--------|-----------|-------------|-------------|
| Mentions | ... | ... | ... |
| Positive % | ... | ... | ... |
| Top Source | ... | ... | ... |

### Action Items
- [ ] Respond to [negative mention]
- [ ] Pitch [publication] about [topic]
- [ ] Update brand listing on [platform]

---

错误处理

状态	含义
401	API 密钥无效或已过期
403	没有访问此端点的足够权限
404	未找到资源（检查监控 ID）
429	超出速率限制 — 请等待后重试
500	服务器错误 — 几秒后重试

提示

• 使用准确的品牌名称和常见拼写错误作为关键词
• 排除你自己的域名，避免匹配到自身提及
• 也为竞争对手品牌设置监控
• 至少每周检查一次提及；在发布或危机期间每天检查
• 将负面提及导出到电子表格，以便客户支持团队跟进