闲鱼 Xianyu API

按关键词搜索闲鱼在售二手商品，再用返回的 item_id 或商品链接批量读取详情：成色、想要人数、浏览与收藏数、全部图片、描述、所在城市和卖家好评率；按商品数计费，没取到的商品不收费。调用 POST /api/v1/social ；返回结构化 JSON，$5.56 / 千次；失败不计费。

免费开始看文档

个能力

$5.56 / 千次

能力价格

同步

调用模式

1 个

一把 Key 通用 90 个平台

闲鱼 Xianyu 能力清单

能力	必填参数	可选参数	单次条数	模式	单价	返回字段
search	keyword	—	默认 20 · 最多 50	同步	$5.56 / 千次	item_id · url · title · price · original_price · currency · city · image_url · want_count · tags · category_id · free_shipping · is_auction · has_video · posted_at · seller_id · seller_name · platform
item_detail	urls	—	—	同步	$5.56 / 千次	item_id · url · title · text · price · original_price · currency · shipping_fee · condition_level · status · quantity · want_count · view_count · collect_count · sold_count · province · city · category_id · image_url · images · posted_at · seller_id · seller_name · seller_url · seller_item_count · seller_sold_count · seller_good_review_rate · seller_reply_rate_24h · platform

闲鱼 Xianyu 每个接口分别做什么

下面逐个解释 action、必填参数、可选筛选项和允许值。请求都发到 POST /api/v1/social，切换 action 时，也要按对应接口调整参数。同名参数在不同平台、不同接口中可能指向不同对象；请以该条说明中的格式和适用范围为准。

下方只展示平台官方资料，用于核对对象与术语，不表示平台对 EveryInfra 的授权或背书。本接口接受的参数、字段与能力边界以各条说明为准，不与平台官方 API 直接等同。

怎么调用闲鱼 Xianyu 关键词搜索 API？

search

使用 platform="xianyu"、action="search" 调用“关键词搜索”能力；返回列表，默认 20 条、单次最多 50 条，主要包含 item_id、url、title、price、original_price、currency 等 18 个字段。

查看完整接口文档：参数、代码示例、响应样例与健康状态 →

keyword 是闲鱼站内搜索词，中文词或型号词更容易命中；默认返回 20 条，最多 50 条。

{
  "platform": "xianyu",
  "action": "search",
  "params": {
    "keyword": "iPhone 15"
  }
}

闲鱼 Xianyu search 的参数分别是什么意思？

keyword必填: 闲鱼站内搜索词，1–100 个字符；卖家标题里常见的中文词或型号词更容易命中。

闲鱼 Xianyu 特有返回字段与含义（11）

item_id: 闲鱼商品数字 ID（字符串）；可直接放进 item_detail 的 urls。
original_price: 卖家填写的原价（元）；没填时为 null。
city: 商品所在地，按闲鱼页面显示到城市，部分商品只显示到省份；不返回更精确的位置。
want_count: 想要人数，即点过「我想要」的用户数。搜索结果取自商品卡片上的「N人想要」，卡片没显示时为 null；null 不等于 0。
tags: 商品卡片上的标签，如「全新」「包邮」、品牌或降价提示；想要人数单独放在 want_count。无标签时为空数组。
category_id: 闲鱼类目 ID（字符串）。
free_shipping: 是否包邮。
is_auction: 是否为拍卖商品；拍卖商品的 price 是当前出价。
has_video: 商品是否带视频。
seller_id: 卖家数字 ID（字符串）。
seller_name: 卖家昵称。闲鱼对未登录访问会部分打码（如「南***鱼」），按页面显示原样返回。

怎么调用闲鱼 Xianyu 商品详情 API？

item_detail

使用 platform="xianyu"、action="item_detail" 调用“商品详情”能力；返回列表，主要包含 item_id、url、title、text、price、original_price 等 29 个字段。

查看完整接口文档：参数、代码示例、响应样例与健康状态 →

替换为 search 返回的 item_id 或 goofish.com 商品链接；urls 一次 1–20 个，按商品数计费，读不到的商品按个数退款。

{
  "platform": "xianyu",
  "action": "item_detail",
  "params": {
    "urls": [
      "https://www.goofish.com/item?id=<ITEM_ID>"
    ]
  }
}

