Skip to content

nexscope-ai/nexscope-ecommerce-skills / ecommerce-etsy-store-query

ecommerce.etsy-store-query

Verified

Query Etsy stores with multi-dimensional filters (sales, favorites, reviews, store opening date, country, primary category, Raving/Star ratings). Trigger when user mentions Etsy store, Etsy shop search, Etsy seller, Etsy shop ranking, Etsy weekly sales stores, Etsy stores, or Etsy store query — even if the tool name is not mentioned, as long as the need is to find stores, filter store data, or analyze store performance on Etsy.

FileKindSize
SKILL.mdskill md2.7 KB
manifest.jsonconfig416 B
references/api.mdmarkdown6.9 KB
scripts/etsy_store_query.pyscript7.9 KB

references/api.md

View on GitHub
# `_ehunt_storeQuery` API Reference

## Call Notes

- **Tool Name**: `_ehunt_storeQuery` (Nexscope MCP, `serverName`: Third-party data service).
- **MCP Display Name**: Etsy Store Query.
- **Note**: Business fields depend on the operation. Only the outer numeric platform `code: 0` indicates success; a nested business `code` does not replace it.

## Request Parameters (JSON)

| Parameter | Type | Required | Description |
|------|------|------|------|
| beginFavorites | integer, >=0 | No | Store favorite count (start), combined with end value to form the upstream favorites range |
| beginFavoritesWeekly | integer, >=0 | No | Store weekly new favorites (start), combined with end value to form the upstream favorites_weekly range |
| beginReviews | integer, >=0 | No | Store review count (start), combined with end value to form the upstream reviews range |
| beginReviewsWeekly | integer, >=0 | No | Store weekly new reviews (start), combined with end value to form the upstream reviews_weekly range |
| beginSales | integer, >=0 | No | Store total sales (start), combined with end value to form the upstream sales range |
| beginSalesWeekly | integer, >=0 | No | Store weekly sales (start), combined with end value to form the upstream sales_weekly range, e.g., 10,100 |
| beginStoreOpenedAt | string, pattern | No | Store opening date range start (YYYY-MM-DD), combined with end date to form the upstream start_at, e.g., 2020-01-01~2023-01-01 |
| category | string, maxLen=1000 | No | Store primary category |
| country | string, maxLen=1000 | No | Store country |
| endFavorites | integer, >=0 | No | Store favorite count (end) |
| endFavoritesWeekly | integer, >=0 | No | Store weekly new favorites (end) |
| endReviews | integer, >=0 | No | Store review count (end) |
| endReviewsWeekly | integer, >=0 | No | Store weekly new reviews (end) |
| endSales | integer, >=0 | No | Store total sales (end) |
| endSalesWeekly | integer, >=0 | No | Store weekly sales (end) |
| endStoreOpenedAt | string, pattern | No | Store opening date range end (YYYY-MM-DD) |
| isRaving | integer | No | Whether Raving store: 1=Yes |
| isStar | integer | No | Whether starred store: 1=Yes |
| page | integer, >=1, default 1 | No | Page number (starting from 1) |
| pageSize | integer, 1~100, default 20 | No | Items per page, max 100 |
| searchKey | string, maxLen=500 | No | Search keyword, store name, or store URL |
| sortBy | integer (8~11) | No | Sort field sort_by: 8=total sales, 9=weekly sales, 10=review count, 11=favorite count |
| sortDesc | integer | No | Sort direction (corresponds to upstream desc): 1=descending, 0=ascending |
| status | integer | No | Store status: 1=active, 0=inactive |

## 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.

## Main Response Fields

| Field | Type | Description |
|------|------|------|
| total | integer | Record count (number of records returned on this page) |
| sourceTool | string | Tool type: ehunt |
| sourceType | string | Source type: etsy |
| stores | array | Store list |
| columns | array | Rendered columns |
| costToken | integer | Token consumption (estimated based on records returned on this page) |
| storeNum | integer | Total number of matching stores (upstream store_num) |
| title | string | Title |
| type | string | Render style |

### `stores[]` Elements

| Field | Type | Description |
|------|------|------|
| category | array | Primary category list |
| country | array | Country/region list |
| favorites | integer | Favorite count |
| favoritesWeekly | integer | Weekly new favorites |
| isRaving | integer | Whether Raving: 1=Yes |
| isStar | integer | Whether starred: 1=Yes |
| logoUrl | string | Store avatar URL |
| productCount | integer | Store product count |
| rating | number | Rating |
| reviews | integer | Review count |
| reviewsWeekly | integer | Weekly new reviews |
| salesTotal | integer | Total sales |
| salesWeekly | integer | Weekly sales |
| shopWebsite | string | Store website/external link |
| startAt | string | Store opening date |
| status | integer | Store status: 1=active, 0=inactive |
| storeId | string | Store ID |
| storeName | string | Store name |
| storeUrl | string | Store link |

## Script Debugging (Optional)

The repository provides **`scripts/etsy_store_query.py`** (Python 3, standard library only), which POSTs JSON matching the MCP parameters to the Nexscope tool gateway.

- **Gateway**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/ehunt/etsy/storeQuery` (can be overridden via `NEXSCOPE_PROXY_BASE_BASE` for the root URL)
- **Authentication**: Environment variable `NEXSCOPE_API_KEY` (same as other `nexscope-*` skills; if not configured, follow **## Resolving Authentication and Credit Issues** in SKILL.md)

```bash
export NEXSCOPE_API_KEY="<your-key>"
python scripts/etsy_store_query.py '{"searchKey": "ceramic", "country": "US", "page": 1, "pageSize": 20}'
```

## 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.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall