Nexscope Ozon Shop Search
This skill lists the products of a specific Ozon shop (seller) from the Nexscope analytics database. Given a shop id, it returns each product's 30-day sales, price, rating, weight, fulfillment model (FBO/FBS), seller type (local / cross-border) and return/cancellation rate, plus the shop's total 30-day sales — the starting point for competitor-shop product analysis, best-seller mining, and seller catalog teardown.
Core Concepts
Unit of data is the product, scoped to one shop: pass a single shop id and receive that shop's product catalog with performance metrics. This is a shop-level view, not a keyword or category view.
Where the shop id comes from: id is the Nexscope seller/shop identifier — the same sellerId returned by other Nexscope Ozon tools (e.g. product report / product detail search). Negative ids (e.g. -2 Ozon Express, -4 Ozon Fresh) are Ozon's own platform sellers; positive ids are third-party sellers. If the user only has a shop name or product, first obtain the sellerId from a product-level Nexscope Ozon source, then call this skill.
Seller type: each product carries sellerType — 0 local (local), 1 cross-border (cross-border). A shop is typically all one type; use it to judge whether a competitor is a domestic or cross-border seller.
Sales & price currency: sales / monthlySalesUnits are 30-day units; price is in Russian rubles (₽), indicated by currency.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | yes | Shop (seller) ID — the sellerId from other Nexscope Ozon tools. Negative = Ozon platform seller. |
| 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 (a platform validation error). |
| page.orders | array | no | Sort rules, elements {field, direction}; direction DESC/ASC. Common fields: sales, price, reviewRating, upTime. |
| uId | string | no | User ID. |
| memberId | string | no | Member ID (data attribution). |
Only id and page are required.
Calling the Tool
- API Endpoint:
/seerfar/ozon/shopSearch(full parameters/responses/error codes inreferences/api.md) - Python Script:
python scripts/ozon_shop_search.py '<JSON params>' [--inline] - Cost constraint: This tool consumes credits. Within the same session and same parameter combination, it defaults to a single call with a 24-hour local cache. Do not automatically retry with different keywords, pagination, or parameters on failure/empty results. Inform the user of additional credit consumption before continuing retrieval.
Output strategy (script default behavior):
- Always write the full response to
<cwd>/nexscope/<YYYY-MM-DD>/<session>/data/ecommerce.ozon-shop-search-<timestamp>.json(<cwd>is the working directory when the script executes, which in Claude Code is the current project directory;<session>is taken from theSESSION_IDenvironment variable, automatically grouped by user task; do not write to /tmp; error if the current directory is not writable) - Response body <= 8 KB: write to disk then print full JSON to stdout
- Response body > 8 KB: write to disk then print only a summary to stdout (top-level fields, common counts like
total/costToken, length of the largest list field + first 3 samples) - Add
--inlineto force full output to stdout (still writes to disk)
Reading data: Check the summary first to determine if it is sufficient. When specific fields are needed, use jq or ConvertFrom-Json to extract from the saved JSON file as needed, avoiding loading the entire JSON into context.
Response handling
For the research HTTP response, require a numeric outer code equal to 0 before using data. Nonzero codes are platform failures; display outer msg without interpreting its wording as a retry instruction. Nexscope preserves upstream messages and translates Chinese to English; successful responses may have msg: null. HTTP 200 alone and nested business code / status do not replace the platform check. See references/api.md for response paths and task-specific states.
Authentication & Credits
If you encounter authentication or credit issues:
Error conditions
- API Key not configured: The
NEXSCOPE_API_KEYenvironment variable is not set. - HTTP 401 or 402 status code
- Insufficient credits/balance: Response message indicates credit balance exhausted, quota exceeded, subscription expired, or recharge required.
Resolution steps
- Set the
NEXSCOPE_API_KEYenvironment variable with a valid API key. - If credits are insufficient, visit https://www.nexscope.ai/pricing?co-from=skillNS to top up your balance.
- For onboarding and setup guidance, refer to https://www.nexscope.ai/help/skills-external-access?co-from=skillNS
Usage Examples
1. A shop's best-sellers (sort by 30-day sales)
{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}
2. A shop's newest listings (sort by upload time)
{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "upTime", "direction": "DESC"}]}}
3. A shop's highest-priced products
{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}
4. Page deeper into a shop's catalog
{"id": 1362816, "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}
How to Build Queries
- Always pass
page.orders: the catalog can be large — sort by the metric you care about (salesDESC for best-sellers,upTimeDESC for new arrivals,priceDESC for premium SKUs). - Keep
pageSize≤ 20: the gateway caps page size at 20. Usepage.pageto paginate; checkhasNextPageto know whether more pages exist. - Resolve the shop
idfirst: if the user gives a shop/product name rather than an id, obtain thesellerIdfrom a product-level Nexscope Ozon source before calling this skill. - Use
totalSalesfor shop-level context: the response'stotalSalesis the shop's total 30-day sales — a quick health indicator for the whole shop, independent of the current page.
Display Rules
- Present data only: show the shop's product metrics in a clear table without subjective advice.
- Lead with shop context, then product columns: state
totalSales(shop 30-day total) first, then a table ofsku,price,sales,reviewRating,weight,sellerType,fulfillment,returnCancellationRate. - Seller type label: render
sellerTypeas local/cross-border (0/1) so the user reads it at a glance. - Fulfillment:
fulfillmentis an array (e.g.["FBO"]); join multiple values with/. - Missing
returnCancellationRate: for Ozon platform sellers (negativeid) this field is often absent — show-rather than failing. - Pagination guidance: when
hasNextPageis true, tell the user more pages are available viapage.page; remind thempageSizeis capped at 20. - Empty shop: a non-existent
idreturns success withtotal=0and no data — tell the user the id may be wrong rather than reporting a system error. - Error handling: when the numeric outer platform
codeis nonzero, explain the reason from outermsgand suggest fixes (addpage, lowerpageSize, retry on rate-limit).
Important Limitations
idandpageare both required; omitting either returns a nonzero platform code.pageSizemax 20: exceeding it returns a nonzero platform code.totalis the page row count, not the shop's full catalog size — usehasNextPageto decide whether to fetch more pages.- No text/keyword filter: this endpoint filters by shop only; to find a shop by name, use another Nexscope Ozon source first.
- Field variance by seller type:
returnCancellationRateis populated for third-party sellers but frequently absent for Ozon platform sellers (negativeid). Schema-definedproductPageUrl,monthlySalesRevenue,brandare not returned (upstream has no source, omitted rather than null).
User Expression & Scenario Quick Reference
Applicable — analyzing one Ozon shop/seller's catalog:
| User Says | Scenario |
|---|---|
| "Analyze this Ozon shop's products" / "What is this seller selling" | Shop product catalog |
| "What are the best-selling products in this shop" | Best-seller mining (sort by sales) |
| "What new products has this shop listed recently" | New arrivals (sort by upTime) |
| "Price band / average order value for this competitor shop" | Price-band analysis (sort by price) |
| "Is this shop a local or cross-border seller" | Seller type check (sellerType) |
| "Total sales for this shop" | Shop health (totalSales) |
Not applicable — Needs beyond one shop's catalog:
- Discovering Ozon keywords by market metrics → use the Nexscope Ozon market keyword search skill.
- A single product's full detail → use a product-level Nexscope Ozon source (this skill returns catalog-level fields only).
- Browsing the category tree → use a category-level Nexscope Ozon source.
- Finding which shop sells a given product → use a product-level Nexscope Ozon source to get the
sellerIdfirst.
Boundary judgment: if the user already has a shop/seller ID (or a sellerId obtained from a product lookup) and wants to enumerate or rank that shop's products by sales/price/rating, start here. If they want market-level keyword discovery or a single product's deep detail, route to the corresponding Nexscope Ozon skill.
API Key request rate
All Nexscope API Keys belonging to the same user share one request-rate allowance for public API execution. The allowance is measured over any rolling 1-second window. Your RPS depends on your account entitlements; do not assume every user has a fixed 1 RPS. A single Skill operation may make multiple public API requests, and each request uses this allowance.
If an execution request returns HTTP 429 with outer code 13012, the request-rate allowance was exceeded. Honor the returned Retry-After before considering another request. Outer code 13013 means the concurrent-request limit was exceeded, not the rate limit; honor its Retry-After when supplied. Inspect the response and reconcile state before retrying. Never automatically replay a write operation or a request whose outcome is unclear.
