返回教程列表
教程2026年11月17日5 分钟阅读

闲鱼 API 怎么用?关键词搜索与商品详情接入教程

用 JustOneAPI 按关键词搜索闲鱼二手商品,再按已知商品 ID 请求详情;区分发现与跟踪,提供最多两次请求的 JSON 快照示例。

从关键词发现商品,再按 ID 查看详情

做闲鱼二手商品监测,通常有两种需求:按关键词找新出现的商品,以及继续查看已经选定的商品。JustOneAPI 提供闲鱼(GooFish)商品搜索 V1 和商品详情 V1,分别承接这两步。

搜索接口使用 keyword、page 和 sort;详情接口使用已知 itemId。本教程先保存一页搜索响应,再选择性地请求一个已知商品的详情,单次运行最多两次 API 请求。它不自动从搜索结果提取 ID,也不承诺覆盖全部在售商品或已有价格历史。

接入前准备

在 JustOneAPI 控制台获取 API Token,确认两个接口各自的权限、价格及可用试用次数。一个接口有权限,不代表另一个接口也已开通;实际可用性和具体费用以账户显示为准。

两条请求都发送到 https://api.justoneapi.com,HTTP 方法均为 GET,并通过查询参数传入 token。Token 放在本机环境变量中,不要写入文章、截图、共享命令记录或代码仓库。

第一步:按关键词请求搜索页

闲鱼商品搜索 V1的路径是 /api/xianyu/search-item-list/v1。必填参数为 token 和 keyword;page 为可选页码,第一页是 1,本例明确传入 "1"。

sort 默认是 active,当前文档列出的可选值如下:

  • active:优先显示活跃商品。
  • recent:优先显示附近或基于位置的最新结果。
  • credit:优先显示卖家信用高的商品。
  • price_asc、price_desc:价格从低到高、从高到低。
  • price_drop:优先显示降价商品。
  • newest:优先显示最新发布的商品。

如果你关心新发布的商品,可以先试 newest。recent 与 newest 的文档含义不同,不要仅凭英文词义互换。本例使用 active,方便先验证默认排序下的结果。

搜索得到的是该次关键词、页码和排序条件下的响应。分页期间商品可能变化;请求两页并不自动构成完整且不重复的商品清单。增加分页前,先确认实际结果中的列表路径、稳定商品标识和有依据的结束条件,再设置总页数与调用预算。

第二步:用已知 itemId 请求详情

闲鱼商品详情 V1的路径是 /api/xianyu/get-item-detail/v1,必填参数为 token 和 itemId。它用于读取已知商品的公开详情,不接受用关键词替代商品 ID。

先从你确认过的商品链接或实际搜索响应中核对商品 ID,再传入 itemId。不要把整段链接、卖家 ID 或关键词直接填进去。当前公开 OpenAPI 没有定义这两个接口 data 内的具体字段,因此本例不假设搜索列表在 data.items,也不假设 ID、价格或商品状态的字段名。

设置下面的 XIANYU_ITEM_ID 时,详情查询独立使用这个已知 ID;代码不会检查它是否出现在本次搜索结果中。不设置时只执行搜索,避免为了演示自动查询一个未经确认的商品。

示例:保存搜索页和一个已知商品的快照

安装依赖,设置 Token 和关键词。以下命令适用于 macOS 或 Linux,将占位 Token 替换为自己的值。

bash
python3 -m pip install requests
export JUSTONEAPI_TOKEN='your_token'
export XIANYU_KEYWORD='二手相机'
# 可选:确认商品 ID 后再设置;不设置则只搜索。
# export XIANYU_ITEM_ID='your_known_item_id'

将代码保存为 xianyu_sample.py,运行 python3 xianyu_sample.py。它请求第一页,最多再查一个已知商品;不自动重试,也不跟随重定向。HTTP 200 后仍检查业务 code=0 和 data 是否存在,失败时停止,已保存的成功响应保留。

python
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://api.justoneapi.com"
TOKEN = os.environ.get("JUSTONEAPI_TOKEN", "").strip()
KEYWORD = os.environ.get("XIANYU_KEYWORD", "").strip()
ITEM_ID = os.environ.get("XIANYU_ITEM_ID", "").strip()


