Documentation Index
Fetch the complete documentation index at: https://docs.api.ehunt.ai/llms.txt
Use this file to discover all available pages before exploring further.
接口概述
该接口用于 VIP 用户进行 Etsy 店铺数据查询，支持按销量、收藏、评论、国家、分类等多条件筛选，并支持排序与分页。 每条返回店铺将消耗对应的 API 积分。
- 接口类型：REST API
- 请求方式：POST
- 数据格式：JSON
- 鉴权方式：API Key
- 适用用户：VIP / 订阅用户
接口地址
鉴权说明
请求 Header 中必须携带有效的 API Key：
X-VIP-TOKEN: your_api_key_here
请求参数
请求体（JSON）
{
"search_key": "jewelry",
"status": 1,
"country": "US",
"category": "String",
"sales_weekly": "10~100",
"sales": "100~5000",
"favorites": "50~2000",
"favorites_weekly": "5~200",
"reviews": "20~1000",
"reviews_weekly": "2~100",
"start_at": "2020-01-01~2023-01-01",
"is_star": 0,
"is_raving": 0,
"sort_by": 8,
"desc": 1,
"page_num": 1,
"page_size": 20
}
参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|
| search_key | string | 否 | 搜索关键词或店铺名称、店铺URL |
| status | int | 否 | 店铺状态：1=活跃，0=非活跃 |
| country | string | 否 | 店铺所在国家 |
| category | string | 否 | 店铺主营分类 |
| sales_weekly | string | 否 | 店铺周销量范围，例如：1~100 |
| sales | string | 否 | 店铺总销量范围 |
| favorites | string | 否 | 店铺收藏数范围，例如：1~100 |
| favorites_weekly | string | 否 | 店铺周新增收藏数 |
| reviews | string | 否 | 店铺评论数范围，例如：1~100 |
| reviews_weekly | string | 否 | 店铺周新增评论数 |
| start_at | string | 否 | 店铺开店时间区间（YYYY-MM-DD） |
| is_star | int | 否 | 是否星标店铺：1=是 |
| is_raving | int | 否 | 是否 Raving 店铺：1=是 |
| sort_by | int | 否 | 排序字段：8=总销量，9=周销量，10=评论数，11=收藏数 |
| desc | int | 否 | 排序方向：1=降序，0=升序 |
| page_num | int | 否 | 页码，从 1 开始 |
| page_size | int | 否 | 每页数量，最大 100 |
请求示例
curl -X POST https://api.example.com/api/v1/stores \
-H "Content-Type: application/json" \
-H "X-VIP-TOKEN: your_api_key_here" \
-d '{
"search_key": "jewelry",
"country": "US",
"page_num": 1,
"page_size": 20
}'
返回结果
返回示例
{
"code": 0,
"message": "success",
"data": {
"store_num": 1520,
"page_size": 20,
"final_count": 20,
"list": [
{
"store_id": "123456",
"store_name": "BestJewelryShop",
"logo_url": "https://image.xxx/logo.png",
"store_url": "https://www.etsy.com/shop/BestJewelryShop",
"status": 1,
"products": 320,
"start_at": "2019-06-01",
"sales_weekly": 120,
"sales_total": 5600,
"reviews": 980,
"reviews_weekly": 12,
"favorites": 3400,
"favorites_weekly": 45,
"is_star": 1,
"is_raving": 0,
"category": ["Jewelry"],
"rating": 4.8,
"country": ["US"],
"social_info": [],
"shop_badges": [],
"shop_website": "https://www.etsy.com/shop/BestJewelryShop"
}
]
},
"used_today": 80,
"remaining_today": 920
}
返回字段说明
| 字段名 | 类型 | 说明 |
|---|
| store_num | int | 符合条件的店铺总数 |
| page_size | int | 每页返回数量 |
| final_count | int | 当前页返回条数 |
| list | array | 店铺数据列表 |
| used_today | int | 今日已使用积分 |
| remaining_today | int | 今日剩余积分 |
积分消耗规则
- 每返回 1 条店铺数据,消耗 1 个积分
- 实际消耗积分 = final_count
- 当日积分不足将直接返回 429 错误
错误码说明
400 参数错误
401 API Key 无效或缺失
403 无订阅权限
429 今日调用额度已用尽
500 服务器内部错误
使用场景
- Etsy 店铺筛选与调研
- 高销量 / 高评分店铺挖掘
- 竞品店铺监控
- 市场规模与趋势分析
店铺查询场景
1. 查询星标优质店铺
{
"search_key": "",
"status": 1,
"is_star": 1,
"sales": "10000~",
"sort_by": 8,
"desc": 1,
"page_size": 20
}
2. 查询特定国家的新兴店铺
{
"search_key": "",
"status": 1,
"country": "US",
"sales_weekly": "100~",
"sort_by": 9,
"desc": 1,
"page_size": 20
}
3. 查询Raving店铺（高好评率）
{
"search_key": "",
"status": 1,
"is_raving": 1,
"reviews": "1000~",
"sort_by": 10,
"desc": 1,
"page_size": 20
}
注意事项
- 建议合理控制 page_size，避免不必要的积分消耗
- 多条件筛选可能增加查询耗时
- 返回数据来源于 Etsy 公开信息，仅供分析使用
更新时间：2026-05-15
维护方：EHunt API Team