店铺查询接口

接口概述

该接口用于 VIP 用户进行 Etsy 店铺数据查询，支持按销量、收藏、评论、国家、分类等多条件筛选，并支持排序与分页。每条返回店铺将消耗对应的 API 积分。

接口类型：REST API
请求方式：POST
数据格式：JSON
鉴权方式：API Key
适用用户：VIP / 订阅用户

接口地址

POST /api/v1/stores

鉴权说明

请求 Header 中必须携带有效的 API Key：

X-VIP-TOKEN: your_api_key_here

若 API Key 无效、未订阅或积分不足，将返回对应错误。

请求参数

请求体（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
  }'

import requests
import json

url = "https://api.example.com/api/v1/stores"

headers = {
    "Content-Type": "application/json",
    "X-VIP-TOKEN": "your_api_key_here"
}

payload = {
    "search_key": "jewelry",
    "country": "US",
    "page_num": 1,
    "page_size": 20
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(json.dumps(data, indent=2))

const axios = require('axios');

const url = 'https://api.example.com/api/v1/stores';

const headers = {
  'Content-Type': 'application/json',
  'X-VIP-TOKEN': 'your_api_key_here'
};

const payload = {
  search_key: 'jewelry',
  country: 'US',
  page_num: 1,
  page_size: 20
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

<?php
$url = "https://api.example.com/api/v1/stores";

$headers = [
    "Content-Type: application/json",
    "X-VIP-TOKEN: your_api_key_here"
];

$payload = [
    "search_key" => "jewelry",
    "country" => "US",
    "page_num" => 1,
    "page_size" => 20
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

curl_close($ch);

echo json_encode($data, JSON_PRETTY_PRINT);
?>

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.example.com/api/v1/stores"
    
    payload := map[string]interface{}{
        "search_key": "jewelry",
        "country":    "US",
        "page_num":   1,
        "page_size":  20,
    }
    
    jsonData, _ := json.Marshal(payload)
    
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-VIP-TOKEN", "your_api_key_here")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

require 'net/http'
require 'json'
require 'uri'

url = URI.parse("https://api.example.com/api/v1/stores")

headers = {
  'Content-Type' => 'application/json',
  'X-VIP-TOKEN' => 'your_api_key_here'
}

payload = {
  search_key: 'jewelry',
  country: 'US',
  page_num: 1,
  page_size: 20
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url.path, headers)
request.body = payload.to_json

response = http.request(request)
data = JSON.parse(response.body)

puts JSON.pretty_generate(data)

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

public class StoresQuery {
    public static void main(String[] args) throws Exception {
        String url = "https://api.example.com/api/v1/stores";
        
        URL obj = new URL(url);
        HttpURLConnection con = (HttpURLConnection) obj.openConnection();
        con.setRequestMethod("POST");
        con.setRequestProperty("Content-Type", "application/json");
        con.setRequestProperty("X-VIP-TOKEN", "your_api_key_here");
        con.setDoOutput(true);
        
        JSONObject payload = new JSONObject();
        payload.put("search_key", "jewelry");
        payload.put("country", "US");
        payload.put("page_num", 1);
        payload.put("page_size", 20);
        
        OutputStream os = con.getOutputStream();
        os.write(payload.toString().getBytes());
        os.flush();
        os.close();
        
        BufferedReader in = new BufferedReader(
            new InputStreamReader(con.getInputStream())
        );
        String inputLine;
        StringBuilder response = new StringBuilder();
        
        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close();
        
        System.out.println(response.toString());
    }
}

返回结果

返回示例

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_num	int	符合条件的店铺总数
page_size	int	每页返回数量
final_count	int	当前页返回条数
list	array	店铺数据列表
used_today	int	今日已使用积分
remaining_today	int	今日剩余积分

积分消耗规则

- 每返回 1 条店铺数据,消耗 1 个积分
- 实际消耗积分 = final_count
- 当日积分不足将直接返回 429 错误

错误码说明

参数错误
API Key 无效或缺失
无订阅权限
今日调用额度已用尽
服务器内部错误

使用场景

Etsy 店铺筛选与调研
高销量 / 高评分店铺挖掘
竞品店铺监控
市场规模与趋势分析

店铺查询场景

1. 查询星标优质店铺

{
  "search_key": "",
  "status": 1,
  "is_star": 1,
  "sales": "10000~",
  "sort_by": 8,
  "desc": 1,
  "page_size": 20
}

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": "",
    "status": 1,
    "is_star": 1,
    "sales": "10000~",
    "sort_by": 8,
    "desc": 1,
    "page_size": 20
  }'

import requests

url = "https://api.example.com/api/v1/stores"
headers = {
    "Content-Type": "application/json",
    "X-VIP-TOKEN": "your_api_key_here"
}

payload = {
    "search_key": "",
    "status": 1,
    "is_star": 1,
    "sales": "10000~",
    "sort_by": 8,
    "desc": 1,
    "page_size": 20
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const axios = require('axios');

const response = await axios.post(
  'https://api.example.com/api/v1/stores',
  {
    search_key: '',
    status: 1,
    is_star: 1,
    sales: '10000~',
    sort_by: 8,
    desc: 1,
    page_size: 20
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-VIP-TOKEN': 'your_api_key_here'
    }
  }
);

console.log(response.data);

2. 查询特定国家的新兴店铺

{
  "search_key": "",
  "status": 1,
  "country": "US",
  "sales_weekly": "100~",
  "sort_by": 9,
  "desc": 1,
  "page_size": 20
}

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": "",
    "status": 1,
    "country": "US",
    "sales_weekly": "100~",
    "sort_by": 9,
    "desc": 1,
    "page_size": 20
  }'

import requests

payload = {
    "search_key": "",
    "status": 1,
    "country": "US",
    "sales_weekly": "100~",
    "sort_by": 9,
    "desc": 1,
    "page_size": 20
}

response = requests.post(
    "https://api.example.com/api/v1/stores",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your_api_key_here"
    },
    json=payload
)

