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 用户商品数据查询，支持多维度筛选（销量、价格、收藏、评论等）、排序与分页。 每条返回商品将消耗对应的 API 积分。
- 接口类型：REST API
- 请求方式：POST
- 数据格式：JSON
- 鉴权方式：API Key
- 适用用户：VIP / 订阅用户
接口地址
鉴权说明
请求需在 Header 中携带 API Key：
X-VIP-TOKEN: your_api_key_here
请求参数
请求体（JSON）
{
"search_key": "string",
"status": 1,
"category": "string",
"price": "20~100",
"sales_weekly": "10~100",
"sales": "100~1000",
"favorites": "50~500",
"favorites_weekly": "5~50",
"reviews": "10~200",
"reviews_weekly": "1~20",
"product_type": "1,2",
"is_raving": 0,
"is_pick": 0,
"is_bestsell": 0,
"listed_time": "2024-01-01",
"country": "US",
"currency_code": "USD",
"sort_by": 1,
"desc": 1,
"page_num": 1,
"page_size": 20
}
参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|
| search_key | string | 否 | 搜索关键词或 Etsy 商品 URL |
| status | int | 否 | 商品状态：1=上架，0=下架 |
| category | string | 否 | 商品分类ID，仅支持单品类
详情见商品分类接口 |
| price | string | 否 | 价格范围，如 20~100 |
| sales_weekly | string | 否 | 周销量范围，例如：1~100 |
| sales | string | 否 | 总销量范围，例如：1~100 |
| favorites | string | 否 | 收藏数范围，例如：1~100 |
| favorites_weekly | string | 否 | 周新增收藏数范围，例如：1~100 |
| reviews | string | 否 | 评论数范围，例如：1~100 |
| reviews_weekly | string | 否 | 周新增评论数范围，例如：1~100 |
| product_type | string | 否 | 商品类型，多个用逗号分隔。
1=手工
2=复古
3=数字
4=定制
9=其他 |
| is_raving | int | 否 | 是否 Raving 商品：1=是 |
| is_pick | int | 否 | 是否 Pick 商品：1=是 |
| is_bestsell | int | 否 | 是否畅销商品：1=是 |
| listed_time | string | 否 | 上架时间（YYYY-MM-DD） |
| country | string | 否 | 发货国家 |
| currency_code | string | 否 | 货币代码，默认 USD |
| sort_by | int | 否 | 排序字段（1~6） |
| desc | int | 否 | 排序方向：1=降序，2=升序 |
| page_num | int | 否 | 页码，从 1 开始 |
| page_size | int | 否 | 每页数量，最大 100 |
请求示例
curl -X POST https://api.example.com/api/v1/items \
-H "Content-Type: application/json" \
-H "X-VIP-TOKEN: your_api_key_here" \
-d '{
"search_key": "wedding ring",
"page_num": 1,
"page_size": 20
}'
返回结果
返回示例
{
"code": 0,
"message": "success",
"data": {
"product_num": 2345,
"page_size": 20,
"final_count": 20,
"list": [
{
"title": "Gold Wedding Ring",
"category": "Jewelry",
"price": 89.99,
"status": 1,
"sales_weekly": 32,
"sales_total": 1200,
"reviews": 320,
"favorites": 540,
"is_bestsell": 1,
"is_pick": 0,
"is_raving": 1,
"tags": "ring, wedding, gold",
"ships_from": "US",
"release_time": "2024-01-01",
"store_name": "BestJewelryShop",
"product_url": "https://www.etsy.com/listing/xxx",
"logo_url": "https://image.xxx/logo.png",
"reviews_weekly": 5,
"favorites_weekly": 12
}
]
},
"used_today": 120,
"remaining_today": 880
}
返回字段说明
| 字段名 | 类型 | 说明 |
|---|
| product_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,
"sales": "100~",
"is_bestsell": 1,
"sort_by": 4,
"desc": 1,
"page_size": 20
}
2. 查询下架的高销量商品（竞品分析）
{
"search_key": "",
"status": 0,
"sales": "1000~",
"sort_by": 4,
"desc": 1,
"page_size": 20
}
3. 查询特定时间段上架的商品
{
"search_key": "handmade",
"status": 1,
"listed_time": "2025-12-15~2026-01-15",
"sort_by": 2,
"desc": 1,
"page_size": 20
}
注意事项
- page_size 建议不超过 50，以避免不必要的积分消耗
- 复杂筛选条件可能影响接口响应时间
- 接口返回数据仅供分析参考，不构成商业保证
更新时间：2026-05-15
维护方：EHunt API Team