EtshopAPI Platform
EN / 中文
API REFERENCE

Shop List API

Use the Etsy shop list API to filter shops by category, price, sales, favorites, reviews, country and period. Review request parameters, cURL examples, JSON responses and Credits usage below.

GET/v1/shop
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?times=2&current_page=1&page_size=2&order_by=sale_growth&direction=desc' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}'

Request parameters 27 fields

Pass each parameter in its specified location.

Parameter Type Description
times
query · required
integer Statistics period for the *_growth fields and growth-based sorting: 1 yesterday, 2 last 7 days, 3 last 30 days, 4 last 90 days.
name
query · optional
string Keywords matched against shop name or headline (fuzzy). Multiple values should be comma-separated; all must match.
exclude_name
query · optional
string Exclude shops whose name or headline contains any of these keywords. Multiple values should be comma-separated.
star_seller
query · optional
integer Star Seller: 1 yes, 0 no.
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.
created_time_start
query · optional
string Shop opening date (from). Format: Y-m-d, e.g. 2024-01-01.
created_time_end
query · optional
string Shop opening date (to). Format: Y-m-d, e.g. 2024-12-31.
average_rating_start
query · optional
number Minimum shop rating (0–5).
average_rating_end
query · optional
number Maximum shop rating (0–5).
country_code
query · optional
string Shop country/region code(s). Multiple values should be comma-separated.
sold_count_start
query · optional
integer Minimum total sales.
sold_count_end
query · optional
integer Maximum total sales.
total_rating_count_start
query · optional
integer Minimum total reviews.
total_rating_count_end
query · optional
integer Maximum total reviews.
favorites_count_start
query · optional
integer Minimum total favorites.
favorites_count_end
query · optional
integer Maximum total favorites.
views_start
query · optional
integer Minimum total views.
views_end
query · optional
integer Maximum total views.
product_type
query · optional
string Product type(s). Multiple values should be comma-separated. Valid options: Handmade, Digital, Vintage, Customizable, Others.
is_real_sale
query · optional
integer Whether the shop has real sales data: 1 yes, 0 no.
current_page
query · optional
integer Page number (min: 1, default: 1).
page_size
query · optional
integer Items per page (range: 1-100, default: 20).
order_by
query · optional
string Sort field. Valid options: sale_growth (sales growth in the period), view_growth (view growth in the period), collection_growth (favorite growth in the period), review_growth (review growth in the period), total_sale (total sales), total_view (total views), total_collection (total favorites), total_review (total reviews). Defaults to sale_growth.
direction
query · optional
string Sort direction. Valid options: desc (descending, default), asc (ascending).

Response example

Response · JSON
{
    "code": 200,
    "message": "success",
    "data": {
        "data": [
            {
                "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": 86214,
                "sold_count_growth": 1342,
                "total_rating_count": 15830,
                "total_rating_count_growth": 187,
                "favorites_count": 48270,
                "favorites_count_growth": 615,
                "views": 2903417,
                "views_growth": 40512,
                "product_type": ["Handmade", "Customizable"],
                "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"]
                    }
                ]
            },
            {
                "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": 154302,
                "sold_count_growth": 1105,
                "total_rating_count": 21455,
                "total_rating_count_growth": 96,
                "favorites_count": 30218,
                "favorites_count_growth": 402,
                "views": 4120584,
                "views_growth": 61873,
                "product_type": ["Digital"],
                "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"]
                    }
                ]
            }
        ],
        "page": {
            "page_count": 238411,
            "current_page": 1,
            "total_count": 476822,
            "page_size": 2
        }
    },
    "credits": {
        "type": "default",
        "remaining_credits": 196538,
        "consumed_credits": 2,
        "total_credits": 196540
    }
}
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 Total sales
»»» sold_count_growth integer true none Sales growth in the period set by times
»»» total_rating_count integer true none Total reviews
»»» total_rating_count_growth integer true none Review growth in the period
»»» favorites_count integer true none Total favorites
»»» favorites_count_growth integer true none Favorite growth in the period
»»» views integer true none Total views
»»» views_growth integer true none View growth in the period
»»» product_type [string] true none Product types: Handmade, Digital, Vintage, Customizable, Others
»»» 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