EtshopAPI Platform
中文 / EN
接口参考

商品列表 API

GET/v1/product
每返回一条记录消耗 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/product?times=2&name=linen%20duvet&order_by=sale_growth&direction=desc&current_page=1&page_size=2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}'

请求参数 28 项

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

参数 类型 说明
times
query · 必填
integer 统计周期,决定 *_growth 字段和增长类排序的统计区间:5 近 3 天、2 近 7 天、3 近 30 天、4 近 90 天
categories
query · 可选
integer 分类 ID,见分类列表;任意层级均可,包含其下所有子分类
name
query · 可选
string 商品关键词,匹配商品标签或标题;多个用英文逗号分隔,需同时匹配
exclude_name
query · 可选
string 排除标题包含这些关键词的商品,多个用英文逗号分隔
shop_id
query · 可选
integer 店铺 ID,只返回该店铺的商品(包括已关闭店铺)
price_start
query · 可选
number 价格最小值(美元)
price_end
query · 可选
number 价格最大值(美元)
created_time_start
query · 可选
string 上架日期起始,格式 Y-m-d,例如 2026-01-01
created_time_end
query · 可选
string 上架日期截止,格式 Y-m-d,例如 2026-10-31
bestseller
query · 可选
integer 传 1 只返回 Bestseller 商品
etsy_pick
query · 可选
integer 传 1 只返回 Etsy's Pick 商品
with_video
query · 可选
integer 传 1 只返回有视频的商品
sale_start
query · 可选
integer 总销量最小值
sale_end
query · 可选
integer 总销量最大值
review_start
query · 可选
integer 总评论数最小值
review_end
query · 可选
integer 总评论数最大值
collection_start
query · 可选
integer 总收藏数最小值
collection_end
query · 可选
integer 总收藏数最大值
view_start
query · 可选
integer 总浏览量最小值
view_end
query · 可选
integer 总浏览量最大值
product_type
query · 可选
string 商品类型,多个用英文逗号分隔:Handmade、Digital、Vintage、Customizable、Others
is_real_sale
query · 可选
integer 传 1 只返回有真实销量的商品
real_sale_start
query · 可选
integer 真实销量最小值
real_sale_end
query · 可选
integer 真实销量最大值
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(周期内评论增长)、real_sale_growth(周期内真实销量增长)、total_sale(总销量)、total_view(总浏览)、total_collection(总收藏)、total_review(总评论)、real_sale(真实销量)、create_date(上架时间);默认 review_growth
direction
query · 可选
string 排序方向:desc 降序(默认)、asc 升序

返回示例

返回示例 · JSON
{
    "code": 200,
    "message": "success",
    "data": {
        "data": [
            {
                "id": 1284567890,
                "image": "https://i.etsystatic.com/21475836/r/il/8c1d2e/5123456789/il_fullxfull.5123456789_ab12.jpg",
                "name": "Linen Duvet Cover in Natural Flax, Stonewashed Linen Bedding, Queen King Size",
                "create_date": 1663200000,
                "currency_code": "EUR",
                "country_code": "LT",
                "sale": 9842,
                "sale_growth": 214,
                "review": 2137,
                "review_growth": 31,
                "collect": 18450,
                "collect_growth": 402,
                "view": 389214,
                "view_growth": 6120,
                "bestseller": 1,
                "etsy_pick": 0,
                "product_type": ["Handmade", "Customizable"],
                "is_video": 1,
                "price": 129,
                "url": "https://www.etsy.com/listing/1284567890/linen-duvet-cover-in-natural-flax",
                "store_name": "LunaLinenStudio",
                "shop_id": 21475836,
                "real_sale": 6215,
                "real_sale_growth": 158
            },
            {
                "id": 1532907846,
                "image": "https://i.etsystatic.com/38201745/r/il/a17c4d/6012345678/il_fullxfull.6012345678_xy90.jpg",
                "name": "Washed Linen Duvet Cover Set, Sage Green Bedding with Pillowcases",
                "create_date": 1694563200,
                "currency_code": "USD",
                "country_code": "US",
                "sale": 3120,
                "sale_growth": 167,
                "review": 604,
                "review_growth": 22,
                "collect": 7731,
                "collect_growth": 288,
                "view": 145032,
                "view_growth": 4870,
                "bestseller": 0,
                "etsy_pick": 1,
                "product_type": ["Handmade"],
                "is_video": 0,
                "price": 98.5,
                "url": "https://www.etsy.com/listing/1532907846/washed-linen-duvet-cover-set-sage-green",
                "store_name": "HearthAndLoomHome",
                "shop_id": 38201745,
                "real_sale": 0,
                "real_sale_growth": 0
            }
        ],
        "page": {
            "page_count": 1846,
            "current_page": 1,
            "total_count": 3692,
            "page_size": 2
        }
    },
    "credits": {
        "type": "default",
        "remaining_credits": 196531,
        "consumed_credits": 2,
        "total_credits": 196533
    }
}
文档中的示例数据

返回数据结构

名称 类型 必选 约束 说明
» 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 商品标题
»»» create_date integer true none 上架时间(Unix 时间戳,秒)
»»» currency_code string true none 价格币种
»»» country_code string true none 店铺所在国家/地区代码
»»» sale integer true none 总销量
»»» sale_growth integer true none 统计周期(times)内的销量增长
»»» review integer true none 总评论数
»»» review_growth integer true none 统计周期内的评论增长
»»» collect integer true none 总收藏数
»»» collect_growth integer true none 统计周期内的收藏增长
»»» view integer true none 总浏览量
»»» view_growth integer true none 统计周期内的浏览增长
»»» bestseller integer true none 是否 Bestseller:1 是,0 否
»»» etsy_pick integer true none 是否 Etsy's Pick:1 是,0 否
»»» product_type [string] true none 商品类型:Handmade、Digital、Vintage、Customizable、Others
»»» is_video integer true none 是否有视频:1 是,0 否
»»» price number true none 价格(币种见 currency_code)
»»» url string true none 商品链接
»»» store_name string true none 店铺名称
»»» shop_id integer true none 店铺 ID
»»» real_sale integer true none 真实销量
»»» real_sale_growth integer 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)
来自现有接口目录与文档 · 支持接口名称和地址搜索