闲鱼 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 替换为自己的值。
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 是否存在,失败时停止,已保存的成功响应保留。
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 项目了解最新配置。