闲鱼 Xianyu item_detail 的参数分别是什么意思？

urls必填: 闲鱼商品数组，一次 1–20 个；每项填纯数字商品 ID（search 返回的 item_id）或 https://www.goofish.com/item?id=<数字> 商品链接，同一商品只能出现一次。按商品数计费，没取到的商品按个数退款。暂不接受 App 分享短链。
阿里巴巴开放平台的「服务商闲鱼商品查询」接口以闲鱼商品 Id（长整型）定位单个商品，并用 stuff_status 表示新旧程度：100 为全新、95 为 95 新、-1 为准新。该接口需授权、只能在聚石塔内调用；这里只用于确认商品标识与成色口径，不代表 EveryInfra 使用该接口，也不证明可以读取任意商品的全部字段。官方来源：阿里巴巴开放平台：闲鱼商品 ID 与新旧程度来源核查：2026-09-29

闲鱼 Xianyu 特有返回字段与含义（19）

item_id: 闲鱼商品数字 ID（字符串）；可直接放进 item_detail 的 urls。
original_price: 卖家填写的原价（元）；没填时为 null。
city: 商品所在地，按闲鱼页面显示到城市，部分商品只显示到省份；不返回更精确的位置。
want_count: 想要人数，即点过「我想要」的用户数。搜索结果取自商品卡片上的「N人想要」，卡片没显示时为 null；null 不等于 0。
category_id: 闲鱼类目 ID（字符串）。
seller_id: 卖家数字 ID（字符串）。
seller_name: 卖家昵称。闲鱼对未登录访问会部分打码（如「南***鱼」），按页面显示原样返回。
province: 商品所在省份；不返回区县或更精确的位置。
sold_count: 该商品的已售件数。闲鱼多数商品不显示这个计数，0 和未显示都返回 null，不代表没有卖出。
seller_url: 卖家在闲鱼的主页链接。
condition_level: 成色，10 分制：10 为全新，9.5 为 95 新，依此类推；卖家没标时为 null。
shipping_fee: 邮费（元）；0 表示包邮。
quantity: 卖家标注的可售数量；二手闲置多为 1。
status: 商品状态，按闲鱼页面显示的原文返回，如「在线」。
images: 商品全部图片链接，最多 20 张，第一张通常是主图。
seller_item_count: 卖家主页显示的在售商品数。
seller_sold_count: 卖家主页显示的累计卖出件数。
seller_good_review_rate: 卖家好评率，百分数（98 表示 98%）；主页没显示时为 null。
seller_reply_rate_24h: 卖家 24 小时内回复率，百分数（99 表示 99%）；主页没显示时为 null。

一次闲鱼 Xianyu search 调用的全过程：向 POST /api/v1/social 发送 platform="xianyu"、action="search"，以及必填参数 keyword;返回结构化 JSON，含 item_id、url、title、price、original_price 等字段；返回列表，单次最多 50 条，计费 $5.56 / 千次，失败与空结果不计费。

闲鱼 Xianyu 的独有字段名（当前目录）

全站 90 个平台的当前目录中，这 9 个字段名只在闲鱼 Xianyu 出现。这是字段命名的分布，不代表其他平台没有同类信息，也不保证每次响应都含这些字段；具体含义和返回条件仍需逐接口核对。

want_count
is_auction
condition_level
quantity
seller_url
seller_item_count
seller_sold_count
seller_good_review_rate
seller_reply_rate_24h

返回字段含义

通用字段采用统一命名；切换平台时仍需核对目标格式、字段是否存在、类型、空值与平台特有含义。机器可读版：/api/v1/social/fields