def call_api(path, params):
    try:
        response = requests.get(
            BASE_URL + path,
            params={"token": TOKEN, **params},
            timeout=120,
            allow_redirects=False,
        )
    except requests.RequestException:
        raise RuntimeError("API network error or timeout") from None
    if response.status_code != 200:
        raise RuntimeError(f"API HTTP {response.status_code}")
    try:
        result = response.json()
    except ValueError:
        raise RuntimeError("API response is not JSON") from None
    if not isinstance(result, dict):
        raise RuntimeError("Unexpected API response")
    if type(result.get("code")) is not int or result["code"] != 0:
        raise RuntimeError("API business failure; check the docs and account")
    if "data" not in result:
        raise RuntimeError("Missing data; inspect the current docs")
    return {key: value for key, value in result.items() if key != "requestParams"}


def save_snapshot(folder, name, path, params):
    result = call_api(path, params)
    snapshot = {
        "capturedAtUTC": datetime.now(timezone.utc).isoformat(),
        "endpoint": path,
        "request": params,
        "response": result,
    }
    (folder / name).write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2), encoding="utf-8"
    )
    print(f"Saved {name}")


def main():
    if not TOKEN or TOKEN == "your_token" or not KEYWORD:
        raise RuntimeError("Set JUSTONEAPI_TOKEN and XIANYU_KEYWORD")
    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    folder = Path("xianyu-output") / run_id
    folder.mkdir(parents=True, exist_ok=False)
    save_snapshot(
        folder, "search-page-1.json", "/api/xianyu/search-item-list/v1",
        {"keyword": KEYWORD, "page": "1", "sort": "active"},
    )
    if ITEM_ID:
        save_snapshot(
            folder, "detail-known-id.json", "/api/xianyu/get-item-detail/v1",
            {"itemId": ITEM_ID},
        )


if __name__ == "__main__":
    try:
        main()
    except RuntimeError as error:
        raise SystemExit(str(error)) from None

每次运行在 xianyu-output 下新建一个时间目录。search-page-1.json 保存搜索条件、接口路径、UTC 采集时间和响应;设置了已知 ID 且详情请求成功后,才会生成 detail-known-id.json。

保存时略去顶层回显的 requestParams,不把请求 Token 写进自建的 request 元数据;data 保持原样。这不是已提取的商品表,也不是对响应内容的全面脱敏。分享文件前仍需检查实际内容。

怎样接入自己的商品监测

先查看账户内真实返回的字段,确认列表位置、商品 ID、价格含义与单位、时间以及商品状态。确认映射后,再把关键词发现的商品加入自己的跟踪清单,对已知 ID 分别保存后续详情快照。当前示例没有自动执行这一步。

比较两次结果时,保留相同商品标识、接口版本和采集时间,并区分搜索排序变化与商品本身变化。搜索页中暂时没出现某个商品,不足以认定已经下架;详情失败或字段缺失,也不应填成价格为零或“已售出”。仅当实际响应中有明确状态依据时,再作相应判断。

常见问题

可以直接拿到所有闲鱼商品或历史价格吗?

这两个接口分别提供关键词搜索和已知 ID 详情读取。一次搜索、一个排序或一个详情响应,都不能据此保证全站覆盖、全部商品或过去的价格记录。本例保存的是从本次执行开始的快照。

为什么搜索成功后没有自动请求商品详情?

搜索与详情使用不同参数,当前公开契约未固定搜索结果的 ID 字段。先核实字段映射;在此之前,本例只对你明确设置的 XIANYU_ITEM_ID 请求详情,不用猜测的 JSON 路径选取商品。

HTTP 200 就代表结果完整吗?

不代表。先检查业务 code,成功后再核对实际数据结构和覆盖范围。业务成功、非空结果和完整覆盖是不同检查项;空数据与响应结构未知也不能混为一谈。

打开闲鱼商品搜索文档,先在账户权限和预算内核对一个熟悉的关键词,再决定需要跟踪哪些商品。

继续使用 JustOneAPI

登录 Dashboard 获取 Token,查看完整 API 文档,或打开 MCP GitHub 项目了解最新配置。