商品搜索请求模板
将示例中的 <API_KEY> 替换为你自己的平台 API 密钥。密钥会出现在请求 URL 中,请勿放入共享链接、截图或日志。
此模板使用 JSON 请求体。请填写搜索关键词,并按需选择 eBay 站点;复制示例不会发出请求。
搜索只需要一个关键词:在必填的 query 字段中填写要搜索的商品词,并可按需选择 com、co.uk、de 等 eBay 站点。无需登录,也不需要 Cookie、会话或上一步返回的 ID。打开页面、切换面板或复制模板都不会发出请求;只有你主动提交时才会请求数据,每次提交的请求都会消耗你的 API 密钥对应的额度。
基础 URL https://api.opendata-api.com
curl -X POST 'https://api.opendata-api.com/api/project/ebay/search?key=<API_KEY>' \
-H 'Content-Type: application/json' \
-d '{"query":"<query>"}'import requests
response = requests.request(
"POST",
"https://api.opendata-api.com/api/project/ebay/search",
params={
"key": "<API_KEY>",
},
json={
"query": "<query>",
},
timeout=30,
)
response.raise_for_status()
print(response.json())const url = new URL("https://api.opendata-api.com/api/project/ebay/search");
url.search = new URLSearchParams({
"key": "<API_KEY>",
}).toString();
const response = await fetch(url, {
method: "POST",
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"query": "<query>"
}),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());发送请求前请确认
- 每次请求都要记录所用的 domain 和返回的币种,价格会随站点变化;英国自提筛选需要使用 co.uk 站点并填写邮编。
- 返回的是挂牌价和卖家公开信息,不是成交价;缺失的反馈数据不要补零,不同时间窗口的评价数量也不能相加。
- 批量查询的文档限制不一致:概述写每次最多 40 个 ID,参数说明写 15 个。确认前请每批不超过 15 个,并注意按商品 ID 逐个计费,同时处理 not_found 和请求错误。
检查返回结果
HTTP 状态只说明请求是否被处理;请继续检查平台返回的 code、message 和 data,再看结果里的 ok 标记与字段结构。成功响应不代表字段齐全,也不代表业务结论成立。
按查询目标选择接口
- 发现商品、特价与类目
-
用类目名称查数字类目 ID,用关键词和筛选条件搜索在售商品,或单独查看当前每日特价。这三个接口都不需要事先拿到商品 ID。
- 查看商品完整详情
-
单个商品详情需要商品 ID 或商品链接,二选一即可;批量查询需要用逗号分隔的商品 ID。ID 可来自搜索或店铺结果,不要凭标题猜测。
- 核查卖家与店铺
-
使用准确的卖家用户名查看店铺全部在售商品和公开反馈评分。结果只反映公开页面信息,不能作为卖家可靠的保证,也不是完整的库存导出。
类目查询
/api/project/ebay/categories 按名称查询 eBay 类目 ID,并列出指定站点的一级大类目录。
完整文档 →说明
以结构化 JSON 返回某个 eBay 站点的类目目录。可传入 query,按类目名称或 slug 做不区分大小写的子串筛选,把 cell phones 这类日常名称解析为搜索接口 category 参数所需的数字 category_id;query 留空则返回完整的一级类目树。domain 可选 13 个已验证的 eBay 站点(com、co.uk、de、com.au、ca、fr、it、es、nl、at、ch、ie、pl),max_results 控制返回的类目数量,最多 240 条。响应采用 ok/meta/data 外层结构:data.categories[] 包含 category_id、name 和 slug,data.groups[] 为一级大类(department)名称。实测示例(query 为 cell phones,domain 为 com,max_results 为 5):返回 1 个类目(category_id 15032,name 为 Cell Phones & Accessories,slug 为 Cell-Phones-Smart-Watches-Accessories),同时返回 18 个大类名称,如 Electronics、Collectibles & Art、Home & Garden,meta 中 domain 为 com、query 为 cell phones、record_count 为 1。
主动测试请求 必填 0 项,可选 3 项
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body |
更多可选参数 (1)
| 参数 | 位置 | 值 |
|---|---|---|
| body |
调用成本暂不可用,未假定任何价格。
每日特价
/api/project/ebay/deals 获取指定站点当前 eBay 每日特价(Daily Deals)榜单,含促销价、原价和运费信息。
完整文档 →说明
返回某个 eBay 站点的 Daily Deals 页面当前展示的促销商品,无需提供搜索关键词。可选参数 domain 用于选择 13 个已验证站点之一(com、co.uk、de、com.au、ca、fr、it、es、nl、at、ch、ie、pl),同时决定币种和本地商品;可选参数 max_results 设置返回的特价卡片数量,最多 240。响应采用 ok/meta/data 外层结构,data.results[] 中每张卡片对应一个特价商品,包含 item_id、title、price{value, currency, raw}、was_price{value, currency, raw}、shipping、deal_badge、image 和 url。实测示例(domain 为 com,max_results 为 5):返回 5 张以美元计价的卡片,其中 4 张带有 was_price 对象,1 张的 was_price 为 null;shipping 为文本 Free shipping 或 null;所有卡片的 deal_badge 均为 null,因此 was_price、shipping 和 deal_badge 都应按可选字段处理。meta.record_count 为 5,meta.domain 为 com。
主动测试请求 必填 0 项,可选 2 项
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body |
调用成本暂不可用,未假定任何价格。
商品详情
/api/project/ebay/item-detail 通过商品 ID 或商品链接获取 eBay 商品完整详情,含价格、卖家、运费、退货政策和商品规格。
完整文档 →说明
返回单个 eBay 商品的完整详情记录,可用 item_id(商品链接中 /itm/ 后面的数字)或完整的商品链接 url 指定,二者提供其一即可。domain 用于选择 13 个已验证站点之一(com、co.uk、de、com.au、ca、fr、it、es、nl、at、ch、ie、pl);将 include_description 设为 true 会内联完整的卖家描述文本,代价是多一次请求。响应采用 ok/meta/data 外层结构,data.item 即商品信息。实测示例(item_id 为 287070621317,domain 为 com):返回 item_id、title、url、price{value, currency, raw}、list_price、condition、availability、brand、model、mpn、images[](url、width、height,有时带 description)、含 22 项的 item_specifics{}、seller{name, feedback_pct, feedback_count}、shipping{country, currency, rate}、return_policy{days, method}、best_offer、quantity_available、quantity_sold、watchers、end_time、attributes{dimensions, weight} 和 description_url。该样本中 seller.feedback_pct、seller.feedback_count、category_path 以及 attributes 的两个值均为 null。另有文档说明但本次实测商品未涉及的字段:拍卖商品的 bids、current_bid 和 time_left,多规格商品的 variations[]{dimension, values[]{value, out_of_stock}},以及设置 include_description 后出现的 description 字段。
主动测试请求 必填 0 项,可选 4 项
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body | ||
| body |
更多可选参数 (1)
| 参数 | 位置 | 值 |
|---|---|---|
| body |
调用成本暂不可用,未假定任何价格。
/api/project/ebay/items-batch 一次请求批量获取多个 eBay 商品的完整详情,查不到的商品 ID 会列在 not_found 中,并按商品 ID 逐个计费。
完整文档 →说明
按商品编号一次查询多个 eBay 商品,并为每个商品返回与单商品详情接口相同的完整记录。item_ids 填写以英文逗号分隔的字符串,每个编号取自商品链接 /itm/ 之后的那串数字;还可以通过 domain 选择站点(已验证 13 个站点,如 com、co.uk、de、com.au、ca),以决定查询的 eBay 站点和结算币种。接口概述写明单次最多 40 个 ID,而 item_ids 参数说明写的是单次最多 15 个,因此如果想保持在更严格的限制内,请按每批 15 个拆分。响应采用 ok/meta/data 三段式结构:data.items[] 中每条记录包含 item_id、title、url、price{value,currency,raw}、list_price、condition、availability、brand、model、mpn、images[]、category_path、item_specifics{}、seller{name,feedback_pct,feedback_count}、shipping{rate,currency,country}、return_policy{days,method}、best_offer、end_time、watchers、quantity_available、quantity_sold,拍卖类商品还会附带 bids、current_bid 等拍卖字段。已下架、被移除或无效的 ID 不会被悄悄丢弃,而是列在 data.not_found[] 中;meta.requested 与 meta.upstream_calls 则告诉你本次提交了多少个 ID、实际计费了多少次。计费按商品 ID 而不是按请求:eBay 没有批量商品接口,所以 N 个 ID 的费用与 N 次单商品查询相同,批量调用节省的是耗时而非费用(接口说明中的实测数据为 8 个 ID 顺序调用 25.6 秒,批量调用 4.1 秒)。一次实际探测(item_ids 为 287070621317,301782776848,domain 为 com)的结果:HTTP 200,ok 为 true,meta.requested 为 2,meta.upstream_calls 为 2,返回两条在售且 InStock 的记录,not_found 为空数组,data.unavailable 为 null。该次探测中第一条记录的 seller.feedback_pct、seller.feedback_count、category_path 和 return_policy 均为 null,所以这些字段请按可选字段处理;第二条记录则返回了 return_policy {days 30, method ReturnByMail} 以及三级分类路径。40 个 ID 的上限、拍卖字段以及非空的 not_found 数组来自接口说明和文档示例,并非探测所得。
主动测试请求 必填 1 项,可选 1 项
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body |
调用成本暂不可用,未假定任何价格。
商品搜索
/api/project/ebay/search 按关键词搜索 eBay 在售商品,支持成色、价格、销售方式、运费、所在地和自提筛选,返回分页的商品卡片。
完整文档 →说明
按关键词搜索 eBay 在售商品,以 JSON 返回分页的商品卡片。query 是唯一必填参数。可选筛选包括:domain(13 个已验证站点)、category(eBay 数字类目 ID,可用 categories 操作按名称查询)、condition(new、open_box、refurbished、used、for_parts)、以站点币种计价的 price_min 与 price_max、布尔开关 buy_it_now、auction、best_offer、free_shipping 和 returns_accepted,以及 location(domestic、us、uk、worldwide、north_america、european_union),其可选值沿用各站点自带的商品所在地筛选,因此取决于 domain。pickup_postcode 搭配 pickup_distance(单位英里,默认 25)可限定英国上门自提的商品,且需要 domain 为 co.uk。sort 支持 best_match、newly_listed、ending_soonest、price_low 和 price_high,选项列表中还包含 price_asc 与 price_desc。page 与 max_results 控制分页;max_results 取值 1 到 240,超过 240 的值会被截断为 240。响应为 ok/meta/data 结构:data.query 回显搜索词,data.results[] 包含 item_id、title、price{value,currency,raw}、condition、buying_format、shipping、location、image 和 url,部分卡片还带有 sold_count、catalog_rating 和 best_offer,meta.pagination 返回 page 与 has_more。实测记录(query 为 iphone 13 pro,domain 为 com,max_results 为 5):HTTP 200,ok 为 true,返回 5 张卡片,meta.record_count 为 5,meta.pagination 为 {page 1, has_more true}。实测卡片还带有 buying_format_code(buy_it_now)、in_stock、aspects[]、形如“42+ sold”的 sold_count 文本、catalog_rating{average,review_count},以及精简的 seller{username,positive_pct,feedback_count,top_rated_plus} 对象,其中有一张卡片缺少 top_rated_plus;不过操作说明指出,完整的卖家数据只在商品详情页提供。shipping 是展示文本,例如“Free delivery in 1-2 days”或“+$7.72 delivery”,并非数值。除 domain 和 max_results 外,其他筛选条件在实测中未被验证;约 450 页的翻页深度和每页最多 240 条的上限来自操作说明中的测量记录(2026-08-07,query 为 iphone 13 pro)。
主动测试请求 必填 1 项,可选 16 项
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body |
更多可选参数 (11)
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body |
调用成本暂不可用,未假定任何价格。
卖家店铺
/api/project/ebay/seller-items 按用户名列出 eBay 卖家店铺内的全部在售商品,支持筛选、排序和分页。
完整文档 →说明
以结构化 JSON 返回某个 eBay 卖家店铺里的全部在售商品,无需关键词就能扫描竞争对手或供货商的完整商品目录。唯一必填的参数是 seller,即 eBay 卖家用户名,也就是网址 /usr/{seller} 里的那段名称,或商品页“Sold by”链接中的名称(eBay 链接里的 _ssn 值)。其余可选参数沿用搜索接口的筛选方式:domain(已验证 13 个站点,按操作说明,com.sg、com.hk 等其他 eBay 国家站点同样可用)、category(eBay 数字类目 ID,可用 categories 操作按名称查询)、condition(new、open_box、refurbished、used、for_parts)、以站点币种计价的 price_min 与 price_max、布尔开关 best_offer、free_shipping 和 returns_accepted、location(domestic、us、uk、worldwide、north_america、european_union,可选项遵循各站点自带的商品所在地筛选,因此取决于 domain)、pickup_postcode 配合 pickup_distance(单位为英里,默认 25;仅适用于英国当面自提,需要 domain 为 co.uk),以及 sort(best_match、newly_listed、ending_soonest、price_low、price_high)。page 和 max_results 用于翻页遍历整个目录,max_results 每页取值 1 到 240,超过 240 会被截为 240。响应采用 ok/meta/data 三段式结构:data.seller 为卖家用户名,data.results[] 是商品卡片,包含 item_id、title、price{value,currency}、condition、buying_format、shipping、location、image 和 url,meta.pagination 给出分页状态,其中包括 has_more。实测探测结果(卖家 musicmagpie,domain 为 co.uk,max_results 为 5):HTTP 200,ok 为 true,存在 meta.pagination,data.seller 为字符串,data.results 是包含 5 张卡片的数组。已存档的源示例并未经过探测验证,来自另一次不同的调用(价格为美元,链接指向 ebay.com);其中部分卡片还带有 price.raw、形如“1,062 sold”的 sold_count 文本和 catalog_rating{average,review_count},运费显示为“+$4.71 delivery”这样的展示文本,而 condition 字段里是卖家的宣传语而不是成色标签,因此请把卡片上的 condition 当作展示文本,需要按成色过滤时请使用 condition 筛选参数。除 domain 和 max_results 之外的筛选参数没有在探测中验证过,操作说明中提到的翻页深度上限是在搜索查询上测得的,并非针对店铺目录。
主动测试请求 必填 1 项,可选 14 项
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body | ||
| body | ||
| body |
更多可选参数 (11)
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body | ||
| body |
调用成本暂不可用,未假定任何价格。
卖家信誉
/api/project/ebay/seller-profile 按用户名查询 eBay 卖家的信用评分、好评率、评分明细,以及金牌卖家和商家身份。
完整文档 →说明
以结构化 JSON 返回某位 eBay 卖家的公开信誉数据。唯一必填的参数是 seller,即 eBay 卖家用户名,也就是网址 /usr/{seller} 里的那段名称,或商品页“Sold by”链接中的名称。domain 为可选参数,用于选择 eBay 站点(已验证 13 个站点,按操作说明,com.sg、com.hk 等其他 eBay 国家站点同样可用)。调用时无需你自己拥有 eBay 账号,也不需要卖家授权,数据来自公开可见的卖家信息。响应采用 ok/meta/data 三段式结构,data.seller_profile 按文档包含 store_name、feedback_score、feedback_positive_pct、positive_pct_12mo、items_sold_display、followers_display、member_since、location、business_seller、top_rated 和 feedback_ratings,其中 feedback_ratings 是一个对象,含 positive、neutral、negative 三项,每一项都带有 m1、m6、m12 三个计数。实测探测结果(卖家 musicmagpie,domain 为 co.uk):HTTP 200,ok 为 true,存在 meta,data.seller_profile 是一个对象,其中包含 seller、feedback_score、positive_pct_12mo、feedback_ratings 和 detailed_seller_ratings 等字段。已存档的源示例并未经过探测验证,其 meta 中的 domain 为 com;示例里 feedback_score 是一个很大的整数,feedback_positive_pct 和 positive_pct_12mo 是形如 99.1 的百分比,items_sold_display 和 followers_display 是“51.1M”“487K”这类缩写的展示字符串而不是数字,member_since 是形如“Feb-02-11”的展示日期,location 是国家名称,business_seller 和 top_rated 是布尔值,detailed_seller_ratings 则是 Accurate description(与描述相符)、Communication(沟通)、Reasonable shipping cost(运费合理)和 Shipping speed(发货速度)四项五分制评分。示例中出现的是 seller 字段而没有 store_name,因此不要假定 store_name 一定存在。示例的 meta 还带有 record_count 和 feedback_upstream_error 标记(示例中为 false),建议记入日志。目前只探测过一位卖家(musicmagpie),对于不存在的卖家名称,其行为尚未验证。
主动测试请求 必填 1 项,可选 1 项
| 参数 | 位置 | 值 |
|---|---|---|
| body | ||
| body |
调用成本暂不可用,未假定任何价格。
可用的数据能力
通过 JSON 接口获取 ebay.com、ebay.co.uk、ebay.de 等 eBay 站点的结构化商品与卖家数据,无需自己申请 eBay 开发者账号、处理 OAuth 令牌或解析 HTML 页面。
- 商品搜索:按关键词查询在售商品,支持成色、价格区间、一口价、拍卖、接受还价、包邮、可退货、商品所在地和自提筛选,并可排序、翻页
- 商品详情:按商品 ID 或商品链接获取单个商品的完整记录,含价格、卖家、运费、退货政策、商品规格和多规格字段
- 批量商品查询:一次请求查询多个商品 ID,查不到的 ID 会单独列在 not_found 中
- 卖家店铺:按卖家用户名列出其全部在售商品,同样支持筛选、排序与分页
- 卖家信誉:反馈评分、好评率、按时间窗口统计的评价数量,以及金牌卖家和商家身份标记
- 每日特价:当前特价榜单,含促销价、原价和运费标签
- 类目查询:按类目名称查出数字类目 ID,并列出各站点的一级大类
采用 RESTful JSON 接口,适合价格监控、竞品店铺跟踪、特价信息流、跨境选品调研和商品目录补全。返回结果描述的是当前在售商品和卖家公开信息,不是历史成交价。