nexscope-ai/nexscope-ecommerce-skills / ecommerce-amazon-keyword-summary
ecommerce.amazon-keyword-summary
VerifiedBreak down all competitor ASIN traffic sources under a given keyword -- organic search, SP ads, SB brand ads, SBV video ads, SP recommendations, AC/ER/TR recommendation slots, with support for ASIN filtering, custom date ranges, and new traffic keyword filters. Trigger when the user mentions keyword traffic sources, which competitors are grabbing traffic under this keyword, organic traffic vs paid traffic share, SP ad exposure, brand ad share, SP recommendation slots, recommendation ad/non-ad split, search display analysis, Amazon's Choice or editorial recommendation exposure, keyword competitive landscape, ASIN traffic composition, keyword traffic, traffic structure analysis, search share, ad share, traffic source distribution, Nexscope, traffic analysis, SP recommendation, recommend position breakdown. Even if the user does not explicitly mention "Nexscope", if their need involves analyzing competitor ASIN traffic source distribution under a keyword, this skill should also be triggered.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.7 KB |
| manifest.json | config | 232 B |
| references/api.md | markdown | 12.0 KB |
| scripts/amazon_keyword_summary.py | script | 6.6 KB |
references/api.md
View on GitHub# Nexscope - Keyword Traffic Sources API Reference
## API Specification
- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sif/keywordSummary`
- **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 |
|------|------|------|------|
| searchKeyword | string | Yes | Search keyword, translate to the corresponding country's language whenever possible. Max length 1000 characters |
| country | string | No | Country site, default `US`. Options (13 total): `US`, `UK`, `DE`, `CA`, `JP`, `FR`, `ES`, `IT`, `MX`, `AU`, `AE`, `BR`, `SA` |
| asins | string | No | ASIN filter list, comma-separated; if not provided, returns all ASINs for this keyword. Max length 1000 characters |
| condition | string | No | Condition filter, only one at a time.<br>**Flag type**: `nfPosition` (natural traffic keyword), `isSpAd` (SP ad keyword), `isVedioAd` (video ad keyword), `isBrandAd` (brand ad keyword), `isPPCAd` (PPC ad keyword), `isSearchRecommend` (search recommendation keyword), `acAd` (SP recommendation)<br>**Period count type**: `totalPeriod.in` (new incoming traffic keywords), `nfKeywordCnt.total` / `.in`, `adKeywordCnt.total` / `.in`, `allSpKeywordCnt.total` / `.in`, `spKeywordCnt.total` / `.in`, `recSpKeywordCnt.total` / `.in`, `allSbKeywordCnt.total` / `.in`, `sbKeywordCnt.total` / `.in`, `sbvKeywordCnt.total` / `.in` |
| last7d | boolean | No | Whether to get last 7 days data, default `true`. When `false`, use `startDate`/`endDate` range |
| startDate | string | No | Start date `yyyy-MM-dd` (effective when `last7d=false`; if omitted, the latest system full week is used) |
| endDate | string | No | End date `yyyy-MM-dd` (paired with `startDate`) |
| sortBy | string | No | Sort field. Options: `totalKeywordNum` (all traffic keywords), `naturalKeywordNum` (natural traffic keywords), `brandKeywordNum` (brand ad keywords), `vedioKeywordNum` (video ad keywords), `acKeywordNum` (AC recommended keywords), `erKeywordNum` (ER recommended keywords), `trKeywordNum` (TR recommended keywords), `sumScore` (total keyword exposure score), `totalNfScore`, `totalSpSocre` (note spelling), `totalBrandScore`, `totalVedioScore`, `totalAcScore`, `totalTrScore`, `totalErScore` |
| pageNum | integer | No | Page number, default `1` |
| pageSize | integer | No | Results per page, min 10, max 100, default `100` |
| desc | boolean | No | Whether to sort descending, 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
### Top-Level Fields
| Field | Type | Description |
|------|------|------|
| total | integer | Number of data records actually returned |
| data | array | Return data, array of product keyword traffic data objects |
| columns | array | Render columns |
| type | string | Render style |
| title | string | Title |
| costTime | integer | Latency (ms) |
| costToken | integer | Tokens consumed |
> This endpoint does not return `isParentAsin`, `variantsNum`, or `noKeywordVariantsNum`; use the `sif/asinSummary` endpoint if you need these fields.
### Data Item Fields (Each Object in the `data` Array)
> Two types of scores: unprefixed fields (e.g. `naturalSearchExposureScore`) are product-level aggregate metrics for this ASIN across all keywords; `keyword*` prefixed fields (e.g. `keywordNaturalExposureScore`) are metrics for this ASIN only on the current query keyword.
| Field | Type | Description |
|------|------|------|
| asin | string | ASIN code |
| productTitle | string | Product title |
| productImageUrl | string | Product main image URL |
| productPrice | number | Product price |
| customerRatingCount | integer | Total customer rating count |
| productStarRating | number | Product star rating (0-5 stars) |
| productRatingScore | number | Product rating score value |
| productUpdateTime | string | Product update time (`yyyy-MM-dd HH:mm:ss`) |
| dataPeriodStartDate | string | Data period start date (`yyyy-MM-dd`) |
| totalExposureScore | number | Total exposure score |
| totalExposureRatio | number | Total traffic share |
| naturalSearchExposureScore | number | Natural search exposure total score |
| naturalSearchExposureRatio | number | Natural search exposure ratio |
| sponsoredProductsExposureScore | number | SP ad exposure total score |
| sponsoredProductsExposureRatio | number | SP ad exposure ratio |
| brandAdExposureScore | number | Brand ad exposure total score |
| brandAdExposureRatio | number | Brand ad exposure ratio |
| videoAdExposureScore | number | Video ad exposure total score |
| videoAdExposureRatio | number | Video ad exposure ratio |
| amazonsChoiceExposureScore | number | AC exposure total score |
| amazonsChoiceExposureRatio | number | AC exposure ratio |
| editorialRecommendationsExposureScore | number | ER exposure total score |
| editorialRecommendationsExposureRatio | number | ER exposure ratio |
| topRatedExposureScore | number | TR exposure total score |
| topRatedExposureRatio | number | TR exposure ratio |
| recommendPositionExposureScore | number | Recommendation position exposure total score |
| recommendAdExposureScore | number | Recommendation position ad exposure score |
| recommendAdExposureRatio | number | Recommendation position ad traffic share |
| recommendNonadExposureScore | number | Recommendation position non-ad exposure score |
| recommendNonadExposureRatio | number | Recommendation position non-ad traffic share |
| comprehensiveNaturalExposureScore | number | Comprehensive natural traffic score (natural search + recommendation non-ad) |
| comprehensiveNaturalExposureRatio | number | Comprehensive natural traffic share |
| keywordTotalExposureScore | number | Keyword total score |
| keywordNaturalExposureScore | number | Keyword natural score |
| keywordSponsoredProductsExposureScore | number | Keyword SP ad score |
| keywordBrandAdExposureScore | number | Keyword brand ad score |
| keywordVideoAdExposureScore | number | Keyword video ad score |
| keywordAmazonsChoiceExposureScore | number | Keyword AC score |
| keywordRecommendExposureScore | number | Keyword recommendation position score |
| keywordRecommendAdExposureScore | number | Keyword recommendation position ad score |
| keywordRecommendNonadExposureScore | number | Keyword recommendation position non-ad score |
| keywordComprehensiveNaturalExposureScore | number | Keyword comprehensive natural score (natural + recommendation non-ad) |
| ppcTrafficSources | array | PPC paid ad traffic source markers. Contains: SP ads, top brand ads, bottom brand ads, video ads |
| naturalSearchTrafficSources | array | Natural search traffic source markers |
| amazonRecommendationSources | array | Amazon recommendation traffic source markers. Contains: Best Seller, AC, ER, TR, TRFOB, etc. |
| promotionalDealSources | array | Promotional deal traffic source markers. Contains: Coupon, Limited Time Deal, Lowest Price in 30 Days, etc. |
> This endpoint does not return the following fields: `productCategory`, `productFeatures`, `isVariantProduct`, `isMonitored`, `monitoringStartTime`, and per-ASIN `totalTrafficKeywordCount`, `naturalSearchKeywordCount`, `sponsoredProductsKeywordCount`, `brandAdKeywordCount`, `topBrandAdKeywordCount`, `bottomBrandAdKeywordCount`, `videoAdKeywordCount`, `amazonsChoiceKeywordCount`, `editorialRecommendationsKeywordCount`, `topRatedKeywordCount`, `frequentlyBoughtKeywordCount`. Use the `sif/asinSummary` endpoint if you need these fields.
## 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 balance | HTTP 402: follow the **## Resolving Authentication and Credits Issues** section in SKILL.md. |
## curl Example
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sif/keywordSummary \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"searchKeyword": "wireless charger", "country": "US"}'
```
### With Condition Filter (SP Ad Keywords Only):
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sif/keywordSummary \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"searchKeyword": "wireless charger", "country": "US", "condition": "isSpAd"}'
```
### Filter by ASIN + Specified Date Range:
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sif/keywordSummary \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"searchKeyword": "wireless charger", "country": "US", "asins": "B01NBNDC1T,B09VLJJPL6", "last7d": false, "startDate": "2026-04-05", "endDate": "2026-04-11"}'
```
### Sort by SP Exposure Score:
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sif/keywordSummary \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"searchKeyword": "wireless charger", "country": "US", "sortBy": "totalSpSocre", "desc": true}'
```
### With Pagination:
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/sif/keywordSummary \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"searchKeyword": "phone case", "country": "US", "pageNum": 2, "pageSize": 50}'
```
---
## 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 |