Async client for mercari-shops.com (enterprise sellers on Mercari).
非官方 Mercari Shops(企业商户)GraphQL 异步客户端。
- Python 3.9+
- 基于
httpx异步请求 - 类型完备(PEP 561,内置
py.typed)
✅ 面向企业商家(mercari-shops.com)的异步 Python API。
✅ 提供 GraphQL
search()(可分页,全量)与店铺总页首屏抓取landing()(低延迟)两种能力。✅ 已在生产脚本中验证:支持按店铺 + 关键词抓取、分页、可选在库筛选、客户端价格排序。
✅ 需要时可传入站点 cookies(如
__cf_bm,_cfuvid)。
From source (editable):
#Local installation
pip install -U pip build
pip install -e .From PyPi:
#pip installation
pip install mercapi-shopsimport asyncio
from mercapi_shops import MercapiShops
SHOP_ID = "d2uUKgmbjTGT7BzBGUnXxe" # 示例:MANDARAKE
async def main():
async with MercapiShops() as api:
# 1) GraphQL 搜索(可分页、全量)
res = await api.search(
"アゾン",
shop_id=SHOP_ID,
in_stock=True, # 仅在库(本地过滤)
order_by="PRICE_ASC", # 价格升序(本地兜底排序)
# local_keyword="..." # 可选:二次本地过滤(NFKC+lower,空白分词 AND)
)
print("First page:", len(res.items))
for p in res.items[:5]:
print(p.id, p.name, p.price, p.inStock, p.assets[0].imageUrl if p.assets else None)
if res.pageInfo.hasNextPage:
res2 = await res.next_page()
print("Next page:", len(res2.items))
# 2) 店铺总页首屏(低延迟,更快发现“新上架”,但非全量)
latest = await api.landing(
shop_id=SHOP_ID,
in_stock=None, # True / False / None
keyword="アゾン", # 本地关键词过滤(NFKC+lower,空白分词 AND)
limit=120
)
print("Landing size:", len(latest))
for p in latest[:5]:
print(p.id, p.name, p.price, p.inStock, p.assets[0].imageUrl if p.assets else None)
asyncio.run(main())
GraphQL search()
支持分页(pageInfo.hasNextPage / await results.next_page())。
支持本地在库过滤 in_stock=True/False/None。
支持价格本地排序兜底:PRICE_ASC / PRICE_DESC(CREATED_AT 依赖后端,不做本地兜底)。
可选 local_keyword 二次本地过滤,不影响后端请求。
landing() 店铺总页首屏抓取
通常更快出现最新上架商品(低延迟)。
仅抓取店铺总页首屏,不分页,非全量。
支持 in_stock 本地过滤与 keyword 本地关键词过滤。
图片 URL 归一化
- 自动解析/展开 /_next/image?url=...、相对地址等,输出可直连的绝对 URL,方便下载与消息推送。
类型完备
- 内置 py.typed,对 ShopProduct / ShopProductAsset / ShopSearchResults / PageInfo 等提供静态类型。
v0.0.5
- 修复:环境依赖更新。
v0.0.4
- 修复:mercari-shops.com 2025-10-15 前端更新导致的搜索失败问题。
v0.0.2
- 新增:landing(shop_id, in_stock, keyword, limit),快速抓取店铺总页首屏;
- 新增:search(..., local_keyword=...) 二次本地过滤;
- 改进:图片 URL 归一化(解析 /_next/image?url=... 与相对链接 → 绝对直链);
- 改进:更健壮地解析 Next.js / Apollo 存储与 __ref,提升首屏解析成功率;
- 完善类型与文档。
MIT License
本项目为非官方客户端,仅用于技术研究与个人工具整合,请勿用于任何商业用途。
请遵守目标站点的服务条款与法律法规,自行承担使用风险。