Skip to main content

​
VIP 商品查询接口（Items Query API）

​
接口概述

该接口用于 VIP 用户商品数据查询，支持多维度筛选（销量、价格、收藏、评论等）、排序与分页。 每条返回商品将消耗对应的 API 积分。
  • 接口类型：REST API
  • 请求方式：POST
  • 数据格式：JSON
  • 鉴权方式：API Key
  • 适用用户：VIP / 订阅用户

​
接口地址

POST /api/vi/items

​
鉴权说明

请求需在 Header 中携带 API Key： 
X-API-Key: your_api_key_here
若 API Key 无效、过期或无订阅权限，将返回错误响应。

​
请求参数

​
请求体（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": "digital,physical",
  "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_keystring否搜索关键词或 Etsy 商品 URL
statusint否商品状态：1=上架，0=下架
categorystring否商品分类
pricestring否价格范围，如 20~100
sales_weeklystring否周销量范围
salesstring否总销量范围
favoritesstring否收藏数范围
favorites_weeklystring否周新增收藏数范围
reviewsstring否评论数范围
reviews_weeklystring否周新增评论数范围
product_typestring否商品类型，多个用逗号分隔
is_ravingint否是否 Raving 商品：1=是
is_pickint否是否 Pick 商品：1=是
is_bestsellint否是否畅销商品：1=是
listed_timestring否上架时间（YYYY-MM-DD）
countrystring否发货国家
currency_codestring否货币代码，默认 USD
sort_byint否排序字段（1~6）
descint否排序方向：1=降序，0=升序
page_numint否页码，从 1 开始
page_sizeint否每页数量，最大 100

​
请求示例

curl -X POST https://api.example.com/api/vi/items \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "search_key": "wedding ring",
    "page_num": 1,
    "page_size": 20
  }'

​
返回结果

​
返回示例

Response
{
  "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_numint符合条件的商品总数
page_sizeint每页数量
final_countint当前页返回数量
listarray商品数据列表
used_todayint今日已使用积分
remaining_todayint今日剩余积分

​
积分消耗规则

- 每返回 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-01-14
维护方：EHunt API Team