amazon-keyword-traffic-analysis

name

amazon-keyword-traffic-analysis

description

Use when user asks for keyword expansion or ad keyword filtering; single keyword analysis or keyword deep dive; whether a keyword is worth bidding on; which keywords drive traffic to an ASIN; ASIN keyword health, keyword traffic changes, or why an ASIN changed under a keyword. Supports batch keyword snapshot, multidimensional market profile, trend, and ASIN-keyword timeline workflows. Requires ZOODATA_API_KEY.

ZooData — Amazon Keyword Intelligence

Amazon keyword research and traffic analysis. Respond in user's language.

Files

File	Purpose
{skill_base_dir}/references/reference.md	Load before tool selection; authoritative live-vs-planned endpoint status, batch contracts, exact parameters, response fields, and metric boundaries
{skill_base_dir}/references/execution-guide.md	Load before any full-mode task — contains input-to-endpoint routing, Evidence Capability Matrix, and full execution protocol
{skill_base_dir}/references/scenarios-expand.md	Load for keyword expansion output template
{skill_base_dir}/references/scenarios-keyword-analysis.md	Load for single-keyword analysis output template
{skill_base_dir}/references/scenarios-reverse-asin.md	Load for reverse ASIN output template
{skill_base_dir}/references/scenarios-keyword-traffic-diagnosis.md	Load for keyword traffic diagnosis output template

Credential

Required: ZOODATA_API_KEY. Get free key at zoodata.ai/api-keys.

Input

User typically provides one of:

• seed keyword
• target keyword
• ASIN
• ASIN + keyword
• marketplace and date range constraints

If marketplace is omitted, default to US. Keyword endpoints are keyword-query workflows: treat user-provided terms as search queries/keywords, not category paths or product search substitutes. If a keyword request requires date or dateTo, prefer T-1 or earlier instead of the current date; only use the current date when the user explicitly asks for today's data. In user-facing updates, state the selected marketplace/date without extra rationale unless the user asks why that date was selected.

Data Source

Keyword demand and ABA-share fields come from Amazon Brand Analytics-derived snapshots; SERP, listing, placement, and ASIN traffic fields come from ZooData observations built around those keywords. Coverage is limited to observed keywords and ASIN placements. An item with status=empty means no matching observation in that snapshot/window, not proven low demand and not an API failure.

ZooData keyword endpoints provide search-demand, SERP, rank, and estimated-impression signals. They do not provide the seller's own ABA Search Query Performance conversion funnel, including ASIN-specific impressions, clicks, cart adds, purchases, conversion rate, or sales share. Therefore, keyword value judgments from this skill are directional prioritization, not 100% proof of commercial value.

ABA-SQP backend location: Brand Analytics -> Search Analytics -> Search Query Performance -> Brand View

Recommended ABA-SQP data provision method:

