Skip to main content

​
VIP 店铺查询接口（Stores Query API）

​
接口概述

该接口用于 VIP 用户进行 Etsy 店铺数据查询，支持按销量、收藏、评论、国家、分类等多条件筛选，并支持排序与分页。 每条返回店铺将消耗对应的 API 积分。
  • 接口类型：REST API
  • 请求方式：POST
  • 数据格式：JSON
  • 鉴权方式：API Key
  • 适用用户：VIP / 订阅用户

​
接口地址

POST /api/v1/stores

​
鉴权说明

请求 Header 中必须携带有效的 API Key： 
X-API-Key: your_api_key_here
若 API Key 无效、未订阅或积分不足，将返回对应错误。

​
请求参数

​
请求体（JSON）

{
  "search_key": "jewelry",
  "status": 1,
  "country": "US",
  "category": "Jewelry",
  "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_keystring否搜索关键词或店铺名称
statusint否店铺状态：1=活跃，0=非活跃
countrystring否店铺所在国家
categorystring否店铺主营分类
sales_weeklystring否店铺周销量范围
salesstring否店铺总销量范围
favoritesstring否店铺收藏数范围
favorites_weeklystring否店铺周新增收藏数
reviewsstring否店铺评论数范围
reviews_weeklystring否店铺周新增评论数
start_atstring否店铺开店时间区间
is_starint否是否星标店铺：1=是
is_ravingint否是否 Raving 店铺：1=是
sort_byint否排序字段：8=总销量，9=周销量，10=评论数，11=收藏数
descint否排序方向：1=降序，0=升序
page_numint否页码，从 1 开始
page_sizeint否每页数量，最大 100

​
请求示例

curl -X POST https://api.example.com/api/v1/stores \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "search_key": "jewelry",
    "country": "US",
    "page_num": 1,
    "page_size": 20
  }'

​
返回结果

​
返回示例

Response
{
  "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_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,
  "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-01-14
维护方：EHunt API Team