Linkfox Seerfar Ozon Keyword Mining

Seerfar Ozon Keyword Mining

This skill mines Ozon marketplace keywords around a seed keyword in the Seerfar analytics database and filters the discovered terms by rich performance metrics — search volume, 30-day growth, product/seller/competitor counts, average price, relevancy, title density, cart-add conversion, and more. Each mined keyword carries a full market profile (market space, return/cancellation rate, top products, Chinese translation), making it the starting point for Ozon keyword expansion, long-tail discovery, and seed-term opportunity analysis.

Core Concepts

Seed-driven, not market-browse: unlike a market keyword search, this endpoint requires a keyword (the seed) and returns terms related to that seed, each enriched with market metrics. You expand outward from a term you already have in mind.

Relevancy is the mining signal: relevancy scores how closely a mined term relates to the seed (the seed term itself returns at relevancy: 100, related terms rank lower); titleDensity reflects how densely the term appears in product titles. Both are populated on every row — sort by relevancy DESC to keep expansions on-topic.

Platform coverage: each keyword record carries a platform field (0 = Ozon, 1 = Wildberries). The dataset is Ozon-centric; Wildberries rows appear where available. There is no input to restrict the platform — filter client-side if needed.

Match mode: matchType controls how the seed keyword (and includeKeywords) are matched — 0 exact, 1 fuzzy. Choose fuzzy to broaden the expansion, exact to stay tight.

No date or category selectors: this endpoint does not accept searchDate or categories. If you need month-over-month or category-scoped browsing, use the market keyword search skill instead.

Parameters

All range filters are {min, max} objects; supply either or both bounds. keyword and page are both required.

调用方式

• API 端点：POST /seerfar/ozon/keywordMining（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/seerfar_ozon_keyword_mining.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-keyword-mining-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

Usage Examples

1. Expand around a seed term (sort by search volume)

{"keyword": "платье", "page": {"page": 1, "pageSize": 10, "orders": [{"field": "searchVolume", "direction": "DESC"}]}}

2. Blue-ocean expansions — high volume, few sellers

{"keyword": "телефон", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "searchVolume", "direction": "DESC"}]}, "searchVolume": {"min": 10000}, "sellers": {"max": 50}}

3. Keep expansions on-topic with relevancy + title density

{"keyword": "наушники", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "relevancy", "direction": "DESC"}]}, "relevancy": {"min": 50}}

4. Narrow with include / exclude lists

{"keyword": "часы", "page": {"page": 1, "pageSize": 20}, "includeKeywords": ["женские"], "excludeKeywords": ["ремень"], "matchType": 1}

How to Build Queries

1. Always lead with the seed keyword: it is required and defines the expansion center. Pass it in Russian for Ozon.
2. Lead with page.orders: sort by the metric you care about (searchVolume DESC for popularity, relevancy DESC for on-topic, sellers ASC for low competition).
3. Stack range filters to find opportunities: combine a high searchVolume floor with a low sellers ceiling to surface blue-ocean expansions; add relevancy / titleDensity bounds to keep them relevant to the seed.
4. Use includeKeywords / excludeKeywords to steer the expansion: force in must-have modifiers and strip noise without running a second query.