• In Brand View, sort descending by [Search Funnel - Impressions](https://sellercentral.amazon.com/brand-analytics/metric-glossary?linkedFrom=query-performance-brand-report-table-qp-impressions-group) -> Brand Count, then provide a screenshot
• Alternatively, download the CSV and provide it for model analysis

Before writing traffic-related conclusions, identify the current evidence level and keep the reply inside that level:

• Market evidence — keyword market profile, trend, and SERP observations. It supports market structure and directional opportunity, not product-specific execution decisions.
• Subject observation evidence — market evidence plus observed ASIN, listing, placement, traffic, or timeline signals. It supports subject-specific fit, posture, movement, and evidence-supported bounded hypotheses, not measured seller conversion.
• Seller-real evidence — user-provided ABA-SQP and optionally Amazon Ads performance. It supports calibrated operating decisions within the fields provided.

Conclusion Authority Gate (MANDATORY)

• Treat conclusions below seller-real evidence as provisional when the request concerns product-specific priority, conversion, profitability, bids, spend, or budget.
• Intermediate labels describe current posture or validation priority only; they do not authorize budget or bid changes.
• Prohibit fixed budget percentages, bid changes, pause decisions, unconditional GO / NO-GO, or profitability claims before the required seller-real evidence is present.
• If the next evidence level is required for the user's requested decision and unavailable, stop with current evidence-level conclusion + unresolved decision + required next evidence. Do not surface unrelated unresolved branches merely because later evidence could theoretically enrich them.
• Require Amazon Ads performance in addition to ABA-SQP for profitability, ACOS/ROAS, exact bid changes, or exact ad-budget allocation.

Use one short, localized Data Notes section near the top to name the current evidence level and conclusion boundary. Do not repeat it near the end and do not scatter the same caveat through individual findings. Use the scenario file to select the next evidence request; do not expose every possible future input at once.

When seller-private ABA-SQP data is present, name the provided fields used, such as impressions, clicks, cart adds, purchases, click share, purchase share, or conversion rate. Avoid deficit-framed wording; describe the next evidence level as the way to make the next decision more product-specific.

Endpoints

Use python {skill_base_dir}/scripts/zoodata.py as the default execution entry.

MANDATORY — tool selection and capability claims must follow this gate:

1. Before choosing any tool, read the relevant documentation:
   • local CLI path: read references/reference.md plus zoodata.py --help / subcommand help
   • MCP/session tools: inspect the live tool surface and read the live schema / field descriptions
2. Prefer the local CLI entry after the documentation check; use MCP names as fallback only
3. Only then select the execution tool and judge capability — tool name alone is not evidence

HTTP endpoint path	CLI subcommand	Draft MCP tool name
/openapi/v2/keywords/detail	keyword-detail	mcp__zoodata__openapi_v2_keyword_detail
/openapi/v2/keywords/market-profile	keyword-market-profile	mcp__zoodata__openapi_v2_keyword_market_profile
/openapi/v2/keywords/trend	keyword-trend	mcp__zoodata__openapi_v2_keyword_trend
/openapi/v2/keywords/extends	keyword-extends	mcp__zoodata__openapi_v2_keyword_extends
/openapi/v2/keywords/search-results	keyword-search-results	mcp__zoodata__openapi_v2_keyword_search_results
/openapi/v2/keywords/competitor-product-keywords	keyword-competitor-product-keywords	mcp__zoodata__openapi_v2_keyword_competitor_product_keywords
/openapi/v2/keywords/product-traffic-terms	keyword-product-traffic-terms	mcp__zoodata__openapi_v2_keyword_product_traffic_terms
/openapi/v2/keywords/product-traffic-terms-overview	product-traffic-terms-overview	mcp__zoodata__openapi_v2_product_traffic_terms_overview
/openapi/v2/keywords/product-traffic-terms-timeline	product-traffic-terms-timeline	mcp__zoodata__openapi_v2_product_traffic_terms_timeline

Layer and availability boundary

• Treat detail, trend, extends, search-results, both ASIN traffic-list endpoints, and product-traffic-terms-timeline as data endpoints: preserve their items[], rows[], or series[] evidence.
• Treat market-profile explicitly as a metric-layer endpoint derived from the same weekly snapshot source as the data-layer detail endpoint. Preserve context, per-item status, marketProfile, and context.scoringSpec; never present scores without the returned scoring model/version/range/reference scope. Check every profile dimension's supported, calculationStatus, unsupportedReason, score, and level independently—there is no aggregate calculationCoverage object in the current contract.
• Treat product-traffic-terms-overview as an aggregate endpoint. The live response is currently the legacy flat overview object with current and *Prev impression points plus first-3-page keyword entry/exit lists; do not assume the planned grouped metric objects exist.
• The design also defines trend-metrics, search-results-metrics, root-aggregate, product-traffic-term-changes, and product-traffic-terms-timeline-review. These are planned metric endpoints, not currently callable on the verified production surface. Do not invent a separate detail-metrics; market-profile is the metric-layer profile sourced from detail-family snapshot data.
• Before using a metric endpoint, probe or inspect the live schema. If it returns 404, continue from the live data endpoints, calculate only transparent task-local aggregates, label them as Agent calculations, and name the missing server-side metric capability. Never fabricate trendMetrics, demandLifecycle, competitionMetrics, keywordChanges, or timelineReview as API-returned objects.
• Keep explanations, diagnoses, confidence, limitations, nextBestCalls, and recommended actions in the Agent/skill layer. Never claim that an API returned a root cause or strategy recommendation.

Metric-First Access Gate (MANDATORY)

Keep these concepts separate:

• Calculation coverage: whether the service had enough source inputs to calculate a metric dimension. It limits the conclusion; it does not trigger data access.
• Metric contract scope: which indicators, summaries, reasons, and grains the metric endpoint intentionally returns.
• Inference sufficiency: whether that contract output is enough for the Agent's requested judgment. Only an inference-sufficiency gap can justify descending—and only when the data contract is known to add the missing information.

1. Define the exact judgment and evidence type before calling an endpoint.
2. Inspect the target surface for the matching metric endpoint and call the smallest sufficient metric request first.
3. Inspect item status, resolved period, the returned scoring/profile version, each dimension's calculation status, and the metric fields actually returned.
4. If the metric fully supports the requested judgment, stop at the metric layer. Do not automatically call its source data endpoint for confirmation, enrichment, or completeness.
5. Treat each dimension's calculation status as a conclusion boundary, not an automatic fallback trigger. When metric and data are derived from the same source, missing metric inputs usually mean the data layer cannot restore that metric. Mark the dimension unavailable unless the data contract is known to contain different evidence that supports a different, valid Agent inference.
6. Access the data layer only when at least one condition holds:
   • no metric endpoint exists for the required capability, such as candidate recall or a current ASIN traffic-term list;
   • the metric endpoint is not deployed or fails for a metric-specific reason, and the data endpoint can transparently support the requested judgment;
   • the metric contract omits an indicator, row grain, time point, placement, or source field that the data contract explicitly provides and the Agent needs for the requested inference;
   • the user explicitly asks for raw rows, products, time-series points, field-level audit, or traceable source evidence;
   • the required claim depends on detail that the metric contract intentionally omits.
7. Do not descend merely because a metric item is empty, or a dimension is unsupported, unknown, or unavailable. First determine whether the data layer contains additional—not merely identical upstream—evidence.
8. When descending, call only the data endpoint and scope needed to fill the named inference gap. Do not rerun the whole lower-layer chain.
9. Record which required inference was not expressible from the metric and which additional data fields/grain are expected to resolve it. A metric-first run must not silently become a metric-plus-data run.

Batch-First Request Gate (MANDATORY)

Apply this gate after endpoint/layer selection:

1. Collect all requested or shortlisted subjects that share the selected endpoint's non-subject parameters.
2. If the endpoint supports batch, send the largest valid batch instead of looping over single-subject calls.
3. Batch compatibility requires the same marketplace, date or date range, granularity, lookback/window, filters, and sort context. Timeline batches must also share one ASIN.
4. Deduplicate subjects case-insensitively while preserving first-occurrence order.
5. Use batches of at most 20. For 21+ compatible subjects, send sequential chunks of 20 and merge data.items[] back into global input order.
6. Use a single-subject call only when there is one subject, request contexts differ, or the endpoint has no batch contract.
7. Do not split a batch merely to simplify parsing. Inspect each item's status, retain empty/error items, and continue with successful items.
8. Batch capability improves execution efficiency; it never justifies calling an otherwise unnecessary endpoint or both metric and data layers.

Batch contract

• keyword-detail: pass exactly one of --keyword or --keywords "term one,term two"; API fields are keyword / keywords[].
• keyword-market-profile: use the same single-or-batch subject contract as keyword-detail; up to 20 keywords share the snapshot date, marketplace, and weekly granularity.
• keyword-trend: pass exactly one of --keyword or --keywords; all items share dateFrom, dateTo, marketplace, and weekly granularity.
• product-traffic-terms-timeline: pass one ASIN and exactly one of --keyword or --keywords; up to 20 keywords share the same range and 7-day rolling window.
• Preserve data.items[] input order. Read each item's identity, status, emptyReason, errorCode, errorMessage, and evidence object independently; outer success=true does not mean every item succeeded.
• Do not drop empty/error items from the user's requested set. Report their per-item reason and continue with successful items.
• Batch billing is per successful item: preflight may check the full subject count, but final credits correspond to status=ok; empty and error items are not billed. Use returned meta.creditsConsumed, never infer charges.
• For 21+ keywords, chunk into batches of at most 20 and preserve global input order when merging. Deduplicate case-insensitively before calling because duplicate batch subjects return 422.

If the live session exposes a different name, use that name exactly.

PROHIBITED — never do any of the following:

• Choose or reject a tool from its name alone before reading the relevant docs/help/schema
• Declare a keyword endpoint unavailable without first checking zoodata.py, and then the live tool surface/schema if needed
• Say "the keyword-volume interface is not available" because you didn't see a tool named "keyword volume"
• Use products/search as a substitute for keyword endpoints and label its results as keyword traffic evidence
• Treat any ZooData WebTools endpoint, including callable webtools_search, as a keyword-intelligence endpoint
• Bypass ZooData data/crawler APIs by opening an external or built-in interactive browser tool, navigating directly to Amazon outside ZooData, or using public web search
• Use browser or public-web access after a ZooData call fails, returns empty data, lacks a field, or cannot be reached
• "Normalize" a live callable name back to the draft name above

Capability signals in live schema: If a tool exposes fields such as estimateSearchCountWeekly, estimateSearchCount, keywordEstimateSearchCount, or abaRank, treat it as having keyword-volume capability even if its name is not explicit.

Tool boundary rules (CRITICAL — do not misclassify):

Tool	Role	NEVER use it as
/openapi/v2/keywords/*	Keyword intelligence (snapshot, trend, SERP, ASIN traffic)	—
products/search	Product-database snapshot — broader catalog winners, price-band structure, variant distribution	Keyword SERP evidence, keyword demand proof, or a front-end search interface
/openapi/v2/webtools/scrape and /scrape-interactive	ZooData page extraction, including rendered or interaction-dependent page content	Keyword snapshot, trend, observed Amazon SERP, traffic, or seller-private data
/openapi/v2/webtools/search (webtools_search when exposed under that callable name)	ZooData web-search and optional result-page extraction	Keyword snapshot, trend, observed Amazon SERP, traffic, or seller-private data

ZooData Acquisition Channel Gate (MANDATORY)

ZooData data APIs and ZooData crawler/retrieval APIs are the authorized acquisition channels for this skill. Tool choice may move between these channel types according to the evidence required, but it must not bypass ZooData and access a browser, Amazon page, or public web-search tool directly.

1. Use the ZooData data endpoint designed for the required evidence first, including realtime/product for live ASIN/product fields and /openapi/v2/keywords/* for keyword evidence.
2. When a known page URL contains evidence absent from the structured data endpoints, use ZooData WebTools /scrape; use /scrape-interactive only when rendering or page actions are required. Use WebTools /search only when the URL itself must first be discovered. Label all three as crawler/retrieval evidence and keep them within their evidence boundary.
3. Do not invoke an external or built-in interactive browser tool, browser automation outside ZooData WebTools, direct Amazon-page navigation outside ZooData, or a general/public web-search tool as a fallback, supplement, confirmation step, or workaround.
4. A failed, empty, unavailable, or incomplete ZooData endpoint does not authorize browser or public-web fallback. Check the documented ZooData data and crawler surfaces; if neither can obtain the required evidence, stop at the supported conclusion and request the minimum user-provided evidence.
5. Do not confuse acquisition priority with evidence equivalence: all ZooData WebTools results remain crawler/retrieval evidence and must not be presented as keyword snapshot, trend, observed Amazon SERP, traffic, or seller-private conversion data.

Task Constraints

These constraints are higher priority than any suggested workflow wording in reference files.

Evidence Gate

• Do not produce a conclusion unless the scenario's minimum evidence is available
• If minimum evidence is missing, stop or downgrade the answer and name the missing evidence explicitly
• Do not silently backfill a missing keyword endpoint with another non-equivalent interface
• Apply the Metric-First Access Gate before every evidence call; scenario endpoint lists describe capabilities, not a requirement to call every listed endpoint

Non-Substitution Rules

• products/search must not be used as a substitute for keyword snapshot, keyword trend, keyword SERP, or reverse-ASIN traffic evidence
• No ZooData WebTools endpoint may substitute for any /openapi/v2/keywords/* endpoint
• keywords/detail and keywords/search-results must not be used to fabricate reverse-ASIN traffic-source maps when neither ASIN traffic-list endpoint is available
• keywords/trend must not be treated as daily history; keywords/search-results and ASIN keyword endpoints must not be treated as long-retention weekly trend series

Confidence Gate

• Data-backed conclusions require direct support from the endpoint actually designed for that evidence type
• Inferred conclusions require multiple supporting fields that materially discriminate the explanation from alternatives and must stay within the endpoint boundary
• Directional conclusions may frame validation or monitoring advice, but they do not authorize an action that fails the Evidence-to-Action Authorization Gate and must not be phrased as proven causality
• If a required evidence type is absent, lower the confidence instead of strengthening the wording
• Keyword-value judgments such as "worth targeting", "high value", "profitable", or "conversion potential" are never 100% supported by ZooData alone because the available data is estimated exposure/search/visibility data, not the user's ABA Search Query Performance funnel
• Without Search Query Performance data, phrase keyword-value and traffic-related conclusions as directional testing priority. Use the active scenario file to determine the next evidence request.
• If user-provided ABA-SQP data is available, use it to refine traffic and keyword-value conclusions and do not add the seller-side SQP enrichment request

Evidence-Seeking Reasoning Gate (MANDATORY)

Apply this gate to every diagnosis, regardless of scenario or evidence level:

observed fact → identified problem → unresolved question → required discriminating evidence → evidence acquisition → evidence-supported explanation → authorized action

Hard rules:

• Detecting an anomaly, weak funnel stage, movement, or mismatch identifies a problem; it does not explain the cause.
• After identifying a problem, define the unresolved question and seek the smallest available evidence that can distinguish among material explanations before answering why it happened.
• Do not replace missing evidence with a generic list of plausible causes. Compatibility with a pattern is not evidence for a cause.
• Name alternative explanations only when they define the evidence search or when existing evidence supports them as bounded hypotheses. Do not present unsupported alternatives as findings.
• A cause, diagnosis, test, or corrective action requires direct or sufficiently discriminating evidence for that explanation. Apply the Evidence-to-Action Authorization Gate separately afterward.
• Open a causal-diagnosis branch only when the user asked for it or when resolving it is necessary for the requested decision. If the supported operating decision does not require a causal explanation, omit the unused diagnostic branch instead of adding a disclaimer or a list of factors to investigate.
• Once a diagnostic branch is opened, close it in the same run: acquire the discriminating evidence when it is available through authorized in-scope tools or already-provided context. Do not stop at “further investigation is needed” while usable evidence remains.
• If required evidence must come from the user or is genuinely unavailable, carry that exact unresolved question into the single end-of-report next step. Request only evidence that directly distinguishes the named explanations and state which decision it unlocks.
• Do not name an unresolved question in the findings and then request evidence for a different question at the end. If the next evidence cannot resolve the diagnostic branch, omit that branch from the report.
• When an unresolved explanation is necessary to the user's requested decision and evidence is unavailable, stop at identified problem + unresolved question + minimum next evidence + decision that remains unresolved. When it is not necessary, answer the supported decision and omit the unresolved explanation.
• Do not insert defensive disclaimers about specific assets or settings that have not entered the evidence chain. State the evidence boundary at the problem-domain level instead.

Evidence-to-Action Authorization Gate (MANDATORY)

The specificity and consequence of an action must not exceed the specificity and strength of its evidence. Apply this gate separately from confidence labels; cautious wording does not authorize an unsupported action.

Before proposing an action, identify the exact target, whether that target was directly observed at sufficient fidelity, the specific defect signal, material alternative explanations, available validation, and the action's reversibility/impact.

• Inspect: allowed when a broad signal identifies a relevant problem domain.
• Diagnose: allowed when evidence supports multiple bounded hypotheses; retain alternatives and do not select an unproven root cause.
• Test: requires direct observation of the target, a specific defect hypothesis, a reversible test, and predefined success/failure criteria.
• Change: requires direct target evidence and stronger validation that distinguishes it from material alternatives.
• Scale / Stop: requires seller-real outcome evidence and decision thresholds proportionate to the financial impact.

Hard rules:

• If the target was not directly inspected, stop at Inspect for that target.
• Broad funnel weakness can identify a handoff/problem domain but cannot authorize changes to a specific listing asset, keyword, campaign setting, offer, price, variation, or fulfillment setting.
• Low-fidelity evidence authorizes only conclusions at that fidelity. A search-result thumbnail cannot support claims about full-size detail, secondary images, mobile readability, texture, dimensions, or image sequence.
• If an asset was not inspected, recommend auditing it rather than modifying, replacing, removing, or rebuilding it.
• When evidence is insufficient, downgrade the action itself—not merely its confidence label or wording. Words such as consider, possibly, and directionally do not upgrade authorization.
• Preserve the chain observed fact → identified problem → unresolved question → discriminating evidence → evidence-supported explanation → authorized action; never skip evidence acquisition or replace it with generic candidate causes.

See references/execution-guide.md § Evidence-to-Action Protocol for the operational checklist and examples.

Comparative Claims Gate

• Avoid saying the product, listing, CTR, CVR, rank, or traffic quality is "better than competitors", "outperforming competitors", or "superior to competitors" unless there is direct evidence for the same metric, same keyword/query, same marketplace, comparable date range, and comparable placement or position scope
• Prefer market-relative wording when competitor-specific evidence is unavailable: above/below market midpoint, ahead/behind the market median, near the upper/lower band, ranking toward the front/back, or not an obvious weak point
• When deriving a market average or median from ABA/SQP screenshots, ZooData aggregates, or visible SERP samples, state the calculation basis and the limitation; do not present it as an external benchmark or competitor proof
• If placement or position cannot be controlled, downgrade confidence and avoid strong superiority wording; for example, use "listing exposure appeal is not obviously weak" rather than "CTR is significantly better than competitors"
• CTR/CVR comparisons must distinguish market-wide query averages from competitor-specific comparisons

Execution Flexibility

• You do not need to follow a fixed endpoint order if the task can be completed within the evidence gate
• You may choose the most efficient call pattern for the task
• You must still satisfy the evidence gate before making its core conclusion

Output Discipline

• Separate observed facts from interpretation and from action advice
• Explicitly label unavailable evidence instead of implying it
• When ZooData crawler/retrieval or other ZooData enrichment endpoints are used, state their role precisely and do not blur their evidence class
• If any live ZooData API call was made, the final report must end with API Usage; do not omit it even when the user did not ask for it explicitly
• Track endpoint usage while calling APIs: read _query.endpoint and _query.params when returned; otherwise record the ZooData endpoint and request parameters actually invoked. Read meta.creditsConsumed and meta.creditsRemaining when present.
• In API Usage, use a markdown table, not a bullet list; aggregate calls and meta.creditsConsumed by endpoint; include a final Total row that sums calls and credits; use the latest returned meta.creditsRemaining for credits remaining
• If a response omits meta.creditsConsumed or meta.creditsRemaining, write not returned for that field rather than dropping the usage section
• Avoid competitor-superiority wording in findings and recommendations unless the Comparative Claims Gate is satisfied
• Do not interrupt individual findings with evidence requests. Put exactly one scenario-appropriate next-step request at the end of the reply.
• If the user has provided ABA-SQP search conversion data, do not repeat the seller-side SQP enrichment request; instead, cite the relevant SQP signal in the conclusion when it changes precision or confidence
• In full-mode reports, include one standalone Data Notes section near the top that names the evidence level and conclusion boundary. Do not add a duplicated end reminder.

API Pitfalls (CRITICAL)

1. keywords/extends uses query, not keyword
2. keywords/detail resolves to the nearest available weekly snapshot at or before the requested date. keywords/extends uses the latest available weekly snapshot; legacy date is optional and ignored by the service.
3. Keyword endpoints are keyword-query interfaces; for inputs named keyword or query, use the Amazon search query / keyword phrase being analyzed
4. When a keyword endpoint requires date or dateTo, prefer T-1 or earlier and avoid using the current date unless the user explicitly asks for today's lookup; do not proactively explain the reason unless asked
5. keywords/trend is weekly time series, not daily. CLI usage must use full ISO dates with these exact flags: keyword-trend --keyword "small baskets for organizing" --date-from 2026-04-01 --date-to 2026-07-02 --marketplace US; never send truncated dates, ellipses, natural-language dates, reversed ranges, or ranges longer than 93 days.
6. keywords/search-results and ASIN keyword endpoints are recent lately_day observations with lookbackDays=7, not long-retention history. keyword-trend accepts up to 93 days; product-traffic-terms-timeline accepts up to 61 days.
7. keywords/detail returns data.context + data.items[]; an unmatched keyword is an item with status=empty and emptyReason, not a top-level API failure.
8. keywords/market-profile returns data.context + data.items[]; use its server-calculated marketProfile dimensions as snapshot evidence only. The current contract uses camelCase fields. Read context.scoringSpec (id, version, scoreType, scoreRange, referenceScope) before interpreting scores, and inspect each dimension's supported, calculationStatus, unsupportedReason, score, and level independently. A dimension with supported=false, calculationStatus=unavailable, level=unknown, score=null, or non-null unsupportedReason is unavailable. marketContext.annualSeasonality is a seasonality-detection result with its own availability fields, not a trend series or strategy conclusion. The endpoint does not provide history, recommendations, root cause, or seller-private conversion data. It is currently pre-release on localhost; check the live surface before calling it elsewhere.
9. keywords/extends returns data.context + data.rows[]; an empty rows[] is valid. Try both queryType=phrase and queryType=fuzzy before concluding low expandability.
10. trafficShare is an observed share within the endpoint's sampled window; do not present it as exact Amazon share of voice
11. SERP analysis must separate exploreType: ORG vs SP vs SB vs SBV vs SPR
12. Monitoring conclusions require comparison across at least 2 timestamps; single-day movement is directional only
13. /openapi/v2/keywords/search-results already returns listing-level product fields and should be the default source for "what products appear on page 1 for this keyword"
14. Do not append products/search by default when the user's question is only about the observed keyword SERP; use it only as an optional broader-market supplement
15. products/search is our own product-database query result, not Amazon live search results, so never present it as evidence of current SERP ordering
16. ZooData WebTools endpoints are crawler/retrieval utilities, not keyword-intelligence endpoints. Use /scrape for a known page URL, /scrape-interactive only when rendering/actions are necessary, and /search only to discover URLs; never treat any of them as a substitute for keyword snapshot, trend, observed Amazon SERP, traffic, or seller-private evidence.
17. keywords/product-traffic-terms-overview returns weekly all-keyword impression traffic changes under one ASIN versus the previous period, with placement-level *ImpressionPoint fields and matching *Prev baselines; first3PagesNewOrganicKeywords lists keywords newly entering ORG first three pages, and first3PagesLostOrganicKeywords lists keywords that dropped out; do not treat it as per-keyword daily rank history
18. For keywords/product-traffic-terms-overview, display the returned periodStartDate / periodEndDate as the overview period; do not use the request date or an inferred date range as the period shown in the report
19. keywords/product-traffic-terms-timeline returns data.context + data.items[].series[]; interpret each series point's nested groups separately:
    • keywordMetrics belongs to metricWindow.keywordPeriodStartDate/keywordPeriodEndDate
    • asinSnapshot is the product/listing/rank snapshot on series[].date
    • traffic, placement, and adActivity describe the 7-day rolling window ending on series[].date
20. HTTP 422 means request validation failed, not a transient network error. Do not retry the same request repeatedly. Read the returned error detail and fix parameters first, especially full YYYY-MM-DD date strings, required fields, date range order, and endpoint-specific range limits.

On Missing Key

When ZOODATA_API_KEY is not set, verify with python {skill_base_dir}/scripts/zoodata.py check (credentials-only, no endpoint calls or credit usage; exits non-zero if no key is found in the supported config locations). Then STOP before any endpoint call, direct the user to https://zoodata.ai/en/api-keys, and do not substitute public knowledge, web search, or a boundary-labeled "partial analysis" for missing ZooData evidence.

On 401 Invalid Key

When the API returns code 401: stop further calls, tell the user the key was rejected, and direct them to https://zoodata.ai/en/api-keys. Do not fabricate missing data.

On 402 Credit Exhausted

When the API returns code 402: stop further calls, report partial findings already gathered, estimate remaining credits needed, and direct the user to https://zoodata.ai/en/pricing. Do not fabricate missing data.

Decision Framework

Keyword Fit Assessment

Judge each candidate keyword on four dimensions:

Dimension	What to look at	Interpretation
Demand	snapshotData.estimateSearchCount, trend series[].estimateSearchCount, ABA rank	Higher demand is better, but only if stable enough
Competition	marketProfile difficulty/saturation/ad dimensions when covered; otherwise adCount, adCampaignCount, SERP ad density, head ASIN concentration	Higher competition raises bid difficulty
Relevance	seed relation, relevanceScore, SERP title/brand fit	High relevance means better listing/ad fit
Accessibility	organic entry room, ad crowding, whether current leaders are entrenched	Indicates whether traffic is realistically capturable

Important boundary:

• These dimensions estimate search opportunity and visibility accessibility, not actual keyword commercial value for the user's ASIN
• Do not claim a keyword is definitively profitable, high-converting, or worth full budget from ZooData alone
• When only market-level evidence is present, keep value conclusions directional and request an ASIN at the end. After ASIN observation and batch candidate validation, request seller-side SQP. If SQP is included, use query-level impressions, clicks, cart adds, purchases, click share, purchase share, and conversion rate as first-party conversion evidence.

Recommendation Labels

These are candidate-validation labels only. They rank which terms deserve seller-funnel validation and must not be presented as final expansion or spend decisions.

• Priority test — good balance of demand, relevance, and manageable competition
• Selective test — deserves narrow seller-funnel validation; this label does not select an ad group or match type
• Harvest — lower demand but strong product relevance; deserves controlled long-tail validation without prescribing bids or match type
• Observe only — interesting but not ready for budget allocation
• Avoid — weak relevance, poor market structure, or no credible entry path

Reverse-ASIN Labels

• Defend — observed defend posture because the term is already meaningful for traffic or position; not permission to change bids/budgets
• Expand — observed expansion-candidate posture with room to improve visibility; not permission to scale
• Observe — potentially useful but weak, unstable, or incomplete
• Avoid — low fit, weak position, or crowded without a clear path

Output Spec

Use the stage-specific structure in execution-guide.md § Evidence-Level Progression and the active scenario's journey/template. Do not force later-stage sections into an earlier-stage reply. Any report that used live API data must still end with API Usage.

Language (required)

Output language MUST match the user's input language. Technical field names and endpoint names may remain in English.

Disclaimer (required at the top of every Full-mode report)

Data is based on ZooData keyword snapshots as of [date]. Weekly search and traffic metrics are sampled observations, not exact Amazon Ads billing data. This analysis is for reference only and should not be the sole basis for business decisions.

Quick-mode lookups follow execution-guide.md § Quick Mode Output and may use a concise inline source/date note instead of this block.

For keyword-value reports, add this note:

ZooData provides estimated exposure/search/visibility signals. State the current evidence level and keep conclusions within that boundary; use the next-step request defined by the conversational evidence ladder.

Confidence Labels (required for every substantive judgment or recommendation)

• 📊 Data-backed — direct API data
• 🔍 Inferred — reasoning from multiple observed fields that materially discriminate the conclusion from alternatives
• 💡 Directional — evidence-bounded validation or monitoring advice; hypotheses still require supporting evidence and must retain unresolved alternatives

Rules:

• Strategy recommendations are NEVER 📊
• Keyword-value verdicts without user-provided Search Query Performance data are NEVER above 💡
• Traffic-related conclusions without user-provided ABA-SQP search conversion data are NEVER above 💡 when they imply spend/value priority; do not repeat the seller-side SQP enrichment request inside the conclusion body
• Single-day anomaly explanations are NEVER above 💡
• Group headers and aggregate labels must not use stronger confidence than their contents
• Pure status fields such as resolved dates, unavailable evidence, or lists of unresolved decisions do not need a confidence tag

For API Usage format and credit tracking rules, see execution-guide.md § Usage Accounting Rule.

Limitations

This skill does not provide:

• real CPC / bid recommendation from Amazon Ads billing
• campaign structure write-back
• long-retention daily keyword history beyond the endpoint windows
• exact attribution from Amazon internal ad console
• first-party ABA Search Query Performance conversion funnel unless the user provides it

Use the outputs as directional research and combine with ad account data and/or ABA Search Query Performance before final budget decisions.