Metadata-Version: 2.4
Name: goofish-xianyu-api
Version: 1.0.1
Summary: Unofficial cookie-free Python SDK & CLI for Goofish (Xianyu / 闲鱼): secondhand & luxury deal search, listing details, seller inventory, buyer reviews, CNY resale discount math, and Zhima Credit trust scoring.
Author-email: UnitBytes <contact@unitbytes.com>
License: MIT
Project-URL: Homepage, https://unitbytes.com/actors/goofish-xianyu-seller-scraper/
Project-URL: Documentation, https://unitbytes.com/actors/goofish-xianyu-seller-scraper/
Project-URL: Apify Store, https://apify.com/unitbytes/goofish-scraper?fpr=939u3w&fp_sid=pypi_sdk
Keywords: goofish,xianyu,idlefish,secondhand,recommerce,resale,luxury-authentication,zhima-credit,scraper,apify
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: apify
Requires-Dist: apify-client>=1.7.0; extra == "apify"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# goofish-xianyu-api — Unofficial Goofish (Xianyu / 闲鱼) Search, Seller Inventory & Reviews Python SDK

![UnitBytes Goofish Xianyu Seller Inventory & Reviews Scraper](https://unitbytes.com/assets/banners/unitbytes-goofish-xianyu-seller-inventory-reviews-scraper-banner.jpg)

[![PyPI](https://img.shields.io/pypi/v/goofish-xianyu-api.svg)](https://pypi.org/project/goofish-xianyu-api/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

> **Disclaimer:** Unofficial third-party API client & integration powered by UnitBytes; not affiliated with, sponsored by, or endorsed by Alibaba Group, 1688.com, or Goofish/Xianyu.

**`goofish-xianyu-api`** is an **unofficial** typed Python SDK and CLI (`goofish-xianyu` / `goofish-scrape`) for **Goofish / Xianyu (`闲鱼`)** secondhand & luxury resale intelligence — including keyword search, `m.tb.cn` mobile share-link resolution, listing details, seller storefront inventory (`onsale` & `sold`), buyer reviews, CNY-to-USD markdown math, and **Zhima Credit (`芝麻信用`)** seller trust scoring — with **zero Taobao/Alipay cookies required**.

---

## Why Use `goofish-xianyu-api`?

- **Zero Login / Zero Cookie Churn / Zero Mandatory Dependencies** — Pure Python stdlib HTTP client (`0` required third-party packages); no +86 SMS verification, Alipay QR login, or local proxy rotation to maintain.
- **Multi-Provider Cloud Routing (`apify` • `unitbytes` • `rapidapi`)** — Auto-detects `APIFY_TOKEN` (warm Apify Standby HTTP + batch fallback), `UNITBYTES_API_KEY` (`https://api.unitbytes.com/v1/goofish/*`), or `RAPIDAPI_KEY` (`https://goofish-xianyu-marketplace-and-seller-api.p.rapidapi.com/v1/goofish/*`) with zero code changes.
- **Multi-Keyword Watchlist Sniper (`search_many` + `only_new`)** — Deduplicate across multiple keywords by canonical `itemId` and persist seen listings in an atomic local JSON state file so cron jobs alert only on newly listed deals.
- **Offline English → Xianyu Slang Glossary (`0` LLM Calls)** — Translate English product terms, ACG *guzi* merch (`badge` → `吧唧`, `plush` → `棉花娃娃`, `acrylic stand` → `立牌`), and Xianyu condition shorthand (`box and papers` → `箱说全`, `unopened` → `全新未拆封`) offline while preserving model numbers (`"Sony A7M4 mirrorless camera"` → `"索尼 A7M4 微单相机"`).
- **Cross-Border Proxy-Agent Links Built In** — Generate ready-to-open **Superbuy, AllChinaBuy, Sugargoo, CSSBuy, and Basetao** order URLs (`build_proxy_agent_links`) alongside CNY-to-USD markdown math (`analyze_resale_pricing`) and 0–100 **Zhima Credit (`芝麻信用`)** seller trust scoring (`assess_seller_trust`).

---

## Quickstart

### 1. Install

```bash
pip install goofish-xianyu-api
```

### 2. Configure Your Free Starter API Token

Create a free Apify account (**\$5/month recurring platform credit included — no credit card required**) and copy your `APIFY_TOKEN`:

- **[Get a Free Apify API Token (\$5/mo credit included)](https://apify.com/unitbytes/goofish-scraper?fpr=939u3w&fp_sid=pypi_sdk)**

```bash
export APIFY_TOKEN="apify_api_YOUR_TOKEN"
# Or use UnitBytes Direct Cloud API / RapidAPI with zero code changes:
# export UNITBYTES_API_KEY="ub_live_YOUR_KEY"
# export RAPIDAPI_KEY="YOUR_RAPIDAPI_KEY"
```

### 3. Zero-Login Live Keyword Search, Watchlist Deal Sniper & Seller Zhima Audit

```python
from goofish_xianyu_api import (
    GoofishClient,
    analyze_resale_pricing,
    assess_seller_trust,
    build_proxy_agent_links,
    translate_keyword,
)

client = GoofishClient()  # Reads APIFY_TOKEN automatically

# 1) Offline English -> Simplified Chinese Xianyu slang translation (0 network calls)
print(translate_keyword("Sony A7M4 mirrorless camera box and papers"))
# -> "索尼 A7M4 微单相机 箱说全"
print(translate_keyword("Genshin Impact badge unopened"))
# -> "原神 吧唧 全新未拆封"

# 2) Multi-keyword watchlist sniper with cross-keyword itemId dedup & persistent state
new_deals = client.search_many(
    ["Sony A7C2 mirrorless", "Fujifilm X100VI box and papers", "Nintendo Switch OLED"],
    max_items=45,                  # Auto-paginates warm Standby pages (>30 items)
    translate_keywords=True,       # Translates English terms into Chinese Xianyu slang
    personal_only=True,            # Filter out commercial storefronts (个人闲置)
    free_shipping=True,
    price_min=1000,
    price_max=13500,
    sort_by="newest",
    only_new=True,                 # Emit only unseen itemIds across cron runs
    state_file="watchlist_state.json",
)

for item in new_deals[:5]:
    pricing = analyze_resale_pricing(item, cny_to_usd=0.138)
    agents = build_proxy_agent_links(item)
    print(
        f"[{item.get('matchedKeyword')}] {item['title']} -> "
        f"¥{pricing.price_cny} (${pricing.price_usd}, -{pricing.discount_pct}%)"
    )
    print(f"  Superbuy:    {agents.superbuy}")
    print(f"  AllChinaBuy: {agents.allchinabuy}")

# 3) Resolve a raw Xianyu mobile share snippet or numeric item ID
detail = client.get_item_detail("【闲鱼】https://m.tb.cn/h.5xyz123 点击链接直接打开")

# 4) Audit seller Zhima Credit, KYC verification badges & negative buyer feedback
profile = client.get_seller_profile("2214891234567")
trust = assess_seller_trust(profile)
print(f"Trust Score: {trust.trust_score}/100 | Zhima: {trust.zhima_tier} | Risk: {trust.risk_level}")

sold_comps = client.get_seller_items("2214891234567", status="sold", max_items=20)
neg_reviews = client.get_seller_reviews("2214891234567", review_filter="negative_only", max_reviews=20)
```

---

## Command-Line Interface (`goofish-xianyu` / `goofish-scrape`)

Export Goofish resale listings (enriched automatically with `resaleSummary` and `proxyAgentLinks`), seller profiles, and reviews to `json`, `jsonl`, or `csv`:

```bash
# Multi-keyword English -> Chinese watchlist sniper (persists unseen IDs in seen_deals.json)
goofish-xianyu --format jsonl search \
  --keywords "Sony A7C2 mirrorless" "Pokemon card unopened" \
  --translate \
  --personal-only \
  --max-items 40 \
  --only-new seen_deals.json

# Search personal sellers and export USD markdowns + Superbuy/AllChinaBuy columns to CSV
goofish-xianyu --format csv --output deals.csv search "爱马仕 picotin" --personal-only --max-items 20

# Inspect a single listing (supports raw m.tb.cn share links)
goofish-xianyu --format json item "https://www.goofish.com/item?id=837465918273"

# Audit a seller's Zhima Credit + trust score
goofish-xianyu --format json seller 2214891234567 --include-items --include-reviews

# Export a seller's historical sold comps as JSONL
goofish-scrape --format jsonl seller-items 2214891234567 --status sold --max-items 20
```

---

## Direct Apify Actor JSON Input Compatibility

When triggering [`unitbytes/goofish-xianyu-search-scraper`](https://apify.com/unitbytes/goofish-xianyu-search-scraper?fpr=939u3w&fp_sid=pypi_sdk) directly via REST, n8n, or `prefer_standby=False`, pass multi-keyword queries as a comma-separated string in `keyword` (`"keyword": "索尼 A7C2, 富士 X100VI, Switch OLED"`). `GoofishClient.search_many(..., prefer_standby=False)` formats this automatically.

---

## Upstream Actors & Pricing

| Capability | Apify Actor Slug | Landing Page | Pay-Per-Event Pricing |
| :--- | :--- | :--- | :--- |
| Keyword Search & Listing Detail | [`unitbytes/goofish-xianyu-search-scraper`](https://apify.com/unitbytes/goofish-xianyu-search-scraper?fpr=939u3w&fp_sid=pypi_sdk) | [unitbytes.com/actors/goofish-xianyu-search-scraper](https://unitbytes.com/actors/goofish-xianyu-search-scraper/) | \$0.002 search / \$0.003 detail |
| Seller Profile, Inventory (`onsale`/`sold`) & Reviews | [`unitbytes/goofish-scraper`](https://apify.com/unitbytes/goofish-scraper?fpr=939u3w&fp_sid=pypi_sdk) | [unitbytes.com/actors/goofish-xianyu-seller-scraper](https://unitbytes.com/actors/goofish-xianyu-seller-scraper/) | \$0.004 profile / \$0.0035 item / \$0.001 review |

---

## Realistic Scope & Upstream Boundaries

- **Works Reliably Without Login:** Public Goofish keyword search, CNY price & personal-seller filters, `m.tb.cn` share-link resolution, full item descriptions & HD galleries, seller Zhima Credit tier (`极好`/`优秀`/`良好`), KYC verification badges (`实人认证`/`实名认证`), active & sold storefront inventory, and buyer feedback ratings.
- **Upstream Platform Boundaries:** Private buyer-seller chat messages, direct Alipay phone/account identifiers, and order checkout actions require an authenticated personal Goofish mobile app session and are outside the scope of public guest data extraction.

---

## Legal & Compliance

- Extracts **publicly available marketplace listing & seller reputation metadata** only.
- Independent integration powered by UnitBytes; not affiliated with or endorsed by Alibaba Group, 1688.com, or Goofish/Xianyu.
- Licensed under the [MIT License](./LICENSE).
