Hermes Analysis

Hermes 数据分析 Skill (V2)

基于 Hermes V2 API 的亚马逊卖家数据分析工具。支持市场评估、产品搜索、竞品分析、实时数据获取。

快速开始

1. 获取 API Token

1. 访问 Hermes 开发者平台 注册账号
2. 登录后进入 API Keys 页面，创建新 Token
3. 复制生成的 hms_live_xxx 格式的 Token

2. 配置 Token

将 Token 设置为环境变量：

# macOS/Linux — 添加到 ~/.zshrc 或 ~/.bashrc
export HERMES_API_TOKEN="hms_live_your_token_here"

# 或在 Claude Code 项目中配置 .env 文件
echo 'HERMES_API_TOKEN=hms_live_your_token_here' >> .env

3. 验证

在 Claude Code 中输入：「分析 Throw Pillow Covers 市场」，确认 API 调用正常。

API 配置

调用模板（所有接口通用）：

curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/{endpoint}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{...}'

通用响应结构：

{
  "success": true,
  "data": [...],
  "error": null,
  "meta": {
    "requestId": "xxx",
    "timestamp": "2026-01-01T00:00:00Z",
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

接口参考

1. categories — 类目搜索

端点： POST /openapi/v2/categories

查询亚马逊类目层级。支持按关键词搜索、按路径查询、按父类目获取子类目。5 种查询模式互斥，每次只用一种。

请求参数：

响应字段（Category）：

调用示例：

# 搜索"pillow"相关类目
curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/categories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{"categoryKeyword": "pillow", "marketplace": "US"}'

# 获取某类目的子类目
curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/categories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{"parentCategoryPath": ["Home & Kitchen", "Bedding"], "marketplace": "US"}'

2. markets/search — 市场数据

端点： POST /openapi/v2/markets/search

按类目获取市场聚合数据，包含销量、价格、集中度、品牌数等指标。用于市场可行性评估。

请求参数：

sortBy 枚举值： totalSkuCnt, sampleSkuCnt, sampleAvgPrice, sampleAvgMonthlySaleCnt, sampleAvgMonthlySaleAmt, sampleAvgBigCategoryBsr, sampleAvgRatingAmt, sampleAvgRatingCnt, sampleAvgGrossMarginRate, sampleBrandCnt, sampleSellerCnt, sampleFbaSkuRate, sampleNewSkuRate, topAvgMonthlySaleCnt, topAvgMonthlySaleAmt, topSaleCntRate, topBrandSaleCntRate, topSellerSaleCntRate

响应字段（MarketDTOV2）：

集中度指标说明：

• topSalesRate：Top N 产品销量占总样本销量的比例。越高 = 市场越集中，新卖家进入越难
• topBrandSalesRate：Top N 品牌销量占比。越高 = 品牌垄断越强
• topSellerSalesRate：Top N 卖家销量占比。越高 = 卖家集中度越高

调用示例：

# 查询 Throw Pillow Covers 市场数据
curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/markets/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{
    "categoryPath": ["Home & Kitchen", "Bedding", "Pillow Covers"],
    "topN": "10",
    "marketplace": "US"
  }'

3. products/search — 产品搜索

端点： POST /openapi/v2/products/search

按关键词和筛选条件搜索产品。支持丰富的过滤和排序。

请求参数：

sortBy 枚举值： monthlySales, monthlyRevenue, bsr, price, rating, reviewCount, listingDate

响应字段（ProductDTOV2）：

调用示例：

# 搜索 throw pillow covers，按月销量排序
curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/products/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{
    "keyword": "throw pillow covers",
    "sortBy": "monthlySales",
    "sortOrder": "desc",
    "pageSize": 50,
    "marketplace": "US"
  }'

4. products/competitor-lookup — 竞品查询

端点： POST /openapi/v2/products/competitor-lookup

按关键词、品牌、ASIN 或卖家查找竞品。返回与 products/search 相同的产品结构。

请求参数：

响应： 与 products/search 完全相同（ProductDTOV2 列表）。

调用示例：

# 查找某品牌的竞品
curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/products/competitor-lookup" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{"brand": "MIULEE", "marketplace": "US", "pageSize": 20}'

# 查找某 ASIN 的竞品
curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/products/competitor-lookup" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{"asin": "B07XXXXXX", "marketplace": "US"}'

5. realtime/product — 实时产品数据

端点： POST /openapi/v2/realtime/product

获取亚马逊产品的实时详情，包括评论、变体、BSR、图片等。数据实时抓取，响应较慢（5-15秒）。

请求参数：

响应字段（RealtimeProductDTO）：

调用示例：

curl -s -X POST "https://hermes.spider.yesy.dev/openapi/v2/realtime/product" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${HERMES_API_TOKEN}" \
  -d '{"asin": "B0CXXXXXX", "marketplace": "US"}'

分析流程

以下是基于 5 个接口组合使用的标准分析流程。根据用户需求选择合适的流程。

流程 1：市场可行性验证

适用场景：用户想了解某个品类/关键词的市场情况，判断是否值得进入

Step 1 — 类目定位 调用 categories（categoryKeyword）→ 获取 categoryPath，确认目标类目

Step 2 — 市场指标 调用 markets/search（categoryPath, topN:"10"）→ 获取市场聚合数据

Step 3 — 头部产品分析 调用 products/search（keyword, sortBy:monthlySales, pageSize:50）→ 查看头部产品

分析要点：

• 市场容量：sampleTotalMonthlySales、totalSkuCount
• 竞争强度：topSalesRate、topBrandSalesRate、topSellerSalesRate
• 进入门槛：sampleAvgReviewCount、sampleAvgRating
• 利润空间：sampleAvgGrossMargin、sampleAvgPrice
• 新品机会：sampleNewSkuRate、sampleNewSkuCount

流程 2：ASIN 深度分析

适用场景：用户有具体的 ASIN，想深入了解该产品

Step 1 — 实时数据 调用 realtime/product（asin）→ 获取评论、变体、BSR、图片等详情

Step 2 — 竞品对比 调用 products/competitor-lookup（asin）→ 找到该 ASIN 的竞品

Step 3 — 关键词表现（可选） 调用 products/search（keyword:产品相关关键词）→ 查看该关键词下的排名

流程 3：竞品研究

适用场景：用户想了解某品牌/卖家/关键词的竞品格局

Step 1 — 竞品查找 调用 products/competitor-lookup（keyword/asin/brand/seller）→ 竞品列表

Step 2 — 头部竞品详情（可选） 对 Top 3-5 竞品调用 realtime/product → 获取详情

流程 4：定价与利润分析

适用场景：帮助用户制定定价策略

Step 1 — 类目均价 调用 markets/search（categoryPath）→ sampleAvgPrice、sampleAvgGrossMargin

Step 2 — 价格带分布 调用 products/search（keyword, sortBy:monthlySales, pageSize:100）→ 统计各价格区间的产品数和销量

分析要点：

• 将产品按价格分段，统计每段的产品数量和平均月销量
• 找到"高销量 + 合理价格"的甜蜜区间
• 对比 FBA 费用和毛利率

流程 5：子类目扫描

适用场景：用户想在某个大类下找细分机会

Step 1 — 获取子类目 调用 categories（parentCategoryPath）→ 子类目列表

Step 2 — 批量市场数据 对每个子类目调用 markets/search → 获取各子类目的市场指标

Step 3 — 对比排序 按市场容量、竞争度、新品率等维度对子类目排序，找到最优细分

评估标准

市场健康度评估

产品潜力评估

注意事项

1. 站点支持：products/search、markets/search、competitor-lookup 仅支持 US 和 UK；realtime/product 支持 12 个站点
2. 响应时间：realtime/product 需要实时抓取，响应时间 5-15 秒；其他接口通常 1-3 秒
3. 分页限制：pageSize 最大 100，大量数据需要翻页
4. categoryPath 格式：必须是字符串数组，如 ["Home & Kitchen", "Bedding", "Pillowcases"]
5. 数据精度：销量和收入为估算值，仅供参考
6. 调用频率：避免短时间内大量调用，合理使用分页
7. 错误处理：检查响应中的 success 字段和 error 对象