Linkfox Seerfar Ozon Keyword Back Search

Seerfar Ozon Keyword Back-Search

This skill reverse-looks-up Ozon search keywords by a list of product SKU IDs in the Seerfar analytics database: pass up to 20 SKUs (your own listing or a competitor's) and it returns the search terms those products appear under — organic and/or ad — each enriched with a full market profile (search volume, 30-day growth, product/seller/competitor counts, average price, conversion concentration, top products, plus per-term organic/ad channel, natural rank, exposure, and conversion in the dimension object). It is the starting point for Ozon keyword reverse lookup, listing-title optimization, and competitor traffic-word discovery.

Core Concepts

SKU-driven, not keyword-driven: unlike keyword mining (expand from a seed term) or market keyword search (browse the whole market), this endpoint takes skuIds and returns the search terms those specific products rank for. The direction is product → keywords (reverse).

hasVariant is required: every request must declare whether to exclude variants — 0 keep variants, 1 exclude variants. Pick 1 when you want de-duplicated keyword coverage for a parent listing.

Natural vs ad terms: type filters the search-term channel — ["0"] organic (自然搜索词) only, ["1"] ad (广告搜索词) only; omit to get both. Combine with the naturalRank / adRank range filters to qualify positioning.

Back-search metrics live in dimension: each returned term carries a dimension object with the reverse-lookup-specific metrics — type (0 organic / 1 ad), naturalRank (the SKU's natural rank for that term), exposure (exposure share, 0–1), conversion (conversion rate, 0–1), and x (opaque position indicator). The input filters type / naturalRank / adRank / exposure / conversion filter on these same per-term values. Note: relevancy is defined in the schema but is not returned by this endpoint.

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 includeKeywords / excludeKeywords are matched — 0 exact, 1 fuzzy.

Parameters

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

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-keyword-back-search-<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. Reverse-lookup a single SKU's traffic keywords (sort by search volume)

{"skuIds": [4380710124], "hasVariant": 0, "page": {"page": 1, "pageSize": 10, "orders": [{"field": "searchVolume", "direction": "DESC"}]}}

2. Organic terms where the SKU ranks near the top

{"skuIds": [4380710124], "hasVariant": 1, "type": ["0"], "naturalRank": {"max": 10}, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "searchVolume", "direction": "DESC"}]}}

3. Ad search words only, with an ad-rank floor

{"skuIds": [4380710124], "hasVariant": 0, "type": ["1"], "adRank": {"max": 50}, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "searchVolume", "direction": "DESC"}]}}

4. Narrow with include / exclude lists

{"skuIds": [4380710124], "hasVariant": 0, "page": {"page": 1, "pageSize": 20}, "includeKeywords": ["платье"], "excludeKeywords": ["ремень"], "matchType": 1}

How to Build Queries

1. Always lead with skuIds + hasVariant: both are required and define the reverse-lookup target. Use real Ozon SKU IDs (the same IDs returned by Seerfar Ozon product / shop / category skills).
2. Lead with page.orders: sort by the metric you care about (searchVolume DESC for traffic weight, sellers ASC for low competition, count30GrowthRate DESC for rising terms).
3. Split organic vs ad with type: pass ["0"] or ["1"] to focus a listing-optimization pass (organic) or an ads pass (ad), then bound naturalRank / adRank to qualify positioning — these filter on the values surfaced in each row's dimension.
4. Use includeKeywords / excludeKeywords to steer: force in must-have modifiers and strip noise without running a second query.