item_id: 闲鱼商品数字 ID（字符串）；可直接放进 item_detail 的 urls。
url: 该记录在原平台上的可访问链接。
title: 标题。平台无标题概念时（如纯文本帖）为 null。
price: 价格数值，不含货币符号；币种见 currency。
original_price: 卖家填写的原价（元）；没填时为 null。
currency: 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。
city: 商品所在地，按闲鱼页面显示到城市，部分商品只显示到省份；不返回更精确的位置。
image_url: 图片链接。多图能力可能返回 image_urls 数组。
want_count: 想要人数，即点过「我想要」的用户数。搜索结果取自商品卡片上的「N人想要」，卡片没显示时为 null；null 不等于 0。
tags: 商品卡片上的标签，如「全新」「包邮」、品牌或降价提示；想要人数单独放在 want_count。无标签时为空数组。
category_id: 闲鱼类目 ID（字符串）。
free_shipping: 是否包邮。
is_auction: 是否为拍卖商品；拍卖商品的 price 是当前出价。
has_video: 商品是否带视频。
posted_at: 发布时间，ISO 8601 格式、UTC 时区（如 2026-08-07T12:34:56+00:00）。平台只给非标准字符串时原样透传，解析前建议做容错。null 表示平台未公开。
seller_id: 卖家数字 ID（字符串）。
seller_name: 卖家昵称。闲鱼对未登录访问会部分打码（如「南***鱼」），按页面显示原样返回。
platform: 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。
text: 正文内容，已去除 HTML 标签。长文可能被截断。
shipping_fee: 邮费（元）；0 表示包邮。
condition_level: 成色，10 分制：10 为全新，9.5 为 95 新，依此类推；卖家没标时为 null。
status: 商品状态，按闲鱼页面显示的原文返回，如「在线」。
quantity: 卖家标注的可售数量；二手闲置多为 1。
view_count: 浏览/播放数。null 表示不公开，不等于 0。
collect_count: 收藏数。null 表示不公开，不等于 0。
sold_count: 该商品的已售件数。闲鱼多数商品不显示这个计数，0 和未显示都返回 null，不代表没有卖出。
province: 商品所在省份；不返回区县或更精确的位置。
images: 商品全部图片链接，最多 20 张，第一张通常是主图。
seller_url: 卖家在闲鱼的主页链接。
seller_item_count: 卖家主页显示的在售商品数。
seller_sold_count: 卖家主页显示的累计卖出件数。
seller_good_review_rate: 卖家好评率，百分数（98 表示 98%）；主页没显示时为 null。
seller_reply_rate_24h: 卖家 24 小时内回复率，百分数（99 表示 99%）；主页没显示时为 null。

请求填写示例

先按关键词搜在售二手商品并保存返回的 item_id；详情用 item_detail 的 urls 批量读取。

以下为填写格式示意，并非成功调用记录。请替换 API Key 和尖括号中的目标，确认可选筛选项后再调用；示例不保证目标当前有数据。

xianyu_search.sh

curl -X POST https://api.everyinfra.com/api/v1/social \
  -H "Authorization: Bearer 你的 API Key" \
  -H "Content-Type: application/json" \
  -d '{"platform":"xianyu","action":"search","params":{"keyword":"iPhone 15"}}'

记录字段预览（非真实响应）

仅展示 search 的记录字段，不包含外层响应、计费或任务状态。null 只作展示占位，不表示字段类型或实际空值；完整响应须以接口文档与实际调用为准。

fields.preview.json

{
  "item_id": null,
  "url": null,
  "title": null,
  "price": null,
  "original_price": null,
  "currency": null,
  "city": null,
  "image_url": null,
  "want_count": null,
  "tags": null,
  "category_id": null,
  "free_shipping": null,
  "is_auction": null,
  "has_video": null,
  "posted_at": null,
  "seller_id": null,
  "seller_name": null,
  "platform": null
}

常见用例

以下是基于现有接口的接入思路，不是开箱即用的分析或告警功能。字段以实际返回为准，缺失值不按零处理。

按关键词查看闲鱼在售二手商品

用 search 的 keyword 搜站内在售商品，按价格、想要人数和所在城市初筛，再把 item_id 交给 item_detail。

查看 search 的 keyword 参数 →

keyword 与卖家标题用词越接近越容易命中，limit 默认 20、最多 50；每条返回 item_id、title、price、want_count、city 与 posted_at。want_count 取自商品卡片上的「N人想要」，卡片没显示时为 null。
结果是请求当时站内默认顺序的一页快照，不是全部在售商品；二手商品随时可能售出或下架，下单前用 item_detail 复核当前状态。

批量核对闲鱼商品的成色、热度与卖家信誉

把 search 返回的 item_id 或商品链接放进 urls，一次 1–20 个，每个商品返回一行详情。

查看 item_detail 的 urls 参数 →

