按关键词搜索 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 功能

13 个站点的关键词搜索 传入 query 并按需指定 domain(com、co.uk、de、com.au、ca、fr、it、es、nl、at、ch、ie、pl),即可获取以该站点币种计价的在售商品。
按本地币种设定价格区间 price_min 与 price_max 按站点币种限定价格范围,可把同一个关键词的结果压缩到目标价位以内的商品。
成色与销售方式筛选 可只看 new、open_box、refurbished、used 或 for_parts 成色的商品,也可只看一口价(buy_it_now)、拍卖(auction)或接受还价(best_offer)的商品,让每次扫描只覆盖一个细分类别。
运费、退货与还价筛选 free_shipping 与 returns_accepted 可把结果收窄到包邮或支持退货的商品,方便对比到手价。
商品所在地与到店自提 location 沿用站点自带的商品所在地筛选;pickup_postcode 搭配 pickup_distance(domain 为 co.uk)可找出英国可上门自提的商品。
含最新上架在内的多种排序 sort 支持 best_match、newly_listed、ending_soonest、price_low 和 price_high,同一个关键词既能做新上架信息流,也能做价格从低到高的扫描。
单页最多 240 条的深度翻页 max_results 每页最多返回 240 张卡片,再用 page 继续往后翻;说明中的测量显示最多可取到约第 450 页的完整不重复结果。当 meta.pagination.has_more 为 false 时停止即可。
卡片可直接衔接后续查询 每张卡片都有 item_id、url、price、buying_format、运费文本和 image,拿到的 ID 可直接传给 item-detail 或 items-batch 获取完整商品记录。

在线 API 演示

POST /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>"}'
📢
需要帮助?
如遇接口异常,或需要其他接口需求,可联系我们
联系我们

使用场景

常见问题

如何翻遍某个关键词的全部搜索结果?

保持 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,但说明里没有介绍它们的行为,实测也没有验证过。

相关接口

相关指南

查看订阅方案 →