商品查询接口

接口概述

该接口用于 VIP 用户商品数据查询，支持多维度筛选（销量、价格、收藏、评论等）、排序与分页。每条返回商品将消耗对应的 API 积分。

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

接口地址

POST /api/v1/items

鉴权说明

请求需在 Header 中携带 API Key：

X-VIP-TOKEN: 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": "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=周销量(默认） 2=总销量 3=评论 4=收藏 11=周评论 12=周收藏 13=月销量
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
  }'

import requests
import json

url = "https://api.example.com/api/vi/items"

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

payload = {
    "search_key": "wedding ring",
    "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/vi/items';

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

const payload = {
  search_key: 'wedding ring',
  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/vi/items";

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

$payload = [
    "search_key" => "wedding ring",
    "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/vi/items"
    
    payload := map[string]interface{}{
        "search_key": "wedding ring",
        "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/vi/items")

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

payload = {
  search_key: 'wedding ring',
  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 ItemsQuery {
    public static void main(String[] args) throws Exception {
        String url = "https://api.example.com/api/vi/items";
        
        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", "wedding ring");
        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": {
    "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 错误

错误码说明

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

使用场景

Etsy 商品选品分析
高销量 / 高收藏商品挖掘
竞品商品数据监控
市场趋势研究与数据分析

商品查询场景

1. 查询上架的热销商品

{
  "search_key": "",
  "status": 1,
  "sales": "100~",
  "is_bestsell": 1,
  "sort_by": 4,
  "desc": 1,
  "page_size": 20
}

curl -X POST https://api.example.com/api/vi/items \
  -H "Content-Type: application/json" \
  -H "X-VIP-TOKEN: your_api_key_here" \
  -d '{
    "search_key": "",
    "status": 1,
    "sales": "100~",
    "is_bestsell": 1,
    "sort_by": 4,
    "desc": 1,
    "page_size": 20
  }'

import requests

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

payload = {
    "search_key": "",
    "status": 1,
    "sales": "100~",
    "is_bestsell": 1,
    "sort_by": 4,
    "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/vi/items',
  {
    search_key: '',
    status: 1,
    sales: '100~',
    is_bestsell: 1,
    sort_by: 4,
    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": 0,
  "sales": "1000~",
  "sort_by": 4,
  "desc": 1,
  "page_size": 20
}

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": "",
    "status": 0,
    "sales": "1000~",
    "sort_by": 4,
    "desc": 1,
    "page_size": 20
  }'

import requests

payload = {
    "search_key": "",
    "status": 0,
    "sales": "1000~",
    "sort_by": 4,
    "desc": 1,
    "page_size": 20
}

response = requests.post(
    "https://api.example.com/api/vi/items",
    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/vi/items',
  {
    search_key: '',
    status: 0,
    sales: '1000~',
    sort_by: 4,
    desc: 1,
    page_size: 20
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key_here'
    }
  }
);

3. 查询特定时间段上架的商品

{
  "search_key": "handmade",
  "status": 1,
  "listed_time": "2025-12-15~2026-01-15",
  "sort_by": 2,
  "desc": 1,
  "page_size": 20
}

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": "handmade",
    "status": 1,
    "listed_time": "2024-03-01",
    "sort_by": 2,
    "desc": 1,
    "page_size": 20
  }'

import requests

payload = {
    "search_key": "handmade",
    "status": 1,
    "listed_time": "2024-03-01",
    "sort_by": 2,
    "desc": 1,
    "page_size": 20
}

response = requests.post(
    "https://api.example.com/api/vi/items",
    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/vi/items',
  {
    search_key: 'handmade',
    status: 1,
    listed_time: '2024-03-01',
    sort_by: 2,
    desc: 1,
    page_size: 20
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key_here'
    }
  }
);

注意事项

page_size 建议不超过 50，以避免不必要的积分消耗
复杂筛选条件可能影响接口响应时间
接口返回数据仅供分析参考，不构成商业保证

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

​接口概述

​接口地址

​鉴权说明

​请求参数

​请求体（JSON）

​参数说明

​请求示例

​返回结果

​返回示例

​返回字段说明

​积分消耗规则

​错误码说明

​使用场景

​商品查询场景

​1. 查询上架的热销商品

​2. 查询下架的高销量商品（竞品分析）

​3. 查询特定时间段上架的商品

​注意事项

接口概述

接口地址

鉴权说明

请求参数

请求体（JSON）

参数说明

请求示例

返回结果

返回示例

返回字段说明

积分消耗规则

错误码说明

使用场景

商品查询场景

1. 查询上架的热销商品

2. 查询下架的高销量商品（竞品分析）

3. 查询特定时间段上架的商品

注意事项