condition_level 是 10 分制成色（9.5 即 95 新）；want_count、view_count、collect_count 分别是想要、浏览、收藏人数；seller_good_review_rate 与 seller_sold_count 是卖家主页显示的好评率和累计卖出件数。
按商品数计费。已售出、下架或暂时读不到的商品列在响应的 missed 里并按个数退款；sold_count 为 null 表示闲鱼没有显示，不代表没有卖出。

闲鱼 Xianyu API 常见问题

闲鱼 Xianyu API 怎么调用？

调用 POST /api/v1/social，请求体传 platform="xianyu"、action 和 params。以 search 为例，必填 keyword，没有可选参数。先按关键词搜在售二手商品并保存返回的 item_id；详情用 item_detail 的 urls 批量读取。闲鱼 Xianyu 共 2 个 action，鉴权用 Authorization: Bearer <API Key>,同一把 Key 通 90 个平台。

闲鱼 Xianyu API 怎么收费？

$5.56 / 千次，闲鱼 Xianyu 全部 2 个能力同价。按本页最高能力单价、每次单目标估算，$1 免费额度约可用于 179 次闲鱼 Xianyu 调用。费用按所选能力与目标数量计算，多目标请求不要按单目标估算；参数错误、鉴权失败和空结果不计费。

闲鱼 Xianyu API 一次能返回多少条数据？

闲鱼 Xianyu 有 2 个列表接口，包括 search、item_detail。数量参数要逐接口区分目标数、页数和记录数，不能将目录数值直接当作保证返回的条数；具体限制见对应参数与用例，不保证完整历史。

闲鱼 Xianyu API 返回哪些字段？

当前目录为 search 列出 item_id、url、title、price、original_price、currency 等 18 个字段名。按全站当前目录统计，9 个字段名只在闲鱼 Xianyu 出现；这不表示其他平台没有同类信息。字段不保证每次齐全，嵌套位置、类型与空值须按各接口说明核对，同名字段不代表语义可互换。

闲鱼 Xianyu API 的能力都能异步调用吗？

item_detail 只能同步调用：一次请求里逐个读取批量里的每个目标，按目标数计费；请求体带 "mode": "async" 会在扣费前返回 422。其他能力可以在请求体加 "mode": "async"，先拿到 job_id，再轮询 GET /api/v1/jobs/{job_id} 取结果。

「按关键词查看闲鱼在售二手商品」怎样接入闲鱼 Xianyu API？

用 search 的 keyword 搜站内在售商品，按价格、想要人数和所在城市初筛，再把 item_id 交给 item_detail。 keyword 与卖家标题用词越接近越容易命中，limit 默认 20、最多 50；每条返回 item_id、title、price、want_count、city 与 posted_at。want_count 取自商品卡片上的「N人想要」，卡片没显示时为 null。结果是请求当时站内默认顺序的一页快照，不是全部在售商品；二手商品随时可能售出或下架，下单前用 item_detail 复核当前状态。

「批量核对闲鱼商品的成色、热度与卖家信誉」怎样接入闲鱼 Xianyu API？

把 search 返回的 item_id 或商品链接放进 urls，一次 1–20 个，每个商品返回一行详情。 condition_level 是 10 分制成色（9.5 即 95 新）；want_count、view_count、collect_count 分别是想要、浏览、收藏人数；seller_good_review_rate 与 seller_sold_count 是卖家主页显示的好评率和累计卖出件数。按商品数计费。已售出、下架或暂时读不到的商品列在响应的 missed 里并按个数退款；sold_count 为 null 表示闲鱼没有显示，不代表没有卖出。

可以先免费试用闲鱼 Xianyu API 吗？

可以。注册免费，加微信领 $1 额度码（≈720 次数据调用），注册后在控制台「余额与充值」兑换，进入赠送余额。请先选择闲鱼 Xianyu 的目标接口，用单目标请求核对结果；实际可调用次数取决于能力价格与目标数量，不保证覆盖全部 2 个能力。无需信用卡。

1688 API 速卖通 API Amazon API Craigslist API 得物 Dewu API eBay API Etsy API 京东 JD.com API 全部 90 平台 ↗

开始调用闲鱼 Xianyu API

加微信领 $1 额度码，注册后在控制台兑换，先选一个闲鱼 Xianyu 接口验证结果。实际可调用次数取决于能力价格与目标数量。

免费开始