> ## 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 / 订阅用户 *** ## 接口地址 ```text theme={null} POST /api/v1/stores ``` *** ## 鉴权说明 请求 Header 中必须携带有效的 API Key： ```text theme={null} X-VIP-TOKEN: your_api_key_here ``` 若 API Key 无效、未订阅或积分不足，将返回对应错误。 *** ## 请求参数 ### 请求体（JSON） ```json theme={null} { "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 | *** ## 请求示例 ```bash curl theme={null} 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 }' ``` ```python Python theme={null} 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)) ``` ```javascript JavaScript theme={null} 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 PHP theme={null} "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); ?> ``` ```go Go theme={null} 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)) } ``` ```ruby Ruby theme={null} 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) ``` ```java Java theme={null} 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()); } } ``` *** ## 返回结果 ### 返回示例 ```json Response theme={null} { "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 | 今日剩余积分 | *** ## 积分消耗规则 ```text theme={null} - 每返回 1 条店铺数据,消耗 1 个积分 - 实际消耗积分 = final_count - 当日积分不足将直接返回 429 错误 ``` *** ## 错误码说明 ```text theme={null} 400 参数错误 401 API Key 无效或缺失 403 无订阅权限 429 今日调用额度已用尽 500 服务器内部错误 ``` *** ## 使用场景 * Etsy 店铺筛选与调研 * 高销量 / 高评分店铺挖掘 * 竞品店铺监控 * 市场规模与趋势分析 *** ## 店铺查询场景 ### 1. 查询星标优质店铺 ```json Request theme={null} { "search_key": "", "status": 1, "is_star": 1, "sales": "10000~", "sort_by": 8, "desc": 1, "page_size": 20 } ``` ```bash curl theme={null} 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 }' ``` ```python Python theme={null} 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()) ``` ```javascript JavaScript theme={null} 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. 查询特定国家的新兴店铺 ```json Request theme={null} { "search_key": "", "status": 1, "country": "US", "sales_weekly": "100~", "sort_by": 9, "desc": 1, "page_size": 20 } ``` ```bash curl theme={null} 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 }' ``` ```python Python theme={null} 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()) ``` ```javascript JavaScript theme={null} 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店铺（高好评率） ```json Request theme={null} { "search_key": "", "status": 1, "is_raving": 1, "reviews": "1000~", "sort_by": 10, "desc": 1, "page_size": 20 } ``` ```bash curl theme={null} 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 }' ``` ```python Python theme={null} 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()) ``` ```javascript JavaScript theme={null} 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