Etsy Stores API - EHunt API

Overview

This API is designed for VIP users to query Etsy store data, supporting multi-condition filtering by sales, favorites, reviews, country, category, etc., with sorting and pagination capabilities. Each returned store 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/stores

Authentication

Include a valid API Key in the request header:

X-VIP-TOKEN: your_api_key_here

If the API Key is invalid, unsubscribed, or has insufficient credits, a corresponding error will be returned.

Request Parameters

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

Parameter Description

Parameter	Type	Required	Description
search_key	string	No	Search keyword or store name、url
status	int	No	Store status: 1=Active, 0=Inactive
country	string	No	Store country
category	string	No	Store main category
sales_weekly	string	No	Store weekly sales range
sales	string	No	Store total sales range
favorites	string	No	Store favorites count range
favorites_weekly	string	No	Store weekly new favorites
reviews	string	No	Store reviews count range
reviews_weekly	string	No	Store weekly new reviews
start_at	string	No	Store opening date range
is_star	int	No	Is star store: 1=Yes
is_raving	int	No	Is Raving store: 1=Yes
sort_by	int	No	Sort field: 8=Total sales, 9=Weekly sales, 10=Reviews, 11=Favorites
desc	int	No	Sort direction: 1=Descending, 0=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/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

Response Example

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
}

Response Fields

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

Credit Consumption Rules

Each returned store consumes 1 credit
Actual credit 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 store screening and research
High-sales / high-rating store discovery
Competitor store monitoring
Market size and trend analysis

Query Scenarios

1. Query Star Premium Stores

{
  "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. Query Emerging Stores in Specific Country

{
  "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-VIP-TOKEN: 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-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,
    country: 'US',
    sales_weekly: '100~',
    sort_by: 9,
    desc: 1,
    page_size: 20
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-VIP-TOKEN': 'your_api_key_here'
    }
  }
);

3. Query Raving Stores (High Rating)

{
  "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'
    }
  }
);

Important Notes

Recommended to control page_size reasonably to avoid unnecessary credit consumption
Multi-condition filtering may increase query time
Response data is sourced from Etsy public information and is for analysis use only

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 Star Premium Stores

​2. Query Emerging Stores in Specific Country

​3. Query Raving Stores (High Rating)

​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 Star Premium Stores

2. Query Emerging Stores in Specific Country

3. Query Raving Stores (High Rating)

Important Notes