EtshopAPI Platform
中文 / EN
接口参考

店铺列表 API

使用 Etsy 店铺列表 API,按类目、价格、销量、收藏、评论、国家和统计周期筛选店铺。下方提供请求参数、cURL 调用示例、JSON 返回数据与 Credits 消耗说明。

GET/v1/shop
每返回一条记录消耗 1 Credit;余额不足时按剩余 Credits 能覆盖的条数返回(部分扣费),余额为 0 时返回 403001;查询结果为空不扣费·api.etshop.ai/open-api
Credits 消耗规则

计费规则:店铺/商品列表与热销榜每返回 1 条扣 1 Credit,店铺详情每次扣 2 Credits;详情、趋势、每日数据、评论免费(需 3 天内在列表或详情中返回过)。关键词搜索每个词扣 1 Keyword Credit,30 天内同一个词免费。店铺监控每个店铺扣 1 Monitor Credit,监控 30 天,停止后不退还。空结果不扣费,服务器错误自动退还。

请求头

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

请求示例

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}'

请求参数 27 项

按参数标注的位置传入请求。

参数 类型 说明
times
query · 必填
integer 统计周期,决定 *_growth 字段和增长类排序的统计区间:1 昨天、2 近 7 天、3 近 30 天、4 近 90 天
name
query · 可选
string 店铺名称或标语关键词,模糊匹配;多个用英文逗号分隔,需同时匹配
exclude_name
query · 可选
string 排除店铺名称或标语包含这些关键词的店铺,多个用英文逗号分隔
star_seller
query · 可选
integer 是否 Star Seller:1 是,0 否
avg_price_start
query · 可选
number 商品平均价格最小值(美元)
avg_price_end
query · 可选
number 商品平均价格最大值(美元)
total_product_num_start
query · 可选
integer 商品数最小值
total_product_num_end
query · 可选
integer 商品数最大值
created_time_start
query · 可选
string 开店日期起始,格式 Y-m-d,例如 2024-01-01
created_time_end
query · 可选
string 开店日期截止,格式 Y-m-d,例如 2024-12-31
average_rating_start
query · 可选
number 店铺评分最小值(0–5)
average_rating_end
query · 可选
number 店铺评分最大值(0–5)
country_code
query · 可选
string 店铺所在国家/地区代码,多个用英文逗号分隔
sold_count_start
query · 可选
integer 总销量最小值
sold_count_end
query · 可选
integer 总销量最大值
total_rating_count_start
query · 可选
integer 总评论数最小值
total_rating_count_end
query · 可选
integer 总评论数最大值
favorites_count_start
query · 可选
integer 总收藏数最小值
favorites_count_end
query · 可选
integer 总收藏数最大值
views_start
query · 可选
integer 总浏览量最小值
views_end
query · 可选
integer 总浏览量最大值
product_type
query · 可选
string 商品类型,多个用英文逗号分隔:Handmade、Digital、Vintage、Customizable、Others
is_real_sale
query · 可选
integer 是否有真实销量数据:1 是,0 否
current_page
query · 可选
integer 页码,最小 1,默认 1
page_size
query · 可选
integer 每页条数,范围 1-100,默认 20
order_by
query · 可选
string 排序字段:sale_growth(周期内销量增长)、view_growth(周期内浏览增长)、collection_growth(周期内收藏增长)、review_growth(周期内评论增长)、total_sale(总销量)、total_view(总浏览)、total_collection(总收藏)、total_review(总评论);默认 sale_growth
direction
query · 可选
string 排序方向:desc 降序(默认)、asc 升序

返回示例

返回示例 · 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
    }
}
文档中的示例数据

返回数据结构

名称 类型 必选 约束 说明
» code integer true none 业务状态码
» message string true none 响应消息
» data object true none 响应数据
»» data [object] true none 店铺列表
»»» id integer true none 店铺 ID
»»» image string true none 店铺图标
»»» name string true none 店铺名称
»»» url string true none 店铺链接
»»» star_seller integer true none 是否 Star Seller:1 是,0 否
»»» headline string true none 店铺标语
»»» total_product_num integer true none 商品数
»»» create_date integer true none 开店时间(Unix 时间戳,秒)
»»» currency_code string true none 店铺币种
»»» sold_count integer true none 总销量
»»» sold_count_growth integer true none 统计周期(times)内的销量增长
»»» total_rating_count integer true none 总评论数
»»» total_rating_count_growth integer true none 统计周期内的评论增长
»»» favorites_count integer true none 总收藏数
»»» favorites_count_growth integer true none 统计周期内的收藏增长
»»» views integer true none 总浏览量
»»» views_growth integer true none 统计周期内的浏览增长
»»» product_type [string] true none 商品类型:Handmade、Digital、Vintage、Customizable、Others
»»» avg_price number true none 商品平均价格(美元)
»»» country_code string true none 店铺所在国家/地区代码
»»» best_selling_product [object] true none 最畅销的商品(最多 3 个)
»»»» id integer true none 商品 ID
»»»» images [string] true none 商品主图
»» page object true none 分页信息
»»» page_count integer true none 总页数
»»» current_page integer true none 当前页码
»»» total_count integer true none 总条数
»»» page_size integer true none 每页条数
» credits object true none 本次请求的 Credits 信息,见计费规则
»» type string true none Credits 类型,本接口为 default
»» remaining_credits integer true none 本次请求后剩余的 Credits
»» consumed_credits integer true none 本次请求消耗的 Credits,等于实际返回的记录数
»» total_credits integer true none 本次请求前的 Credits 余额(remaining_credits + consumed_credits)
来自现有接口目录与文档 · 支持接口名称和地址搜索