print(response.json())

const response = await axios.post(
  'https://api.example.com/api/v1/stores',
  {
    search_key: '',
    status: 1,
    country: 'US',
    sales_weekly: '100~',
    sort_by: 9,
    desc: 1,
    page_size: 20
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key_here'
    }
  }
);

3. 查询Raving店铺（高好评率）

{
  "search_key": "",
  "status": 1,
  "is_raving": 1,
  "reviews": "1000~",
  "sort_by": 10,
  "desc": 1,
  "page_size": 20
}

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": "",
    "status": 1,
    "is_raving": 1,
    "reviews": "1000~",
    "sort_by": 10,
    "desc": 1,
    "page_size": 20
  }'

import requests

payload = {
    "search_key": "",
    "status": 1,
    "is_raving": 1,
    "reviews": "1000~",
    "sort_by": 10,
    "desc": 1,
    "page_size": 20
}

response = requests.post(
    "https://api.example.com/api/v1/stores",
    headers={
        "Content-Type": "application/json",
        "X-VIP-TOKEN": "your_api_key_here"
    },
    json=payload
)

print(response.json())

const response = await axios.post(
  'https://api.example.com/api/v1/stores',
  {
    search_key: '',
    status: 1,
    is_raving: 1,
    reviews: '1000~',
    sort_by: 10,
    desc: 1,
    page_size: 20
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-VIP-TOKEN': 'your_api_key_here'
    }
  }
);

注意事项

建议合理控制 page_size，避免不必要的积分消耗
多条件筛选可能增加查询耗时
返回数据来源于 Etsy 公开信息，仅供分析使用

更新时间：2026-05-15
维护方：EHunt API Team

​接口概述

​接口地址

​鉴权说明

​请求参数

​请求体（JSON）

​参数说明

​请求示例

​返回结果

​返回示例

​返回字段说明

​积分消耗规则

​错误码说明

​使用场景

​店铺查询场景

​1. 查询星标优质店铺

​2. 查询特定国家的新兴店铺

​3. 查询Raving店铺（高好评率）

​注意事项

接口概述

接口地址

鉴权说明

请求参数

请求体（JSON）

参数说明

请求示例

返回结果

返回示例

返回字段说明

积分消耗规则

错误码说明

使用场景

店铺查询场景

1. 查询星标优质店铺

2. 查询特定国家的新兴店铺

3. 查询Raving店铺（高好评率）

注意事项