# 闲鱼 Xianyu 商品详情 API (xianyu.item_detail)

- Canonical page: https://everyinfra.com/xianyu-api/item_detail
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "xianyu", "action": "item_detail", "params": {...}}
- Price: $0.005556 per call ($5.56 per 1,000 requests); failed calls and empty results are not charged
- Returns: list
- Mode: sync only; everything it returns (every target of a batch, or every SKU of a product) is read in one call, and "mode": "async" returns 422 before any charge

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=xianyu&action=item_detail

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| urls | not declared | yes | not declared | 闲鱼商品数组，一次 1–20 个；每项填纯数字商品 ID（search 返回的 item_id）或 https://www.goofish.com/item?id=<数字> 商品链接，同一商品只能出现一次。按商品数计费，没取到的商品按个数退款。不接受 App 分享短链。 |
| limit | integer (1–) | no | not declared | 这次调用最多返回的条数，整数，至少为 1；不传按默认值，实际返回可能少于这个数。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| item_id | 闲鱼商品数字 ID（字符串）；可直接放进 item_detail 的 urls。 |
| url | 该记录在原平台上的可访问链接。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| price | 价格数值，不含货币符号；币种见 currency。 |
| original_price | 卖家填写的原价（元）；没填时为 null。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| shipping_fee | 邮费（元）；0 表示包邮。 |
| condition_level | 成色，10 分制：10 为全新，9.5 为 95 新，依此类推；卖家没标时为 null。 |
| status | 商品状态，按闲鱼页面显示的原文返回，如「在线」。 |
| quantity | 卖家标注的可售数量；二手闲置多为 1。 |
| want_count | 想要人数，即点过「我想要」的用户数。搜索结果取自商品卡片上的「N人想要」，卡片没显示时为 null；null 不等于 0。 |
| view_count | 浏览/播放数。null 表示不公开，不等于 0。 |
| collect_count | 收藏数。null 表示不公开，不等于 0。 |
| sold_count | 该商品的已售件数。闲鱼多数商品不显示这个计数，0 和未显示都返回 null，不代表没有卖出。 |
| province | 商品所在省份。 |
| city | 商品所在地，按闲鱼页面显示到城市，部分商品只显示到省份；更细的位置见 district、lat、lng、poi_name。 |
| category_id | 闲鱼类目 ID（字符串）。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| images | 商品全部图片链接，页面有几张给几张，第一张通常是主图。 |
| posted_at | 发布时间，ISO 8601 格式、UTC 时区（如 2026-08-07T12:34:56+00:00）。平台只给非标准字符串时原样透传，解析前建议做容错。null 表示平台未公开。 |
| seller_id | 卖家数字 ID（字符串）。 |
| seller_name | 卖家昵称。闲鱼对未登录访问会部分打码（如「南***鱼」），按页面显示原样返回。 |
| seller_url | 卖家在闲鱼的主页链接。 |
| seller_item_count | 卖家主页显示的在售商品数。 |
| seller_sold_count | 卖家主页显示的累计卖出件数。 |
| seller_good_review_rate | 卖家好评率，百分数（98 表示 98%）；主页没显示时为 null。 |
| seller_reply_rate_24h | 卖家 24 小时内回复率，百分数（99 表示 99%）；主页没显示时为 null。 |
| district | 商品所在区县，按页面原文返回；没给时没有这个字段。 |
| division_id | 商品所在地的行政区划代码（字符串，如 360100）；没给时没有这个字段。 |
| lat | 商品定位的纬度，按原值给出，未做坐标系换算（国内地图常用 GCJ-02）；没定位时没有这个字段。 |
| lng | 商品定位的经度，与 lat 成对出现；没定位时没有这个字段。 |
| poi_name | 卖家标注的地点（POI）名称，如商场、小区名；没标时没有这个字段。 |
| poi_id | 上面那个地点在闲鱼地图里的 ID（字符串）。 |
| seller_avatar_url | 卖家头像链接。 |
| seller_city | 卖家主页显示的所在城市，可能与商品所在地不同。 |
| seller_bio | 卖家主页的个性签名原文。 |
| seller_joined_at | 卖家注册闲鱼的时间，ISO 8601、UTC。 |
| seller_last_seen | 卖家最近一次来闲鱼的时间，按页面原文返回，如「5小时前来过」。 |
| seller_zhima_verified | 卖家是否开通并展示芝麻信用。 |
| seller_zhima_level | 卖家的芝麻信用等级名称，按页面原文返回，如「信用极好」。 |
| seller_zhima_level_code | 芝麻信用等级代码，如 A。 |
| seller_credit_level | 卖家的闲鱼信用等级（数字）。 |
| seller_identity_tags | 卖家主页的认证标签原文，如「实人认证已通过」。 |
| seller_other_items | 同一卖家的其他在售商品，每条有 item_id、url，页面有时还带 title、price、image_url。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "xianyu",
  "action": "item_detail",
  "params": {
    "urls": [
      "https://www.goofish.com/item?id=<ITEM_ID>"
    ]
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "xianyu",
        "action": "item_detail",
        "params": {
            "urls": [
                "https://www.goofish.com/item?id=<ITEM_ID>",
            ],
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

No real sample for these example parameters yet: structure only, every value is a placeholder (…).

```text
{
  "id": "req_…",
  "platform": "xianyu",
  "action": "item_detail",
  "results": [
    {
      "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": …,
      "district": …,
      "division_id": …,
      "lat": …,
      "lng": …,
      "poi_name": …,
      "poi_id": …,
      "seller_avatar_url": …,
      "seller_city": …,
      "seller_bio": …,
      "seller_joined_at": …,
      "seller_last_seen": …,
      "seller_zhima_verified": …,
      "seller_zhima_level": …,
      "seller_zhima_level_code": …,
      "seller_credit_level": …,
      "seller_identity_tags": …,
      "seller_other_items": …,
      "platform": …
    }
  ],
  "count": …,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=xianyu
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md