Etsy Products API - EHunt API

Overview

This API is designed for VIP users to query product data on Etsy, supporting multi-dimensional filtering (sales, price, favorites, reviews, etc.), sorting, and pagination. Each returned product will consume corresponding API credits.

API Type: REST API
Request Method: POST
Data Format: JSON
Authentication: API Key
Available To: VIP / Subscription Users

Endpoint

POST /api/v1/items

Authentication

Include your API Key in the request header:

X-VIP-TOKEN: your_api_key_here

If the API Key is invalid, expired, or lacks subscription permissions, an error response will be returned.

Request Parameters

Request Body (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
}

Parameter Description

Parameter	Type	Required	Description
search_key	string	No	Search keyword or Etsy product URL
status	int	No	Product status: 1=Active, 0=Inactive
category	string	No	Product category
price	string	No	Price range, e.g. 20~100
sales_weekly	string	No	Weekly sales range，1~100
sales	string	No	Total sales range，1~100
favorites	string	No	Favorites count range，1~100
favorites_weekly	string	No	Weekly new favorites range，1~100
reviews	string	No	Reviews count range，1~100
reviews_weekly	string	No	Weekly new reviews range，1~100
product_type	string	No	Product type, multiple separated by comma
is_raving	int	No	Is Raving product: 1=Yes
is_pick	int	No	Is Pick product: 1=Yes
is_bestsell	int	No	Is bestseller: 1=Yes
listed_time	string	No	Listing date (YYYY-MM-DD)
country	string	No	Shipping country
currency_code	string	No	Currency code, default USD
sort_by	int	No	Sort field 1 = Weekly sales (default) 2 = Total sales 3 = Reviews 4 = Favorites 11 = Weekly reviews 12 = Weekly favorites 13 = Monthly sales
desc	int	No	Sort direction: 1=Descending, 2=Ascending
page_num	int	No	Page number, starts from 1
page_size	int	No	Items per page, max 100

Request Examples

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

Response Example

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
}

Response Fields

Field	Type	Description
product_num	int	Total number of products matching criteria
page_size	int	Items per page
final_count	int	Number of items returned in current page
list	array	Product data list
used_today	int	Credits used today
remaining_today	int	Remaining credits today

Credit Consumption Rules

Each returned product consumes 1 credit
Actual consumption = final_count
Returns 429 error when daily credits are insufficient

Error Codes

Code	Description
400	Invalid parameters
401	Invalid or missing API Key
403	No subscription permission
429	Daily quota exhausted
500	Internal server error

Use Cases

Etsy product selection analysis
High-sales / high-favorite product discovery
Competitor product monitoring
Market trend research and data analysis

Query Scenarios

1. Query Active Bestselling Products

{
  "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. Query Inactive High-Sales Products (Competitor Analysis)

{
  "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-VIP-TOKEN: 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-VIP-TOKEN": "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-VIP-TOKEN': 'your_api_key_here'
    }
  }
);

3. Query Products Listed in Specific Time Period

{
  "search_key": "handmade",
  "status": 1,
  "listed_time": "2024-03-01",
  "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-VIP-TOKEN: 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-VIP-TOKEN": "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-VIP-TOKEN': 'your_api_key_here'
    }
  }
);

Important Notes

Recommended page_size should not exceed 50 to avoid unnecessary credit consumption
Complex filtering conditions may affect API response time
API response data is for analysis reference only and does not constitute business guarantee

Last Updated: 2026-01-14
Maintained By: EHunt API Team

​Overview

​Endpoint

​Authentication

​Request Parameters

​Request Body (JSON)

​Parameter Description

​Request Examples

​Response

​Response Example

​Response Fields

​Credit Consumption Rules

​Error Codes

​Use Cases

​Query Scenarios

​1. Query Active Bestselling Products

​2. Query Inactive High-Sales Products (Competitor Analysis)

​3. Query Products Listed in Specific Time Period

​Important Notes

Overview

Endpoint

Authentication

Request Parameters

Request Body (JSON)

Parameter Description

Request Examples

Response

Response Example

Response Fields

Credit Consumption Rules

Error Codes

Use Cases

Query Scenarios

1. Query Active Bestselling Products

2. Query Inactive High-Sales Products (Competitor Analysis)

3. Query Products Listed in Specific Time Period

Important Notes