EtshopAPI Platform
中文 / EN
接口参考

热销店铺榜 API

GET/v1/shop/top-sell-list
每返回一条记录消耗 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/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}'

请求参数 10 项

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

参数 类型 说明
times
query · 必填
integer 榜单类型:1 日榜、2 周榜(周一至周日)、3 月榜(自然月)
start_time
query · 可选
integer 榜单周期的开始时间(Unix 时间戳,秒,按 UTC+8 计算):日榜为当天 00:00,周榜为周一 00:00,月榜为当月 1 日 00:00。不传时取所选榜单类型(times)最新一期的开始时间
avg_price_start
query · 可选
number 商品平均价格最小值(美元)
avg_price_end
query · 可选
number 商品平均价格最大值(美元)
total_product_num_start
query · 可选
integer 商品数最小值
total_product_num_end
query · 可选
integer 商品数最大值
create_date_start
query · 可选
string 开店日期起始,格式 Y-m-d,例如 2024-01-01
create_date_end
query · 可选
string 开店日期截止,格式 Y-m-d,例如 2024-12-31
current_page
query · 可选
integer 页码,最小 1,默认 1
page_size
query · 可选
integer 每页条数,范围 1-100,默认 20

返回示例

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

返回数据结构

名称 类型 必选 约束 说明
» 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 榜单周期内的销量
»»» total_rating_count integer true none 榜单周期内新增的评论数
»»» favorites_count integer true none 榜单周期内新增的收藏数
»»» views integer true none 榜单周期内新增的浏览量
»»» 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)
来自现有接口目录与文档 · 支持接口名称和地址搜索