SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-seerfar-ozon-category-search

linkfox-seerfar-ozon-category-search

Data & analytics

View repository

Updated 10-15 09:27

About this skill

Seerfar Ozon Category Search

This skill lists the products of a specific Ozon category from the Seerfar analytics database. Given a categoryId, it returns category-level aggregates (total sales, total revenue, average price, average rating, seasonality) plus each product's sales, price, rating, review count, brand and seller — the starting point for category selection analysis, best-seller mining within a category, and category capacity / price-band analysis.

Core Concepts

Unit of data is the product, scoped to one category: pass a single categoryId and receive that category's product list with performance metrics, alongside category-level aggregates. This is a category-level view, not a shop or keyword view.

Where the categoryId comes from: categoryId is the Ozon category identifier — a hierarchical path joined by _ (e.g. 15621032_15621049_115951147), obtained from the Ozon category document or from other Seerfar Ozon tools. If the user only has a category name, first resolve it to a categoryId from an upstream Seerfar Ozon source before calling this skill.

Category aggregates vs product rows: the response carries both category-level totals (totalSales, totalRevenue, avgPrice, rating, seasonalityAmplitude, seasonalityCoef, startDate/endDate) and a paginated product list (data / products). Use the aggregates for category sizing and the rows for individual product analysis.

Sales & price currency: sales / monthlySalesUnits are units; price / revenue are in Russian rubles (₽), indicated by currency.

Time window: by default the data covers the last 30 days (startDate / endDate show the actual range). Pass date as yyyy-MM (e.g. 2026-02) to query a historical month snapshot.

Parameters

Parameter Type Required Description
categoryId string yes Ozon category ID, e.g. 15621032_15621049_115951147 (levels joined by _).
page object yes Pagination {page, pageSize, orders[]}.
page.page integer no Page number, from 1 (default 1).
page.pageSize integer no Page size, default 20. Max 20 — larger values are rejected (errcode 1002).
page.orders array no Sort rules, elements {field, direction} (both required); direction DESC/ASC. Common fields: sales, price, revenue, reviewRating.
date string no Historical month yyyy-MM (e.g. 2026-02); omit for last 30 days.
fulfillment string no Fulfillment filter, one of FBO / FBS / RFBS / FBP / OZON; omit to query all. Single string, not an array.
uId string no User ID.
memberId string no Member ID (data attribution).

Only categoryId and page are required.

How to call

  • API endpoint：POST /seerfar/ozon/categorySearch(for full parameters/responses/error codes see references/api.md）
  • Python script：python scripts/seerfar_ozon_category_search.py '<JSON 参数>' [--inline]
  • Cost constraints: this tool consumes compute credits; within the same session, the same parameter combination is by default called only once, and the script has a 24h local cache. On failure/empty results, do not automatically switch keywords, paginate, or change the zip code to probe repeatedly; if further retrieval is needed, first explain to the user that it will incur additional consumption.

Output strategy (script default behavior)：

  • Alwayswrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-category-search-<timestamp>.json（<cwd> is the working directory when the script runs, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, aggregated automatically according to the user's task;writing to /tmp is prohibited, and if the current directory is not writable, report an error)
  • Response body ≤ 8 KB: after saving to disk, print the full JSON to stdout
  • Response body > 8 KB: after saving to disk, stdout outputs only a summary (top-level fields, common counts such as total/costToken, the length of the largest list field + the first 3 samples)
  • Add --inline to force full printing to stdout (also saved to disk)

Data reading suggestions: first look at the summary to judge whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.

Resolving authentication and compute credit issues

When the following abnormal situations occur, use references/onboarding.md to guide resolution:

Abnormal situations

  • API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute credits or balance: the message contains "insufficient compute credit balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

Usage Examples

1. Category best-sellers (sort by 30-day sales)

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. Category top-revenue products

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}}

3. Category premium price band (highest-priced)

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. Historical month snapshot

