nexscope-ai/nexscope-ecommerce-skills / ecommerce-amazon-competitor-lookup
ecommerce.amazon-competitor-lookup
VerifiedUse Nexscope data to find and analyze competitors on Amazon, covering 12 marketplaces, with product metrics including sales, BSR, pricing, ratings, and growth trends. Trigger when the user mentions competitor lookup, competitor analysis, ASIN reverse lookup, competitive product research, finding similar products, market competitor discovery, product benchmarking, competitor sales estimation, analyzing competitor listings, competitor analysis, ASIN reverse lookup, competitor sales, competitor research, Nexscope, market competitor discovery, competitor trends. Even if the user does not explicitly mention "Nexscope" or "competitor lookup", if their need involves discovering and analyzing Amazon competitors by ASIN, keyword, seller name, brand, or category, this skill should also be triggered.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.0 KB |
| manifest.json | config | 229 B |
| references/api.md | markdown | 10.3 KB |
| scripts/amazon_competitor_lookup.py | script | 6.6 KB |
references/api.md
View on GitHub# Nexscope - Competitor Lookup API Reference
## API Specification
- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sellersprite/competitor-lookup`
- **HTTP Method**: POST, Content-Type: application/json
- **Authentication**: Header `Authorization: <api_key>`, api_key is read from environment variable `NEXSCOPE_API_KEY` or `NEXSCOPE_API_KEY` (if not configured, follow the **## Resolving Authentication and Credits Issues** section in SKILL.md)
## Request Parameters
POST Body (JSON):
| Parameter | Type | Required | Description |
|------|------|------|------|
| marketplace | string | No | Amazon site code, default `US`. Options: US, UK, DE, FR, JP, CA, IT, ES, MX, AU, TR, IN |
| keyword | string | No | Search keyword. Translate to the corresponding country's language whenever possible, e.g. use English keywords for the US, German keywords for Germany, etc. |
| asinList | string | No | ASINs, multiple ASINs comma-separated, max 40. Format: `^[A-Z0-9]+(,[A-Z0-9]+){0,39}$` |
| sellerName | string | No | Seller name filter |
| brand | string | No | Brand name filter |
| nodeLabel | string | No | Amazon category name, supports multi-level category names, levels separated by colon `:`, e.g. `Electronics:Headphones` |
| nodeIdPath | string | No | Amazon category ID path |
| matchType | integer | No | Match type. 1 = phrase match (default), 2 = fuzzy match, 3 = exact match |
| showVariation | string | No | Whether to query variants. `Y` = yes, `N` = no (default) |
| dataSnapshotMonth | string | No | Amazon product data snapshot month. Default `nearly` (queries last 30 days real-time data). Use `yyyyMM` format to query historical snapshots (e.g. `202412` for December 2024). Only supports existing historical snapshots, future dates are not supported. Recommended for seasonal analysis to query the same period last year's snapshot for comparison |
| page | integer | No | Page number, starting from 1 (default 1) |
| size | integer | No | Results per page, returns 10-100 records (default 50) |
| order | object | No | Sort configuration (see below) |
### Sort Object (order)
| Field | Type | Required | Description |
|------|------|------|------|
| field | string | Yes | Sort field. Options: `total_units` (monthly sales), `total_amount` (monthly revenue), `bsr_rank` (BSR rank), `price` (price), `rating` (rating), `reviews` (review count), `profit` (gross margin), `reviews_rate` (review rate), `available_date` (listing time), `questions` (Q&A count), `total_units_growth` (monthly sales growth rate), `total_amount_growth` (monthly revenue growth rate), `reviews_increasement` (monthly new review count), `bsr_rank_cv` (7-day BSR growth count), `bsr_rank_cr` (7-day BSR growth rate), `amz_unit` (variant sales). Default: `total_units` |
| desc | string | Yes | Sort direction. `true` = descending, `false` = ascending. Default: `true` |
## 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 matching result count |
| sourceType | string | Source type (e.g. `amazon`) |
| type | string | Render style |
| nodeLabel | string | Category name echo |
| columns | array | Render column definitions |
| products | array | Competitor list (see below) |
| costToken | integer | Tokens consumed |
### Competitor Object Fields (products)
| Field | Type | Description |
|------|------|------|
| asin | string | Product ASIN |
| title | string | Product title |
| price | number | Current price |
| primePrice | number | Prime price |
| averagePrice | number | Average price |
| currency | string | Currency |
| monthlySalesUnits | integer | Monthly sales volume (units) |
| monthlySalesRevenue | number | Monthly sales revenue |
| monthlySalesUnitsGrowthRate | number | Monthly sales volume growth rate |
| bsr | integer | BSR rank |
| bsrGrowthRate | number | BSR growth rate |
| bsrGrowthCount | integer | BSR growth count |
| rating | number | Rating |
| ratings | integer | Review count |
| ratingsGrowth | integer | Monthly new review count |
| ratingsRate | number | Review rate |
| brand | string | Brand |
| brandUrl | string | Brand URL |
| sellerName | string | BuyBox seller name |
| sellerId | string | BuyBox seller ID |
| sellerNation | string | BuyBox seller nationality |
| sellerNum | integer | Number of sellers |
| fulfillment | string | Fulfillment method: AMZ, FBA, FBM |
| availableDate | string | Listing time (date format) |
| availableDateString | string | Listing date (string format) |
| profit | number | Gross margin |
| fba | number | FBA shipping fee |
| deliveryPrice | number | Seller shipping fee |
| imageUrl | string | Product image URL |
| parent | string | Parent ASIN |
| variationNum | integer | Number of variations |
| variant30DayUnits | integer | Variant monthly sales (units) |
| variant30DayRevenue | number | Variant monthly sales revenue |
| variant30DayUpdatedAt | string | Variant data update time (timestamp) |
| amzUnitDateString | string | Variant sales update date |
| listingQualityScore | number | Listing quality score |
| nodeLabelPath | string | Category path |
| nodeIdPath | string | Node ID path |
| nodeId | integer | Node ID |
| dimension | string | Product dimensions |
| dimensionsType | string | Dimension type |
| weight | string | Product weight |
| packageDimensions | string | Package dimensions |
| packageDimensionType | string | Package dimension type |
| packageWeight | string | Package weight |
| sku | string | SKU |
| keyword | string | Matching keyword (if searched by keyword, displays the corresponding keyword) |
| dataSnapshotMonth | string | Data query month |
| sourceTool | string | Source tool |
| sourceType | string | Source type |
| badgeBestSeller | string | Best Seller badge (Y/N) |
| badgeAmazonChoice | string | Amazon's Choice badge (Y/N) |
| badgeNewRelease | string | New Release badge (Y/N) |
| badgeEbc | string | A+ page (Y/N) |
| badgeVideo | string | Video introduction (Y/N) |
| badge | object | Badge detail object, containing: `bestSeller`, `amazonChoice`, `newRelease`, `ebc`, `video` (all Y/N strings) |
| subcategories | array | Subcategory rankings, each entry containing `code` (category code), `rank` (rank), `label` (name) |
## curl Example
### Keyword Search
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sellersprite/competitor-lookup \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"marketplace": "US", "keyword": "wireless earbuds", "matchType": 1, "size": 20}'
```
### ASIN Query
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sellersprite/competitor-lookup \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"marketplace": "US", "asinList": "B072MQ5BRX,B08N5WRWNW"}'
```
### Sort by Monthly Revenue with Pagination
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sellersprite/competitor-lookup \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"marketplace": "US", "keyword": "phone case", "order": {"field": "total_amount", "desc": "true"}, "page": 1, "size": 50}'
```
### Historical Snapshot Query
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sellersprite/competitor-lookup \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"marketplace": "US", "keyword": "space heater", "dataSnapshotMonth": "202412", "order": {"field": "total_units", "desc": "true"}, "size": 20}'
```
## 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 |
|---|---|
| Authentication failed | HTTP 401 or authorized error: follow the **## Resolving Authentication and Credits Issues** section in SKILL.md. |
| Insufficient credits | HTTP 402: follow the **## Resolving Authentication and Credits Issues** section in SKILL.md. |
## 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |