EtshopAPI Platform
EN / 中文
API REFERENCE

Top Selling Shops API

GET/v1/shop/top-sell-list
1 Credit per returned record. If your balance is insufficient, only as many records as your remaining Credits cover are returned (partial deduction); with a zero balance, 403001 is returned. Empty results are free.·api.etshop.ai/open-api
Credits usage rules

Billing: shop/product lists and top sellers cost 1 Credit per returned record; shop details cost 2 Credits per call. Details, trends, daily data and reviews are free (the record must have been returned by a list or details call within 3 days). Keyword search costs 1 Keyword Credit per keyword, and the same keyword is free for 30 days. Shop monitoring costs 1 Monitor Credit per shop for 30 days and is not refunded when stopped. Empty results are free and server errors are refunded automatically.

Request headers

AUTHORIZATIONAuthorization: {API Key}
CONTENT-TYPEapplication/json
ACCEPTapplication/json

Request example

cURL
curl --location --request GET 'https://api.etshop.ai/open-api/v1/shop/top-sell-list?times=2&start_time=1793548800&current_page=1&page_size=2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}'

Request parameters 10 fields

Pass each parameter in its specified location.

Parameter Type Description
times
query · required
integer Ranking type: 1 daily, 2 weekly (Monday to Sunday), 3 monthly (calendar month).
start_time
query · optional
integer Start of the ranking period (Unix timestamp in seconds, UTC+8): 00:00 of the day for daily, 00:00 Monday for weekly, 00:00 on the 1st for monthly. Defaults to the start of the latest period of the selected ranking type (times).
avg_price_start
query · optional
number Minimum average product price (USD).
avg_price_end
query · optional
number Maximum average product price (USD).
total_product_num_start
query · optional
integer Minimum number of products.
total_product_num_end
query · optional
integer Maximum number of products.
create_date_start
query · optional
string Shop opening date (from). Format: Y-m-d, e.g. 2024-01-01.
create_date_end
query · optional
string Shop opening date (to). Format: Y-m-d, e.g. 2024-12-31.
current_page
query · optional
integer Page number (min: 1, default: 1).
page_size
query · optional
integer Items per page (range: 1-100, default: 20).

Response example

Response · JSON
{
    "code": 200,
    "message": "success",
    "data": {
        "data": [
            {
                "id": 30981254,
                "image": "https://i.etsystatic.com/isla/b4d2f1/71234598/isla_fullxfull.71234598_9xq2lm3n.jpg",
                "name": "PrintablePlannerCo",
                "url": "https://www.etsy.com/shop/PrintablePlannerCo",
                "star_seller": 0,
                "headline": "Digital planners and printable templates",
                "total_product_num": 1286,
                "create_date": 1609459200,
                "currency_code": "USD",
                "sold_count": 1105,
                "total_rating_count": 96,
                "favorites_count": 402,
                "views": 61873,
                "avg_price": 6.25,
                "country_code": "US",
                "best_selling_product": [
                    {
                        "id": 1456789012,
                        "images": ["https://i.etsystatic.com/30981254/r/il/0e7b11/5234567890/il_fullxfull.5234567890_ef56.jpg"]
                    }
                ]
            },
            {
                "id": 21475836,
                "image": "https://i.etsystatic.com/isla/7a1c3e/58213467/isla_fullxfull.58213467_k2m9x0qa.jpg",
                "name": "LunaLinenStudio",
                "url": "https://www.etsy.com/shop/LunaLinenStudio",
                "star_seller": 1,
                "headline": "Handmade linen bedding & table linens from Lithuania",
                "total_product_num": 412,
                "create_date": 1462147200,
                "currency_code": "EUR",
                "sold_count": 1042,
                "total_rating_count": 151,
                "favorites_count": 498,
                "views": 32870,
                "avg_price": 68.4,
                "country_code": "LT",
                "best_selling_product": [
                    {
                        "id": 1284567890,
                        "images": ["https://i.etsystatic.com/21475836/r/il/8c1d2e/5123456789/il_fullxfull.5123456789_ab12.jpg"]
                    },
                    {
                        "id": 1197834562,
                        "images": ["https://i.etsystatic.com/21475836/r/il/42f0a9/4987654321/il_fullxfull.4987654321_cd34.jpg"]
                    }
                ]
            }
        ],
        "page": {
            "page_count": 5000,
            "current_page": 1,
            "total_count": 10000,
            "page_size": 2
        }
    },
    "credits": {
        "type": "default",
        "remaining_credits": 196536,
        "consumed_credits": 2,
        "total_credits": 196538
    }
}
Example data from the existing documentation

Response structure

Name Type Required Constraints Description
» code integer true none Status Code
» message string true none Response message
» data object true none Response data
»» data [object] true none Shop list
»»» id integer true none Shop ID
»»» image string true none Shop icon
»»» name string true none Shop name
»»» url string true none Shop URL
»»» star_seller integer true none Star Seller: 1 yes, 0 no
»»» headline string true none Shop headline
»»» total_product_num integer true none Number of products
»»» create_date integer true none Shop opening time (Unix timestamp, seconds)
»»» currency_code string true none Shop currency
»»» sold_count integer true none Sales within the ranking period
»»» total_rating_count integer true none New reviews within the ranking period
»»» favorites_count integer true none New favorites within the ranking period
»»» views integer true none New views within the ranking period
»»» avg_price number true none Average product price (USD)
»»» country_code string true none Shop country/region code
»»» best_selling_product [object] true none Best-selling products (up to 3)
»»»» id integer true none Product ID
»»»» images [string] true none Main product image
»» page object true none Pagination
»»» page_count integer true none Total pages
»»» current_page integer true none Current page number
»»» total_count integer true none Total records
»»» page_size integer true none Items per page
» credits object true none Credits information of this request. See Billing Rules.
»» type string true none Credits type. default for this endpoint.
»» remaining_credits integer true none Remaining Credits after this request
»» consumed_credits integer true none Credits consumed by this request, equal to the number of records returned
»» total_credits integer true none Credits balance before this request (remaining_credits + consumed_credits)
Search the existing endpoint names and paths