Skip to content

nexscope-ai/nexscope-ecommerce-skills / ecommerce-ozon-keyword-back-search

ecommerce-ozon-keyword-back-search

Verified

FileKindSize
SKILL.mdskill md14.3 KB
manifest.jsonconfig319 B
references/api.mdmarkdown14.4 KB
scripts/ozon_keyword_back_search.pyscript6.6 KB

references/api.md

View on GitHub
# Nexscope Ozon Keyword Back-Search API Reference

## API Specification

- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/seerfar/ozon/keywordBackSearch`
- **HTTP Method**: POST, Content-Type: application/json
- **Authentication**: Header `Authorization: <api_key>`, api_key is read from the environment variable `NEXSCOPE_API_KEY` (if not configured, follow the **## Resolving Authentication and Credit Issues** section in SKILL.md)
- **User-Agent**: `Nexscope-Skill/1.0`; HTTP timeout 60s

## Request Parameters

POST Body (JSON). The following fields are consistent with the interface `inputSchema`. `skuIds`, `hasVariant`, and `page` are required; all others are optional. All range filter items are `{min, max}` objects and can be passed with one or both bounds.

| Parameter | Type | Required | Description |
|------|------|------|------|
| skuIds | array<integer> | Yes | List of SKUs to back-search, max 20 |
| hasVariant | integer | Yes | Whether to exclude variants: `0` do not exclude variants, `1` exclude variants |
| page | object | Yes | Pagination & sorting: `{page, pageSize, orders[]}` |
| page.page | integer | No | Page number, starting from 1, default 1 |
| page.pageSize | integer | No | Items per page, default 20 |
| page.orders | array | No | Sort rules, elements `{field, direction}`; `direction` takes `DESC` (descending) / `ASC` (ascending) |
| matchType | integer | No | Keyword match mode: `0` exact, `1` fuzzy |
| type | array<string> | No | Search term type filter, fixed options: `0` organic search terms, `1` ad search terms; no filtering if omitted |
| historyDate | string | No | Historical month `yyyy-MM` (e.g., `2026-02`); omit to query the current period |
| includeKeywords | array<string> | No | Include keyword array (max 1000), only returns search terms containing the specified words |
| excludeKeywords | array<string> | No | Exclude keyword array (max 1000), removes irrelevant terms |
| searchVolume | {min,max} | No | Monthly search volume range |
| searchChange30 | {min,max} | No | 30-day search change range |
| wordCount | {min,max} | No | Keyword word count range |
| productViews | {min,max} | No | Product views range |
| products | {min,max} | No | Product count range |
| sellers | {min,max} | No | Seller count range |
| marketSpace | {min,max} | No | Market space range |
| conversionSharing | {min,max} | No | Conversion concentration range |
| uniqQueriesWCa | {min,max} | No | Add-to-cart count range |
| ca | {min,max} | No | Add-to-cart conversion rate range |
| conversion | {min,max} | No | Conversion rate range |
| titleDensity | {min,max} | No | Title density range |
| adRivalCount | {min,max} | No | Ad competitor count range |
| adRank | {min,max} | No | Ad ranking range |
| naturalRank | {min,max} | No | Organic ranking range |
| exposure | {min,max} | No | Exposure range |
| uId | string | No | User ID |
| memberId | string | No | Member ID (a unique member identifier; data is attributed to memberId) |

> **Required constraints**: `skuIds`, `hasVariant`, and `page` are all required; missing any will cause the request to be rejected. `skuIds` supports at most 20 entries; behavior beyond that limit is not documented.
> **Range filtering**: Both sub-fields of all `{min,max}` objects are optional; passing a single bound filters by lower/upper bound only.
> **Organic / Ad terms**: `type` is used to view only organic search terms (`["0"]`) or ad search terms (`["1"]`); both types are returned if omitted.
> **Difference from market keyword search / keyword mining**: This endpoint is a "keyword back-search by SKU" — `skuIds` must be passed; the results show the search terms these products appear under and their market profile. It does not support month selection via `searchDate` (only `historyDate` historical month), does not support `categories` category filtering, and does not accept `keyword` seed terms or mining/market-only filters like `price`.
> **Sorting**: Recommended to sort by core metrics via `page.orders` (e.g., `searchVolume` DESC, `sellers` ASC) to avoid paging through large unsorted result sets.

## Nexscope response envelope

These research endpoints return a platform object with numeric `code`, nullable `msg`, and business `data`. Only outer `code: 0` means success; `200`, string codes, missing codes, and HTTP 200 alone do not. A nonzero code is a platform error: show `msg` and do not interpret the payload as a successful result.

`msg` preserves the upstream message when available; Chinese messages are translated to English by Nexscope. A successful response without a message has `msg: null`. Do not infer success or retry behavior from the message text. On both success and failure, the direct fields `code`, `errcode`, `errorCode`, `msg`, `errmsg`, `message`, and `errorMsg` are removed from public `data`. Read the message only from outer `msg`; deeper business fields are preserved, including nested `code` and `status`.

Business field tables and abbreviated business examples below describe `data`, unless explicitly labeled as a complete platform response. For example, a business `products` field is at HTTP `data.products`, and a business `data` array is at HTTP `data.data`. The research endpoints already had this outer envelope; no additional wrapper is added.

```json
{"code":0,"msg":null,"data":{}}
```

Metadata includes string `ts` (epoch milliseconds), string `cost` (elapsed milliseconds, not credits), `time`, and nullable `traceId`. Handle network/HTTP failures before the platform code; gateway failures may not be platform JSON. Keep the existing billing-header guidance separate from elapsed time.

## Response Structure

| Field | Type | Description |
|------|------|------|
| total | integer | Total record count |
| data | array | Keyword back-search data (see details below) |
| columns | array | Column definitions, elements contain `{field, title, cellType, sortable, filterable}` |
| costTime | integer | API latency (milliseconds) |
| costToken | integer | Tokens consumed |
| type | string | Response display type, e.g., `tableListWorkbenches` |

### data[*] Keyword Back-Search Object Fields

| Field | Type | Description |
|------|------|------|
| query | string | Keyword (original Russian) |
| queryCn | string | Keyword Chinese translation |
| platform | integer | Platform: `0` Ozon, `1` Wildberries |
| searchVolume | integer | Monthly search volume |
| count30GrowthRate | number | Monthly search growth (%, can be negative) |
| productCount | integer | Product count (may be missing in some rows) |
| competingProducts | integer | Competing product count |
| sellers | integer | Seller count |
| avgPrice | number | Average price |
| itemsViews | number | Product visibility |
| viewSharing | number | View concentration (%) |
| conversionSharing | number | Conversion concentration (%) |
| marketSpace | number | Market space |
| returnCancellationRate | number | Return/cancellation rate (%) |
| uniqQueriesWCa | integer | Add-to-cart count |
| ca | number | Add-to-cart conversion rate (%) |
| titleDensity | number | Title density |
| wordCount | integer | Word count |
| categories | array | Category ID array |
| dimension | object | Dimension object, carrying back-search-specific metrics (see below) |
| products | array | Top product data (see below) |
| id | string | Record ID |

> **Field population (based on actual responses)**: `dimension` (dimension object) **is returned for every row**, carrying back-search-specific metrics (`type` / `naturalRank` / `exposure` / `conversion` / `x`, see below). `titleDensity` (title density) and `wordCount` (word count) are returned for every row. `productCount` (product count) is returned for most rows, but individual rows may be `null`. `relevancy` (relevance) is defined in outputSchema / `columns` but **not returned** in actual `data[*]`; `categoryInfos` (category information) is similarly **not returned** (also not returned in sibling `keywordMining`, but `marketKeywordSearch` does return it — do not assume consistency).

#### dimension Dimension Object Fields

`dimension` is returned for every `data[*]` row and carries the search term's specific metrics relative to the back-searched SKU; the input-side `type` / `naturalRank` / `adRank` / `exposure` / `conversion` filters operate on these values.

| Field | Type | Description |
|------|------|------|
| type | integer | Search term channel: `0` organic search term, `1` ad search term |
| naturalRank | integer | Organic ranking (the back-searched SKU's organic position under this term) |
| exposure | number | Exposure (0–1) |
| conversion | number | Conversion rate (0–1) |
| x | array | Position/pagination indicator, semantics opaque |

> Ad term (`type:1`) rows may additionally carry `adRank`; the test SKU had only organic terms (`type:0`, querying with `type:["1"]` returned `total:0`), so `adRank` was not observed; null-check before use.

#### products[*] Top Product Object Fields

| Field | Type | Description |
|------|------|------|
| ozonId | integer | Ozon product ID |
| sku | integer | SKU ID |
| title | string | Product title (Russian) |
| imageUrl | string | Main image URL |
| advert | integer | Ad indicator (0/1) |

#### categoryInfos[*] Category Information Object Fields

> Warning: `categoryInfos` is **not returned** in actual `data[*]` rows (only appears in `columns` column definitions); the fields below are from outputSchema definition, provided for reference if they appear.

| Field | Type | Description |
|------|------|------|
| titleCn | string | Category Chinese name |
| titleEn | string | Category English name |
| titleRu | string | Category Russian name |
| cnTitlePath | string | Chinese category path |
| enTitlePath | string | English category path |
| titlePath | string | Russian category path |
| id | string | Category ID |
| crossBorderSellable | boolean | Whether cross-border sales are allowed |

## Error Codes

HTTP 200 does not prove business success. Read only the numeric outer platform `code`: `0` succeeds and any other value fails. Show outer `msg`; never test removed provider codes or nested business `code` as the platform status. Authentication, permissions, balance, and validation failures may be platform errors even with HTTP 200; also handle non-2xx HTTP and non-JSON responses.

### Recovery guidance

| Condition | Action |
|---|---|
| Parameter error | Check `msg`; common causes include missing `skuIds` / `hasVariant` / `page` etc. |
| Parameter validation failed | Check `msg`; common causes include passing empty array for `skuIds` etc. |
| Authentication failed | HTTP 401 or authorized error: Follow the **## Resolving Authentication and Credit Issues** section in SKILL.md. |
| Billing failed | HTTP 402: Follow the **## Resolving Authentication and Credit Issues** section in SKILL.md. |

## curl Example

```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/seerfar/ozon/keywordBackSearch \
  -H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Nexscope-Skill/1.0" \
  -d '{
    "skuIds": [4380710124],
    "hasVariant": 0,
    "page": {"page": 1, "pageSize": 5, "orders": [{"field": "searchVolume", "direction": "DESC"}]}
  }'
