按关键词搜索 eBay 在售商品,支持成色、价格、销售方式、运费、所在地和自提筛选,返回分页的商品卡片。
查看 eBay 商品与卖家数据 API 的全部接口 →按关键词搜索 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)。
API 功能
在线 API 演示
未找到可用的 API Key,请前往控制台创建后刷新本页。 控制台 →
/api/project/ebay/search API 响应 (JSON)
{} curl -X POST 'https://api.opendata-api.com/api/project/ebay/search?key=<API_KEY>' \
-H 'Content-Type: application/json' \
-d '{"query":"<query>"}' 查询结果
使用场景
- 搭建套利扫描器:用 query、condition 为 new、price_max 并按 price_low 排序,一旦出现低于目标价的卡片就发出提醒
- 以 newly_listed 排序轮询复古相机、卡牌等细分品类,并按 item_id 去重,生成新上架商品信息流
- 在 com、co.uk 和 de 三个站点用同一关键词并开启 free_shipping 与 returns_accepted,比较哪个站点的到手价最划算
- 为大件商品做同城自提查找工具:在 co.uk 站点用 pickup_postcode 和 pickup_distance 筛选可上门自提的商品
- 先用 categories 操作查到类目 ID,再以每页 240 条的方式翻遍该类目,用于市场调研
- 把已知的约 6 个 item ID 以 (id1,id2,...) 形式放入 query,批量刷新价格和库存卡片,而不必拉取完整商品记录
- 分别开启 buy_it_now 和 auction 调用两次 search,统计某个商品一口价与拍卖挂牌的数量对比
常见问题
如何翻遍某个关键词的全部搜索结果?
保持 max_results 不变,依次递增 page(1、2、3……),直到 meta.pagination.has_more 变为 false。实测第 1 页返回 5 张卡片且 has_more 为 true。操作说明针对 iphone 13 pro 这个关键词测得约第 450 页仍有完整不重复的结果,第 470 页为空页,所以请一直翻到 has_more 结束,不必去试探最后一页。
每页最多能取多少条?
240 条。max_results 取值 1 到 240,超过 240 会被截断为 240;说明中测得 60、120、200、240 都能按数量返回,而 300 或 500 并不会返回更多。需要超过 240 条时请用 page 继续翻页。
怎样按 eBay 类目筛选?
在 category 中传入数字类目 ID,例如参数说明里给出的 9355 对应 Cell Phones & Smartphones。如果只知道类目名称,先调用 categories 操作查出 ID,再在这里使用。category 留空则搜索全部类目。
能用一次 search 调用查询多个已知的商品 ID 吗?
操作说明提到,query 可写成 (id1,id2,id3) 的形式,也就是 eBay 自带的 OR 语法,每次大约能解析 6 个 ID,第 7 个会被丢弃,且只返回卡片级字段。这比拉取完整记录更省成本;如果需要商品属性、卖家详情或退货政策,请使用 items-batch。这一行为来自操作说明,并非实测结果。
为什么 location 筛选取决于 domain?
location 的可选值对应各站点自带的“商品所在地”筛选。domestic 表示商品位于该站点所在国家(com 仅限美国,co.uk 仅限英国);uk 与 domestic 等效,且需要 domain 为 co.uk;区域选项在 com 上是 North America,在 co.uk 上是 European Union。
本地自提筛选如何使用?
在 domain 为 co.uk 时,把 pickup_postcode 设为英国邮编,即可只保留附近可上门自提的商品,并可再用 pickup_distance 指定英里数。eBay 提供 10、25、50、100、200 和 500 几个档位(默认 25),其他数值会按下一个更大的档位处理;说明中记录,传入 7 时返回的恰好是 10 英里的结果。pickup_distance 只能与 pickup_postcode 一起使用。
结果卡片里的运费和成色是什么样的?
shipping 是展示文本而不是数字:实测返回过“Free delivery in 1-2 days”和“+$7.72 delivery”这样的值。condition 在实测中返回过“Excellent - Refurbished”和“Pre-Owned”这样的标签,但文档中的示例响应里有些卡片的 condition 装的是卖家副标题文字,所以要按成色细分请使用 condition 筛选参数,不要对卡片上的字符串做精确匹配。
搜索结果里包含卖家信息吗?
实测卡片带有精简的 seller 对象,包含 username、positive_pct、feedback_count,有时还有 top_rated_plus;但操作说明指出,完整的卖家数据只在商品详情页提供,所以不要假定每张卡片都带齐所有卖家字段。需要完整的卖家信誉信息时,请使用 item-detail、items-batch 或卖家资料操作。
sort 可以用哪些取值?
操作说明列出的取值是 best_match、newly_listed、ending_soonest、price_low 和 price_high。选项列表中还有 price_asc 与 price_desc,但说明里没有介绍它们的行为,实测也没有验证过。