Xianyu (GooFish) API: Keyword Search and Product Details
Use JustOneAPI to search Xianyu resale listings and request details for a known item ID. Save JSON snapshots with a two-request limit and verify fields before building a monitor.
Discover listings by keyword, then inspect a known item
A Xianyu resale monitor usually needs two capabilities: finding listings that match a keyword and checking items already selected for tracking. JustOneAPI provides Xianyu (GooFish) Product Search V1 and Product Details V1 for these separate steps.
Search accepts keyword, page, and sort; details accepts a known itemId. This tutorial saves one search-page response and optionally requests details for one known item, with a maximum of two API requests per run. It does not automatically extract IDs, promise every active listing, or provide an existing price history.
Prepare access and a keyword
Get an API Token from the JustOneAPI dashboard and check permissions, pricing, and available trial requests for each endpoint. Access to one endpoint does not establish access to the other. Account settings determine the actual terms and availability.
Both endpoints use GET at https://api.justoneapi.com, with token in the query parameters. Keep the Token in a local environment variable rather than articles, screenshots, shared command records, or source control.
Step 1: Request a keyword search page
Xianyu Product Search V1 uses /api/xianyu/search-item-list/v1. Required parameters are token and keyword. The optional page starts at 1; this example explicitly sends "1".
The default sort is active. The current documentation lists these options:
active: active listings first.recent: recent nearby or position-based results first.credit: sellers with higher credit first.price_ascandprice_desc: price ascending and descending.price_drop: reduced-price listings first.newest: newly published listings first.
Try newest when discovering newly listed items. The documented meanings of recent and newest differ, so they should not be treated as interchangeable. The example starts with active to inspect the default ordering.
A search response represents the requested keyword, page, and sort at that time. Listings may change between requests. Two requested pages do not automatically form a complete, duplicate-free inventory. Before extending pagination, verify the list location, stable item identifier, and a supported stopping condition, then set a page and request budget.
Step 2: Request details with a known itemId
Xianyu Product Details V1 uses /api/xianyu/get-item-detail/v1. Its required parameters are token and itemId. It reads public details for a known listing; a keyword is not a substitute for the item ID.
Confirm the ID from a listing link you have checked or from the actual search response. Do not pass a full URL, seller ID, or keyword as itemId. The public OpenAPI currently leaves the internal data structure unspecified for both endpoints. The example therefore assumes neither a data.items list nor particular ID, price, or listing-status field names.
When you set XIANYU_ITEM_ID below, the details request independently uses that known ID. The code does not verify that it appears in the current search results. Leave the variable unset to run only the search.
Example: Save a search page and an optional item snapshot
Install the dependency and set your Token and keyword. These commands are for macOS or Linux; replace the Token placeholder with your own value.
python3 -m pip install requests
export JUSTONEAPI_TOKEN='your_token'
export XIANYU_KEYWORD='二手相机'
# Optional: set only after confirming the item ID; omit for search only.
# export XIANYU_ITEM_ID='your_known_item_id'Save the code as xianyu_sample.py and run python3 xianyu_sample.py. It requests the first search page, followed by at most one known-item lookup. It does not retry automatically or follow redirects. An HTTP 200 response must also have business code=0 and a data field. The script stops on failure and preserves snapshots already saved.
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 NoneEach run creates a timestamped directory under xianyu-output. search-page-1.json records the search conditions, endpoint, UTC capture time, and response. detail-known-id.json is created only when a known ID is configured and that request succeeds.
The exporter omits the top-level echoed requestParams and excludes the Token from its own request metadata. It preserves data without mapping it. These files are not normalized product tables, and the exporter does not fully redact response contents. Inspect actual contents before sharing files.
Build a monitor after verifying the response fields
Inspect a real response within your account permissions to confirm the list location, item ID, price meaning and units, timestamps, and listing status. Once that mapping is established, add selected search results to your own watchlist and save subsequent details snapshots by known ID. The example does not automate this step.
Keep the item identifier, endpoint version, and capture time when comparing snapshots. Separate changes in search ordering from changes to a listing. A missing search result alone does not establish that an item was removed. A failed details request or missing field should not become a zero price or a “sold” status. Make those decisions only when the actual response provides a clear basis.
Frequently asked questions
Does this return every Xianyu listing or historical prices?
The two endpoints provide keyword search and known-ID details. One search, one sort order, or one details response does not establish complete marketplace coverage or past price records. This example starts saving snapshots when you run it.
Why does the code not automatically fetch details for search results?
Search and details use different inputs, and the public contract does not fix the item-ID field inside search results. Verify that mapping first. Until then, the example requests details only for the XIANYU_ITEM_ID you explicitly provide.
Does HTTP 200 mean the results are complete?
No. Check the business code, then inspect the actual structure and coverage. Business success, non-empty data, and complete coverage require separate checks. An empty result and an unknown response shape are also different conditions.
Open the Xianyu Product Search documentation, inspect a familiar keyword within your account permissions and budget, and then choose which listings to track.
Continue with JustOneAPI
Log in to the Dashboard for your token, read the full API docs, or open the MCP GitHub project for the latest configuration.