```

## Response Example (abbreviated)

Actual response for `skuIds:[4380710124]`, `hasVariant:0`, sorted by `searchVolume` DESC (2 rows shown, `products` each kept 2 entries):

```json
{
  "total": 388,
  "costTime": 1376,
  "costToken": 16000,
  "type": "tableListWorkbenches",
  "data": [
    {
      "id": "6a4559b8d1fd12d9b57aacea",
      "query": "платье женское летнее",
      "queryCn": "夏季女装",
      "platform": 0,
      "searchVolume": 1167418,
      "count30GrowthRate": -4.7,
      "productCount": 519605,
      "competingProducts": 6221,
      "sellers": 974,
      "avgPrice": 2635.0,
      "itemsViews": 131.3,
      "viewSharing": 16.9,
      "conversionSharing": 17.9,
      "marketSpace": 188,
      "returnCancellationRate": 51.7,
      "uniqQueriesWCa": 153707,
      "ca": 13.1,
      "titleDensity": 0.0,
      "wordCount": 3,
      "categories": ["15621031_200000933_93182"],
      "dimension": {"exposure": 0.3495, "x": [1], "naturalRank": 1, "type": 0, "conversion": 0.353},
      "products": [
        {"ozonId": 4380710124, "sku": 4380710124, "title": "Платье T-SOD", "imageUrl": "https://ir.ozone.ru/s3/multimedia-1-7/wc300/10636393147.jpg", "advert": 0},
        {"ozonId": 3042328733, "sku": 3042328733, "title": "Платье BELLA ROSA", "imageUrl": "https://ir.ozone.ru/s3/multimedia-1-3/wc300/9689632131.jpg", "advert": 0}
      ]
    },
    {
      "id": "6a4559d2d1fd12d9b57e7d19",
      "query": "платье",
      "queryCn": "裙子",
      "platform": 0,
      "searchVolume": 392783,
      "count30GrowthRate": -4.2,
      "productCount": null,
      "competingProducts": 5763,
      "sellers": 974,
      "avgPrice": 5791.0,
      "itemsViews": 99.8,
      "viewSharing": 16.2,
      "conversionSharing": 18.3,
      "marketSpace": 68,
      "returnCancellationRate": 55.4,
      "uniqQueriesWCa": 43543,
      "ca": 11.1,
      "titleDensity": 1.0,
      "wordCount": 1,
      "categories": ["15621031_200000933_93182"],
      "dimension": {"exposure": 0.1176, "x": [1], "naturalRank": 1, "type": 0, "conversion": 0.1004},
      "products": [
        {"ozonId": 4380710124, "sku": 4380710124, "title": "Платье T-SOD", "imageUrl": "https://ir.ozone.ru/s3/multimedia-1-7/wc300/10636393147.jpg", "advert": 0},
        {"ozonId": 3563361777, "sku": 3563361777, "title": "Платье SIMBAL Коллекция лето 2026", "imageUrl": "https://ir.ozone.ru/s3/multimedia-1-0/wc300/9173740572.jpg", "advert": 0}
      ]
    }
  ]
}
```

> Both rows are organic terms (`dimension.type:0`); row 2 has `productCount` as `null` (missing in some rows). `relevancy` / `categoryInfos` are not returned in actual `data[*]`.

---

## API Key request rate and retries

All API Keys of one Nexscope user share the public API execution request-rate allowance, measured in any rolling 1-second window. The allowed RPS depends on that user's entitlements; it is not a universal 1 RPS. One Skill operation may issue multiple public API requests, each of which uses the allowance.

HTTP 429 with Nexscope outer code `13012` means request-rate exhaustion: honor the response's `Retry-After`. Outer code `13013` means concurrent-request exhaustion, not rate exhaustion; honor `Retry-After` when supplied. Check the HTTP status and outer JSON code separately. Do not automatically replay writes or requests with uncertain outcomes; first reconcile the operation's state.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall