Amazon Ranked Keywords Analyzer — find every keyword your product ranks for

✨ What you get

Discover all the search keywords an Amazon ASIN ranks for, along with monthly search volume, ranking positions, ratings, pricing, badges (Best Seller / Amazon's Choice), and competitive metrics. Cursor-paginates Data provider results via numeric offset (up to 1,000 keywords per run).

💼 Use cases

• Finding every keyword one product already ranks for — hand it an asin and the run returns the full ranked keyword list, up to 1,000 per ASIN on the paid tier and 10 ASINs in a single run.
• Seeing where you sit in the SERP, not just that you rank — rankAbsolute, rankGroup, position and serpItemType separate organic from sponsored placement and tell you which side of the page you are on.
• Reading the competitive set on each term — every row carries the ranking item's title, url, asin, priceFrom / priceTo, currency, rating, ratingVotes, isBestSeller and isAmazonChoice, so a keyword's price and review context arrives with it.
• Paging past the first keyword batch — each row returns nextOffset and totalCount, so a second run with offset continues exactly where the first stopped instead of restarting the list.

✅ Who this is for

• Amazon PPC managers — who need the keyword footprint of a specific ASIN rather than a generic suggestion list.
• Marketplace SEO sellers and listing teams — looking for terms where a rival ranks and the positioning gap is still open.
• Competitive pricing and catalog analysts — comparing the price, rating and badge context of the SERP items they are losing to.
• Teams tracking a small portfolio — who can pass up to 10 ASINs in one run and page through each with offset.

❌ Who this is NOT for

• You need an Amazon marketplace outside the four supported ones — coverage is limited to the marketplaces listed in Marketplace Coverage (United States, Egypt, Saudi Arabia, United Arab Emirates), and each carries a fixed set of Amazon-supported languages. Other markets are rejected rather than approximated.
• You are pairing the United States marketplace with Arabic — US accepts English and Spanish only, and an unsupported pairing silently falls back to the marketplace's first supported language. The wrong language looks like a successful run, so check the echoed query in the output.
• You are on the free tier and expecting your limit to be honoured — free users are silently capped at 100 keywords per ASIN per run even if you ask for 500. The only signal is limitCapped: true in the SUMMARY record; the dataset rows themselves look normal.
• You need the complete keyword list in one run — the total keyword count per ASIN commonly runs into the thousands, so anything past 1,000 means running the offset chain by hand, and free-tier runs stop at 100 per ASIN per run with a 5-run daily ceiling.
• You need real sales or conversion data for the ASIN — searchVolume is keyword-level search demand, boughtPastMonth is an estimated unit count, and seResultsCount is a competing-results count. None of them are this ASIN's own revenue or conversion performance.

🚀 Quick start

1. Run with Example Input

{
  "asin": "B0C2JXSHSK",
  "marketplace": "United States",
  "language": "English",
  "limit": 100
}

Returns up to 100 ranked keywords for that ASIN on Amazon US. Free users are capped at 100 per ASIN per run — see Pricing & Limits below.

2. Export Your Results

• Open the run in Apify Console.
• Click the Dataset tab → Export → JSON / CSV / Excel.
• Or fetch the API: GET https://api.apify.com/v2/acts/<ACTOR_ID>/runs/<RUN_ID>/dataset/items

📥 Input parameters

Top-Level Structure

{
  "asin": "B0C2JXSHSK\nB08N5WRWNW",
  "marketplace": "United States",
  "language": "English",
  "limit": 100,
  "offset": 0,
  "ignore_synonyms": false
}

asin — Amazon ASINs

Required	Type	Default	Description
No	string (textarea)	B0C2JXSHSK (test ASIN)	One or more ASINs, separated by commas or newlines. Up to 10 per run.

Examples:

B0C2JXSHSK
B08N5WRWNW
B09G3HRMVB

marketplace — Amazon Marketplace

Required	Type	Default	Description
No	select	United States	Amazon marketplace. Currently only US is supported by the data provider API — other markets return Invalid Field: 'location_code'.

language — Result Language

Required	Type	Default	Description
No	select	English	Language for keyword data. Only English is currently wired up.

limit — Keyword Limit (per ASIN)

Required	Type	Default	Min	Max	Description
No	integer	100	1	1000 (paid tier) / 100 (free tier)	How many keywords to retrieve per ASIN. Free-tier users are silently capped at 100 per ASIN per run — see Pricing & Limits.

offset — Pagination Offset

Required	Type	Default	Description
No	integer	0	Skip the first N keywords. To paginate: first run returns up to limit keywords with nextOffset on each row. Second run sets offset to that value to get the next batch.

ignore_synonyms — Ignore Synonyms

Required	Type	Default	Description
No	boolean	false	If true, the data provider API skips highly similar keyword variants and returns only core keywords.

📤 Output

Keyword Object — one row per ranked keyword

Field	Type	Description
keyword	string	The search keyword the ASIN ranks for.
searchVolume	number	Monthly search volume.
keywordLastUpdated	string|null	ISO timestamp of last keyword data update.
serpItemType	string|null	amazon_serp (organic) or amazon_paid (sponsored).
serpItemTypes	string[]	All SERP types this keyword returns.
rankGroup	number	Ranking position group.
rankAbsolute	number	Absolute ranking position.
position	string|null	left or right placement.
domain	string	Always www.amazon.com for Amazon results.
title	string	SERP item title.
url	string	SERP item URL.
asin	string	The ASIN of the SERP item.
imageUrl	string|null	Product image URL.
priceFrom	number|null	Lowest price in the price range.
priceTo	number|null	Highest price (null for fixed-price items).
currency	string	Currency code, e.g. USD.
isBestSeller	boolean	Best Seller badge flag.
isAmazonChoice	boolean	Amazon's Choice badge flag.
rating	number	Product rating (0–5).
ratingMax	number	Maximum rating value (always 5).
ratingVotes	number	Total ratings count.
boughtPastMonth	number|null	Estimated units bought in the past month.
deliveryInfo	object|null	Delivery info (free shipping, Prime, etc).
specialOffers	string|null	Special offer text.
seResultsCount	number	Total competing results for this keyword on Amazon.
serpLastUpdated	string|null	Last SERP data update.
serpPreviousUpdated	string|null	Previous SERP data update.
checkUrl	string|null	The Amazon search URL that produced this row.
query	object	Echo of the input that produced this row (asin, marketplace, language, etc).
totalCount	number	Total keywords Data provider found for this ASIN.
nextOffset	number|null	Pass this into the next run's offset to fetch the next batch. null when exhausted.

Run Summary

Stored under the SUMMARY key in the default key-value store. The summary now includes a tier block so free vs. paid users can see exactly what gates applied to their run:

{
  "ok": true,
  "query": {
    "asins": ["B0C2JXSHSK"],
    "marketplace": "United States",
    "locationCode": 2840,
    "language": "English",
    "languageCode": "en",
    "limit": 100,
    "limitRequested": 500,
    "limitCapped": true,
    "offset": 0,
    "ignoreSynonyms": false
  },
  "tier": {
    "kind": "free",
    "rowsPerAsinCeiling": 100,
    "freeDailyRunLimit": 5,
    "freeDailyRunsUsed": 2
  },
  "perAsin": {
    "B0C2JXSHSK": { "totalCount": 5005, "collected": 100, "hasMore": true }
  },
  "result": { "totalCollected": 100, "rowsReturned": 100 },
  "errors": [],
  "apiRequests": 1,
  "completedAt": "2026-07-21T08:00:00.000Z"
}

limitCapped: true means the user-requested limit was higher than the per-tier ceiling and was silently lowered — see the tier block for the exact number. To unlock the full 1,000 per ASIN, switch on pay-per-event pricing in the Actor's Pricing tab.

⚙️ How it works

Each ASIN returns up to limit keywords (default 100, free tier ceiling 100, paid tier ceiling 1,000). To paginate:

Run 1: offset=0    → 100 keywords (1-100),    nextOffset on rows = 100
Run 2: offset=100  → 100 keywords (101-200),  nextOffset on rows = 200
Run 3: offset=200  → 100 keywords (201-300),  nextOffset on rows = 300
...

When nextOffset is null, the data provider has no more results for this ASIN.

For paid users who want more than 1,000 keywords:

Run 1: offset=0,    limit=1000 → 1000 keywords (1-1000),   nextOffset on rows = 1000
Run 2: offset=1000, limit=1000 → 1000 keywords (1001-2000), nextOffset on rows = 2000
...

Data provider cap: limit is capped at 1000 per request (paid tier only). The Amazon Labs endpoint does not impose a hard offset + limit ceiling (unlike some other DataForSEO endpoints) — verified up to offset=9900.

💰 Billing

the data provider DataForSEO Labs Amazon endpoint supports 4 marketplaces, each with a fixed list of Amazon-supported languages:

Marketplace	Location Code	Amazon-Supported Languages
United States	2840	English, Spanish
Egypt	2818	Arabic
Saudi Arabia	2682	Arabic
United Arab Emirates	2784	Arabic

Combining a marketplace with a non-supported language returns Invalid Field: 'language_code' (e.g. United States + Arabic). The Actor auto-falls-back to the marketplace's first Amazon-supported language when the user-supplied language is unsupported for the chosen marketplace.

If the data provider gains more locations, they'll be added to src/constants.js and the input schema in a single release.

The Actor uses Apify's Pay per event pricing model. There is no separate monthly subscription. Every gate is enforced in src/lib/billing.js:

	Free tier	Paid tier (pay-per-event on)
Runs per day	5 (KV-scoped counter, resets at UTC midnight)	Unlimited
Keywords per ASIN per run	100	1,000 (hard cap)
ASINs per run	10	10
Silent capping	limit > 100 → capped to 100 + limitCapped: true in SUMMARY	limit > 1000 → capped to 1000 + limitCapped: true in SUMMARY
tier.kind in SUMMARY	"free"	"paid"

How free-tier detection works

The Actor reads Apify's APIFY_USER_IS_PAYING environment variable, which is automatically set to 1 when the user has pay-per-event pricing turned on for the Actor, and 0 (or unset) otherwise. There is no manual toggle.

How capping works

When a free user submits limit higher than 100:

1. The Actor logs a warning at run start (visible in the run log).
2. The requested value is recorded in query.limitRequested.
3. The applied value is recorded in query.limit.
4. query.limitCapped is set to true in SUMMARY.

The dataset rows themselves are unchanged — only the count of returned rows is reduced.

How Pay per event works

Once you turn on pay-per-event pricing for the Actor (Apify Console → Actor → Pricing tab), every keyword row the Actor pushes to the dataset triggers one keyword-result event billed by Apify. The Actor never charges for runs that hit an error before producing rows.

❓ FAQ

Q: Why are all rows in my old runs empty/null? A: If you ran the previous version (v0.1.x), it read the wrong Data provider fields (items[i].keyword_info, items[i].serp_item) — those nested paths don't exist, so rows came out as null. v1.2 fixes the parser. Re-run the Actor to get real data.

Q: Why only 4 marketplaces? A: That's all the data provider DataForSEO Labs Amazon endpoint currently exposes (verified against /dataforseo_labs/locations_and_languages — Amazon's available_sources field only marks these 4 as Amazon-supported). The endpoint docs say the same: https://docs.dataforseo.com/v3/dataforseo_labs/amazon/ranked_keywords/live/

Q: Can I use Arabic in the United States marketplace? A: No. Each marketplace has a fixed set of Amazon-supported languages. United States only accepts English and Spanish. If you submit a non-supported pairing (e.g. United States + Arabic), the Actor falls back to the marketplace's first supported language (English in this case).

Q: Can I get more than 1000 keywords per ASIN? A: Yes — use offset pagination. Run 1 with offset=0, limit=1000, run 2 with offset=1000, limit=1000, etc. Paid tier only — free tier stops at 100 per ASIN per run.

Q: Why is my run returning only 100 rows even though I set limit=500? A: You're on the free tier. The Actor silently caps keywords-per-ASIN at 100 per run for free users. To retrieve up to 1,000 keywords per ASIN per run, open the Actor's Pricing tab in Apify Console and turn on pay-per-event billing — paid users are charged per row and have no keyword cap. Check the run SUMMARY for tier.kind and query.limitCapped to confirm.

Q: Why is my run failing with "Free tier limit reached" after only a few runs? A: Free tier is capped at 5 runs per day (the counter lives in the Actor's KV store and resets at UTC midnight). To lift the daily cap and the per-run keyword cap in one go, switch on pay-per-event billing for the Actor.

Q: How does ignore_synonyms work? A: It tells the data provider API to deduplicate highly similar keyword variants (e.g. "running shoes" vs "running shoe"). Useful for getting core keyword counts, not the long-tail.

📚 Resources

• Console run page: open the run for live logs + retry options.
• Email: sam.wang0420@gmail.com

MIT License — free to use and modify.

📜 Notes & caveats

Why Use This Actor

Problem	How This Actor Solves It
Need to know what keywords an ASIN ranks for?	Run the Actor with the ASIN — get the full list of ranked keywords in one shot.
Need more than 100 keywords?	Set limit up to 1,000 (paid tier, Data provider cap). To go beyond, run again with offset set to the previous run's _nextOffset.
Tracking multiple products?	Pass up to 10 ASINs in one run (comma or newline separated).
Need competitive context?	Each keyword row includes rank position, the SERP item's title/price/rating/badges, and the SERP URL for manual inspection.