{"categoryId": "15621032_15621049_115951147", "date": "2026-02", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

5. Filter to FBO-fulfilled products only

{"categoryId": "15621032_15621049_115951147", "fulfillment": "FBO", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

6. Page deeper into the category

{"categoryId": "15621032_15621049_115951147", "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

How to Build Queries

  1. Always pass page.orders: categories can contain many products — sort by the metric you care about (sales DESC for best-sellers, revenue DESC for top revenue, price DESC for the premium band, reviewRating DESC for best-reviewed).
  2. Keep pageSize ≤ 20: the gateway caps page size at 20. Use page.page to paginate; check hasNextPage to know whether more pages exist.
  3. Resolve the categoryId first: if the user gives a category name rather than an id, obtain the categoryId from an upstream Seerfar Ozon source before calling this skill.
  4. Use category aggregates for sizing: totalSales, totalRevenue, avgPrice and rating describe the whole category at a glance — use them for capacity and price-band assessment before drilling into rows.
  5. Use date for historical comparison: pass date as yyyy-MM to compare a past month against the current 30-day window.
  6. fulfillment is a single string: pass one of FBO / FBS / RFBS / FBP / OZON, not an array.

Display Rules

  1. Present data only: show the category aggregates and product metrics in a clear table without subjective advice.
  2. Lead with category context, then product columns: state the category name (from categoryInfo.cnTitlePath / enTitlePath — confirms the right category), then totalSales, totalRevenue, avgPrice, rating, seasonality (seasonalityAmplitude / seasonalityCoef) and date range, plus the fulfillment distribution (sellerType map) as a one-line FBO/FBS/RFBS/... split; then a table of sku, title, price, sales, revenue, reviewRating, reviewCount, brandName, sellerName.
  3. Currency: price / revenue are in rubles (₽); render with the currency symbol.
  4. Fulfillment: fulfillment is an array (e.g. ["FBO"]); join multiple values with /.
  5. Unified vs original fields: productId/rating/brand/monthlySalesUnits/monthlySalesRevenue/productPageUrl mirror sku/reviewRating/brandName/sales/revenue/productUrl — show one set, prefer the originals.
  6. Pagination guidance: when hasNextPage is true, tell the user more pages are available via page.page; remind them pageSize is capped at 20.
  7. Empty category: a non-existent categoryId returns success with total=0 and no data — tell the user the id may be wrong rather than reporting a system error.
  8. Error handling: when code is not "200" (or errcode is not 200), explain the reason from msg / errmsg and suggest fixes (add page, lower pageSize, retry on rate-limit).

Important Limitations

  • categoryId and page are both required; omitting either returns errcode 400.
  • pageSize max 20: exceeding it returns errcode 1002.
  • No text/keyword filter within a category: this endpoint filters by category (plus optional fulfillment and date) only; to find products by keyword, use the Seerfar Ozon market keyword search skill.
  • total is the page row count, not the category's total product count — use hasNextPage to decide whether to fetch more pages.
  • sellerType is a fulfillment distribution, not seller type: despite the name, the top-level sellerType is a map of fulfillment model → product count ({FBO, RFBS, FBP, FBS, OZON}); it does not carry 本土/跨境 (local/cross-border) info. categoryInfo carries the category name path (CN/EN/RU) and crossBorderSellable.

User Expression & Scenario Quick Reference

Applicable — analyzing one Ozon category's products and aggregates:

User Says Scenario
"Analyze the products in this Ozon category" / "How big is this category" Category sizing (totalSales / totalRevenue / avgPrice)
"What are the best-selling products in this category" Best-seller mining (sort by sales)
"The products with the highest sales revenue in this category" Top-revenue products (sort by revenue)
"The price band/average order value of this category" Price-band analysis (sort by price)
"The highest-rated products in this category" Best-reviewed (sort by reviewRating)
"This category's data for last month" Historical month snapshot (date)
"FBO products in this category" Fulfillment filter

Not applicable — Needs beyond one category's product list:

  • One shop/seller's catalog → use the Seerfar Ozon shop search skill.
  • Market-level keyword discovery → use the Seerfar Ozon market keyword search skill.
  • Keyword mining → use the Seerfar Ozon keyword mining skill.
  • A single product's full detail → use a product-level Seerfar Ozon source (this skill returns category-level fields only).

Boundary judgment: if the user already has a categoryId (or one resolved from an upstream source) and wants to enumerate, rank, or size that category's products by sales/price/rating, start here. If they want a shop's catalog, keyword discovery, or a single product's deep detail, route to the corresponding Seerfar Ozon skill.

Compute credit consumption rules

Consumes 15 compute credits.

Users pay fees due to compute credit consumption. Please fully assess: when this skill needs to be called frequently, or the user has insufficient expectation of the compute credit consumption, be sure to remind the user and let the user decide whether to continue.

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. Anything you believe could be improved

Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, set LinkFox Skills.