{
  "data": {
    "id": "9zDFDJNJ0ejBKMzrw",
    "actId": "0FAIaQmKaKgbU4Ftg",
    "userId": "IYgBDiXtHOijAaUel",
    "startedAt": "2026-11-06T18:17:04.739Z",
    "finishedAt": "2026-11-06T18:17:40.079Z",
    "status": "SUCCEEDED",
    "meta": {
      "origin": "CLI"
    },
    "stats": {
      "durationMillis": 35203,
      "runTimeSecs": 35.203,
      "computeUnits": 0.039114444444444445,
      "imageSizeBytes": 3114809856
    },
    "options": {
      "useCache": true,
      "betaPackages": false,
      "memoryMbytes": 4096,
      "diskMbytes": 8192
    },
    "createdByOrganizationMemberUserId": "QYo53EZkJk0prePWY",
    "exitCode": 0,
    "inputSchema": "{\n  \"title\": \"Amazon Best Sellers & Rankings Scraper Input\",\n  \"description\": \"Scrape Amazon's Best Sellers, New Releases, Most Wished For, Most Gifted, or Movers & Shakers charts for one or more categories.\",\n  \"type\": \"object\",\n  \"schemaVersion\": 1,\n  \"properties\": {\n    \"chartType\": {\n      \"title\": \"Chart type\",\n      \"type\": \"string\",\n      \"description\": \"Which Amazon chart to scrape. A full chart URL pasted into `categoryUrls` overrides this with the URL's own chart type.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"bestSellers\",\n        \"newReleases\",\n        \"mostWishedFor\",\n        \"mostGifted\",\n        \"moversAndShakers\"\n      ],\n      \"enumTitles\": [\n        \"Best Sellers\",\n        \"New Releases\",\n        \"Most Wished For\",\n        \"Most Gifted\",\n        \"Movers & Shakers\"\n      ],\n      \"default\": \"bestSellers\",\n      \"prefill\": \"bestSellers\"\n    },\n    \"domain\": {\n      \"title\": \"Amazon domain\",\n      \"type\": \"string\",\n      \"description\": \"Which Amazon marketplace to scrape the chart from. A full chart URL pasted into `categoryUrls` overrides this with the URL's own marketplace.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"amazon.com\",\n        \"amazon.co.uk\",\n        \"amazon.de\",\n        \"amazon.fr\",\n        \"amazon.it\",\n        \"amazon.es\",\n        \"amazon.ca\",\n        \"amazon.com.au\",\n        \"amazon.co.jp\",\n        \"amazon.in\",\n        \"amazon.com.br\",\n        \"amazon.com.mx\",\n        \"amazon.nl\",\n        \"amazon.se\",\n        \"amazon.pl\",\n        \"amazon.com.tr\",\n        \"amazon.ae\",\n        \"amazon.sa\",\n        \"amazon.sg\",\n        \"amazon.eg\"\n      ],\n      \"enumTitles\": [\n        \"United States (amazon.com)\",\n        \"United Kingdom (amazon.co.uk)\",\n        \"Germany (amazon.de)\",\n        \"France (amazon.fr)\",\n        \"Italy (amazon.it)\",\n        \"Spain (amazon.es)\",\n        \"Canada (amazon.ca)\",\n        \"Australia (amazon.com.au)\",\n        \"Japan (amazon.co.jp)\",\n        \"India (amazon.in)\",\n        \"Brazil (amazon.com.br)\",\n        \"Mexico (amazon.com.mx)\",\n        \"Netherlands (amazon.nl)\",\n        \"Sweden (amazon.se)\",\n        \"Poland (amazon.pl)\",\n        \"Turkey (amazon.com.tr)\",\n        \"UAE (amazon.ae)\",\n        \"Saudi Arabia (amazon.sa)\",\n        \"Singapore (amazon.sg)\",\n        \"Egypt (amazon.eg)\"\n      ],\n      \"default\": \"amazon.com\",\n      \"prefill\": \"amazon.com\"\n    },\n    \"categoryUrls\": {\n      \"title\": \"Category URLs or slugs\",\n      \"type\": \"array\",\n      \"description\": \"Amazon category slugs (e.g. `electronics`, `electronics/172541`) or full chart URLs to scrape. A full chart URL supplies its own chart type and marketplace, e.g. `https://www.amazon.co.uk/gp/new-releases/electronics`.\",\n      \"editor\": \"stringList\",\n      \"default\": [\n        \"electronics\"\n      ],\n      \"prefill\": [\n        \"electronics\"\n      ]\n    },\n    \"categoryNodeIds\": {\n      \"title\": \"Category node IDs\",\n      \"type\": \"array\",\n      \"description\": \"Amazon browse-node IDs in `rootSlug/nodeId` form (e.g. `electronics/172541` for Headphones). Combined with `categoryUrls` if both are provided.\",\n      \"editor\": \"stringList\",\n      \"default\": [],\n      \"prefill\": []\n    },\n    \"maxDepth\": {\n      \"title\": \"Subcategory recursion depth\",\n      \"type\": \"integer\",\n      \"description\": \"When > 0, also walk each category's left-nav subcategory links this many levels deep, scraping each subcategory's own chart too. 0 = only the given categories.\",\n      \"minimum\": 0,\n      \"maximum\": 3,\n      \"default\": 0,\n      \"prefill\": 0\n    },\n    \"startPage\": {\n      \"title\": \"Start page\",\n      \"type\": \"integer\",\n      \"description\": \"First chart page to fetch (1 or 2). Pages are capped at 2 so a chart never exceeds the real top-100 boundary.\",\n      \"minimum\": 1,\n      \"maximum\": 2,\n      \"default\": 1,\n      \"prefill\": 1\n    },\n    \"maxPages\": {\n      \"title\": \"Max pages per category\",\n      \"type\": \"integer\",\n      \"description\": \"Maximum number of chart pages to fetch per category, starting at `startPage`. Capped at 2 (top 100).\",\n      \"minimum\": 1,\n      \"maximum\": 2,\n      \"default\": 2,\n      \"prefill\": 2\n    },\n    \"maxItemsPerCategory\": {\n      \"title\": \"Max items per category\",\n      \"type\": \"integer\",\n      \"description\": \"Hard cap on chart items emitted per category (across all its pages). Maximum 100; coverage fields still report the full listed-rank range.\",\n      \"minimum\": 1,\n      \"maximum\": 100,\n      \"default\": 100,\n      \"prefill\": 20\n    },\n    \"maxItems\": {\n      \"title\": \"Max total items\",\n      \"type\": \"integer\",\n      \"description\": \"Hard cap on total chart items emitted across all categories in this run.\",\n      \"minimum\": 1,\n      \"maximum\": 2000,\n      \"default\": 200,\n      \"prefill\": 20\n    },\n    \"includeProductDetails\": {\n      \"title\": \"Enrich with product detail page\",\n      \"type\": \"boolean\",\n      \"description\": \"For each chart item, also fetch its product detail page for list-price and in-stock data. Slower and bounded by `maxProductDetails`.\",\n      \"default\": false,\n      \"prefill\": false\n    },\n    \"maxProductDetails\": {\n      \"title\": \"Max product detail fetches\",\n      \"type\": \"integer\",\n      \"description\": \"Hard cap on how many chart items get product-detail enrichment when `includeProductDetails` is on.\",\n      \"minimum\": 1,\n      \"maximum\": 100,\n      \"default\": 10,\n      \"prefill\": 5\n    },\n    \"maxMissingDetailFetches\": {\n      \"title\": \"Max missing-detail product fetches\",\n      \"type\": \"integer\",\n      \"description\": \"Per-category cap on best-effort product-page fetches used to fill ranks the nextPage response did not cover. Set 0 to disable product-page fill.\",\n      \"minimum\": 0,\n      \"maximum\": 100,\n      \"default\": 50,\n      \"prefill\": 0\n    },\n    \"proxyConfiguration\": {\n      \"title\": \"Proxy configuration\",\n      \"type\": \"object\",\n      \"description\": \"Apify proxy used to fetch chart pages. Datacenter (AUTO) is used by default and works for most requests; the actor escalates to residential only after repeated blocks on a session.\",\n      \"editor\": \"proxy\",\n      \"prefill\": {\n        \"useApifyProxy\": true\n      },\n      \"default\": {\n        \"useApifyProxy\": true\n      }\n    }\n  },\n  \"required\": [\n    \"chartType\"\n  ]\n}",
    "readme": "# Amazon Best Sellers & Rankings Scraper\r\n\r\nScrape **Amazon's chart family** -- Best Sellers, New Releases, Most Wished For, Most Gifted, and Movers & Shakers -- for any category on any Amazon marketplace. The actor reads Amazon's own `data-client-recs-list` as the authoritative rank/ASIN axis, fills missing card details through the public `nextPage` XHR (and product pages as a fallback), and reports honest `ranksListed` / `withDetails` / `missingDetailRanks` coverage for every chart.\r\n\r\n## What this actor does\r\n\r\n- **Five chart types:** Best Sellers, New Releases, Most Wished For, Most Gifted, Movers & Shakers\r\n- **Authoritative rank axis:** parses Amazon's `data-client-recs-list` (50 listed ranks per page, even when only 30 cards are server-rendered) instead of renumbering whatever badges happen to render\r\n- **Top-100 bounded:** pages are capped at 2; ranks above 100 are ignored\r\n- **Missing-detail fill:** uses the page's own public `nextPage` XHR first, then product pages as a best-effort fallback; never invents a rank or ASIN\r\n- **Any category:** pass a category slug (`electronics`), a slug + browse-node ID (`electronics/172541`), or paste a full Amazon chart URL. A pasted URL supplies its own chart type and marketplace.\r\n- **Category-tree recursion:** optionally walk each category's subcategory links up to a configurable depth, scraping every subcategory's own chart too\r\n- **20 Amazon marketplaces:** amazon.com, .co.uk, .de, .fr, .it, .es, .ca, .com.au, .co.jp, .in, .com.br, .com.mx, .nl, .se, .pl, .com.tr, .ae, .sa, .sg, .eg\r\n- **Truthful diagnostics:** distinguishes a blocked/continue-shopping checkpoint, an invalid localized category, an empty-at-source chart, and partial coverage; every run writes a `runSummary` record\r\n- **Honest empty-chart handling:** a zero-item run is never silently reported as a clean success -- `emptyReason` and `coverageStatus` explain it\r\n- **Empty fields are omitted**\r\n\r\n## Output per chart item\r\n\r\n- `rank` -- position on the chart\r\n- `asin` -- Amazon Standard Identification Number\r\n- `title`, `url`, `image`\r\n- `price` -- `{value, currency, display}` (only emitted when Amazon shows an explicit price)\r\n- `stars`, `reviewsCount`\r\n- `badge` -- canonical product badge, e.g. `BestSeller`, `AmazonsChoice`, `OverallPick` (only when the card actually shows one)\r\n- `isPrime` -- `true` only when the card carries explicit Prime-icon/label evidence (omitted otherwise, never inferred)\r\n- `offersCount` -- real `\"N offers from\"` count when Amazon's card shows it\r\n- `listPrice` -- crossed-out/list price from the card or product page, when explicitly shown\r\n- `format` -- format/variant summary, e.g. `\"Paperback\"` or `\"4 formats available\"` (books/media charts only, when Amazon's card shows one)\r\n- `brand`, `byline` -- brand/store or author byline when the card (or product-page fallback) shows one\r\n- `chartType`, `category`, `categoryNodeId`, `categoryUrl`, `page`\r\n- `rankChangeDirection`, `rankChangeAmount` -- Movers & Shakers only, and only when Amazon's own rank-change marker is present\r\n- `inStock` -- only with explicit product-page evidence (never inferred)\r\n- `detailSource` -- `chart`, `nextPage`, `productPage`, or `missing`; shows where the item's details came from\r\n- `childCategories` -- sibling/child category links `{name, path, url, nodeId}` from the chart page's own category nav, when present\r\n- `recordType: \"chartItem\"`, `scrapedAt`\r\n\r\n## Output: chart metadata + coverage record\r\n\r\nEmitted once per category, including successful charts:\r\n\r\n- `chartType`, `category`, `categoryNodeId`, `categoryUrl`, `domain`\r\n- `extractedItemCount` / `itemsEmitted` -- how many chart-item records were actually emitted\r\n- `ranksListed` -- authoritative ranks Amazon listed (<= 100)\r\n- `withDetails` -- listed ranks with real card/product details\r\n- `missingDetailRanks` -- listed ranks whose details could not be filled\r\n- `coverageStatus` -- `complete`, `partial`, `empty`, `blocked`, `invalid_category`, or `unknown`\r\n- `emptyReason` -- e.g. `empty_at_source`, `blocked_continue_shopping`, `invalid_localized_category`, `partial_details`, `partial_pages`, `partial_categories`\r\n- `truncatedByLimit` -- true when a user limit emitted fewer items than the listed ranks\r\n- `pagesFetched`, `message`\r\n- `recordType: \"chartMetadata\"`, `scrapedAt`\r\n\r\n## Output: run summary\r\n\r\nOne `runSummary` record per run aggregates `itemsEmitted`, `ranksListed`, `withDetails`, `missingDetailRanks`, `coverageStatus`, `emptyReason`, and per-category diagnostics. A zero-item run always sets an explicit status message; blocked/invalid/partial/unknown zero-item runs also fail the Actor instead of silently succeeding. A genuinely empty-at-source chart is reported as `empty_at_source` rather than a generic success.\r\n\r\n## Input\r\n\r\n| Field | Type | Default | Description |\r\n|---|---|---|---|\r\n| `chartType` | string | `bestSellers` | `bestSellers` / `newReleases` / `mostWishedFor` / `mostGifted` / `moversAndShakers` |\r\n| `domain` | string | `amazon.com` | Which Amazon marketplace to scrape |\r\n| `categoryUrls` | array | `[\"electronics\"]` | Category slugs, slug/nodeId pairs, or full chart URLs (a full URL supplies its own chart type + marketplace) |\r\n| `categoryNodeIds` | array | `[]` | Additional `rootSlug/nodeId` entries |\r\n| `maxDepth` | int | `0` | Subcategory recursion depth (0-3) |\r\n| `startPage` | int | `1` | First chart page to fetch (1-2) |\r\n| `maxPages` | int | `2` | Max chart pages per category (1-2; top-100 cap) |\r\n| `maxItemsPerCategory` | int | `100` | Hard cap on emitted items per category (max 100); coverage still reports all listed ranks |\r\n| `maxItems` | int | `200` | Hard cap on total items across the run |\r\n| `includeProductDetails` | boolean | `false` | Enrich items with list price and stock from product pages |\r\n| `maxProductDetails` | int | `10` | Cap on product-detail fetches when enabled |\r\n| `maxMissingDetailFetches` | int | `50` | Per-category cap on best-effort product-page fill; `0` disables it |\r\n| `proxyConfiguration` | object | AUTO | Apify proxy (AUTO datacenter by default, RESIDENTIAL fallback on failure) |\r\n\r\n### Example: Best Sellers in Electronics\r\n\r\n```json\r\n{\r\n  \"chartType\": \"bestSellers\",\r\n  \"categoryUrls\": [\"electronics\"],\r\n  \"maxItems\": 50\r\n}\r\n```\r\n\r\n### Example: New Releases for a specific subcategory (Headphones)\r\n\r\n```json\r\n{\r\n  \"chartType\": \"newReleases\",\r\n  \"categoryUrls\": [\"electronics/172541\"],\r\n  \"maxItems\": 30\r\n}\r\n```\r\n\r\n### Example: recurse a whole department's subcategories\r\n\r\n```json\r\n{\r\n  \"chartType\": \"bestSellers\",\r\n  \"categoryUrls\": [\"electronics\"],\r\n  \"maxDepth\": 2,\r\n  \"maxItemsPerCategory\": 20,\r\n  \"maxItems\": 500\r\n}\r\n```\r\n\r\n### Example: paste a full chart URL (marketplace + chart type come from the URL)\r\n\r\n```json\r\n{\r\n  \"categoryUrls\": [\"https://www.amazon.co.uk/gp/new-releases/electronics\"],\r\n  \"maxItems\": 50\r\n}\r\n```\r\n\r\n### Example: Movers & Shakers on the UK marketplace\r\n\r\n```json\r\n{\r\n  \"chartType\": \"moversAndShakers\",\r\n  \"domain\": \"amazon.co.uk\",\r\n  \"categoryUrls\": [\"electronics\"]\r\n}\r\n```\r\n\r\n## Use cases\r\n\r\n- **Market research** -- track which products dominate a category's chart over time\r\n- **Competitive intelligence** -- monitor a competitor's category ranking and pricing\r\n- **Trend spotting** -- New Releases and Movers & Shakers surface emerging products before they're widely known\r\n- **Gift-guide content** -- Most Gifted and Most Wished For power seasonal buying-guide content\r\n- **Category research** -- recurse a department's full subcategory tree to map an entire vertical's top products\r\n\r\n## FAQ\r\n\r\n**Is this actor affiliated with Amazon?**\r\nNo. This is a third-party actor that scrapes Amazon's public chart pages.\r\n\r\n**Does the actor guarantee \"Top 100\" for every category?**\r\nNo. It parses the ranks Amazon actually lists, capped at rank 100 and at 2 chart pages, then reports `ranksListed`, `withDetails`, and `missingDetailRanks` honestly. Amazon itself sometimes lists fewer than 100 ranks (a live amazon.com electronics probe listed 50 on page 1 and only 51-99 on page 2); the actor never fabricates the missing rank 100 or renumbers around gaps. Check the chart-metadata and run-summary records before claiming a full top 100.\r\n\r\n**Why is Movers & Shakers sometimes empty?**\r\nAmazon itself frequently has no movers-and-shakers data for a given category at a given time -- this is a real, documented state on Amazon's own site, not a scraper bug. The actor emits `emptyReason: \"empty_at_source\"` plus a chart-metadata record instead of guessing or substituting unrelated recommended products.\r\n\r\n**What do the diagnostic statuses mean?**\r\n`blocked_continue_shopping` means Amazon served its \"Continue shopping\" checkpoint (a soft block), not an empty chart. `invalid_localized_category` means the chart URL/category could not be resolved on that marketplace (e.g. a page title ending in \"in undefined\"). `partial_details` means some listed ranks could not be filled from the chart cards, nextPage XHR, or product pages. `partial_page` / `layout_unknown` mean the page loaded but did not match a known chart layout.\r\n\r\n**Why do some items have no `price` or `rating`?**\r\nAmazon only shows these when they exist on the chart card. The actor never fabricates a price or rating -- if the field is missing, it's omitted from the record entirely.\r\n\r\n**How is `rank` different from position across separate runs?**\r\n`rank` reflects Amazon's own displayed chart position at scrape time. The actor holds no state between runs, so `rankChangeDirection`/`rankChangeAmount` (Movers & Shakers only) are populated strictly from Amazon's own rank-change marker on the page, never inferred by comparing separate runs.\r\n\r\n**Does the actor need a proxy?**\r\nNo -- it uses Apify's free AUTO (datacenter) proxy by default, which works for the large majority of requests. If a session gets repeatedly blocked, the actor automatically escalates to a residential proxy session as a fallback.\r\n\r\n**Can I scrape a whole department's subcategories in one run?**\r\nYes -- set `maxDepth` to 1-3 and the actor walks each category's subcategory links (visible in Amazon's own left-nav) that many levels deep, scraping each subcategory's own chart.\r\n",
    "actorDefinition": {
      "actorSpecification": 1,
      "name": "amazon-best-sellers-and-rankings-scraper",
      "title": "Amazon Best Sellers & Rankings Scraper",
      "description": "Scrape Amazon's Best Sellers, New Releases, Most Wished For, Most Gifted and Movers & Shakers charts. Get rank, ASIN, title, price, rating and category for every product on a chart, with optional deeper category coverage.",
      "version": "1.0",
      "buildTag": "latest",
      "dockerfile": "./Dockerfile",
      "readme": "# Amazon Best Sellers & Rankings Scraper\r\n\r\nScrape **Amazon's chart family** -- Best Sellers, New Releases, Most Wished For, Most Gifted, and Movers & Shakers -- for any category on any Amazon marketplace. The actor reads Amazon's own `data-client-recs-list` as the authoritative rank/ASIN axis, fills missing card details through the public `nextPage` XHR (and product pages as a fallback), and reports honest `ranksListed` / `withDetails` / `missingDetailRanks` coverage for every chart.\r\n\r\n## What this actor does\r\n\r\n- **Five chart types:** Best Sellers, New Releases, Most Wished For, Most Gifted, Movers & Shakers\r\n- **Authoritative rank axis:** parses Amazon's `data-client-recs-list` (50 listed ranks per page, even when only 30 cards are server-rendered) instead of renumbering whatever badges happen to render\r\n- **Top-100 bounded:** pages are capped at 2; ranks above 100 are ignored\r\n- **Missing-detail fill:** uses the page's own public `nextPage` XHR first, then product pages as a best-effort fallback; never invents a rank or ASIN\r\n- **Any category:** pass a category slug (`electronics`), a slug + browse-node ID (`electronics/172541`), or paste a full Amazon chart URL. A pasted URL supplies its own chart type and marketplace.\r\n- **Category-tree recursion:** optionally walk each category's subcategory links up to a configurable depth, scraping every subcategory's own chart too\r\n- **20 Amazon marketplaces:** amazon.com, .co.uk, .de, .fr, .it, .es, .ca, .com.au, .co.jp, .in, .com.br, .com.mx, .nl, .se, .pl, .com.tr, .ae, .sa, .sg, .eg\r\n- **Truthful diagnostics:** distinguishes a blocked/continue-shopping checkpoint, an invalid localized category, an empty-at-source chart, and partial coverage; every run writes a `runSummary` record\r\n- **Honest empty-chart handling:** a zero-item run is never silently reported as a clean success -- `emptyReason` and `coverageStatus` explain it\r\n- **Empty fields are omitted**\r\n\r\n## Output per chart item\r\n\r\n- `rank` -- position on the chart\r\n- `asin` -- Amazon Standard Identification Number\r\n- `title`, `url`, `image`\r\n- `price` -- `{value, currency, display}` (only emitted when Amazon shows an explicit price)\r\n- `stars`, `reviewsCount`\r\n- `badge` -- canonical product badge, e.g. `BestSeller`, `AmazonsChoice`, `OverallPick` (only when the card actually shows one)\r\n- `isPrime` -- `true` only when the card carries explicit Prime-icon/label evidence (omitted otherwise, never inferred)\r\n- `offersCount` -- real `\"N offers from\"` count when Amazon's card shows it\r\n- `listPrice` -- crossed-out/list price from the card or product page, when explicitly shown\r\n- `format` -- format/variant summary, e.g. `\"Paperback\"` or `\"4 formats available\"` (books/media charts only, when Amazon's card shows one)\r\n- `brand`, `byline` -- brand/store or author byline when the card (or product-page fallback) shows one\r\n- `chartType`, `category`, `categoryNodeId`, `categoryUrl`, `page`\r\n- `rankChangeDirection`, `rankChangeAmount` -- Movers & Shakers only, and only when Amazon's own rank-change marker is present\r\n- `inStock` -- only with explicit product-page evidence (never inferred)\r\n- `detailSource` -- `chart`, `nextPage`, `productPage`, or `missing`; shows where the item's details came from\r\n- `childCategories` -- sibling/child category links `{name, path, url, nodeId}` from the chart page's own category nav, when present\r\n- `recordType: \"chartItem\"`, `scrapedAt`\r\n\r\n## Output: chart metadata + coverage record\r\n\r\nEmitted once per category, including successful charts:\r\n\r\n- `chartType`, `category`, `categoryNodeId`, `categoryUrl`, `domain`\r\n- `extractedItemCount` / `itemsEmitted` -- how many chart-item records were actually emitted\r\n- `ranksListed` -- authoritative ranks Amazon listed (<= 100)\r\n- `withDetails` -- listed ranks with real card/product details\r\n- `missingDetailRanks` -- listed ranks whose details could not be filled\r\n- `coverageStatus` -- `complete`, `partial`, `empty`, `blocked`, `invalid_category`, or `unknown`\r\n- `emptyReason` -- e.g. `empty_at_source`, `blocked_continue_shopping`, `invalid_localized_category`, `partial_details`, `partial_pages`, `partial_categories`\r\n- `truncatedByLimit` -- true when a user limit emitted fewer items than the listed ranks\r\n- `pagesFetched`, `message`\r\n- `recordType: \"chartMetadata\"`, `scrapedAt`\r\n\r\n## Output: run summary\r\n\r\nOne `runSummary` record per run aggregates `itemsEmitted`, `ranksListed`, `withDetails`, `missingDetailRanks`, `coverageStatus`, `emptyReason`, and per-category diagnostics. A zero-item run always sets an explicit status message; blocked/invalid/partial/unknown zero-item runs also fail the Actor instead of silently succeeding. A genuinely empty-at-source chart is reported as `empty_at_source` rather than a generic success.\r\n\r\n## Input\r\n\r\n| Field | Type | Default | Description |\r\n|---|---|---|---|\r\n| `chartType` | string | `bestSellers` | `bestSellers` / `newReleases` / `mostWishedFor` / `mostGifted` / `moversAndShakers` |\r\n| `domain` | string | `amazon.com` | Which Amazon marketplace to scrape |\r\n| `categoryUrls` | array | `[\"electronics\"]` | Category slugs, slug/nodeId pairs, or full chart URLs (a full URL supplies its own chart type + marketplace) |\r\n| `categoryNodeIds` | array | `[]` | Additional `rootSlug/nodeId` entries |\r\n| `maxDepth` | int | `0` | Subcategory recursion depth (0-3) |\r\n| `startPage` | int | `1` | First chart page to fetch (1-2) |\r\n| `maxPages` | int | `2` | Max chart pages per category (1-2; top-100 cap) |\r\n| `maxItemsPerCategory` | int | `100` | Hard cap on emitted items per category (max 100); coverage still reports all listed ranks |\r\n| `maxItems` | int | `200` | Hard cap on total items across the run |\r\n| `includeProductDetails` | boolean | `false` | Enrich items with list price and stock from product pages |\r\n| `maxProductDetails` | int | `10` | Cap on product-detail fetches when enabled |\r\n| `maxMissingDetailFetches` | int | `50` | Per-category cap on best-effort product-page fill; `0` disables it |\r\n| `proxyConfiguration` | object | AUTO | Apify proxy (AUTO datacenter by default, RESIDENTIAL fallback on failure) |\r\n\r\n### Example: Best Sellers in Electronics\r\n\r\n```json\r\n{\r\n  \"chartType\": \"bestSellers\",\r\n  \"categoryUrls\": [\"electronics\"],\r\n  \"maxItems\": 50\r\n}\r\n```\r\n\r\n### Example: New Releases for a specific subcategory (Headphones)\r\n\r\n```json\r\n{\r\n  \"chartType\": \"newReleases\",\r\n  \"categoryUrls\": [\"electronics/172541\"],\r\n  \"maxItems\": 30\r\n}\r\n```\r\n\r\n### Example: recurse a whole department's subcategories\r\n\r\n```json\r\n{\r\n  \"chartType\": \"bestSellers\",\r\n  \"categoryUrls\": [\"electronics\"],\r\n  \"maxDepth\": 2,\r\n  \"maxItemsPerCategory\": 20,\r\n  \"maxItems\": 500\r\n}\r\n```\r\n\r\n### Example: paste a full chart URL (marketplace + chart type come from the URL)\r\n\r\n```json\r\n{\r\n  \"categoryUrls\": [\"https://www.amazon.co.uk/gp/new-releases/electronics\"],\r\n  \"maxItems\": 50\r\n}\r\n```\r\n\r\n### Example: Movers & Shakers on the UK marketplace\r\n\r\n```json\r\n{\r\n  \"chartType\": \"moversAndShakers\",\r\n  \"domain\": \"amazon.co.uk\",\r\n  \"categoryUrls\": [\"electronics\"]\r\n}\r\n```\r\n\r\n## Use cases\r\n\r\n- **Market research** -- track which products dominate a category's chart over time\r\n- **Competitive intelligence** -- monitor a competitor's category ranking and pricing\r\n- **Trend spotting** -- New Releases and Movers & Shakers surface emerging products before they're widely known\r\n- **Gift-guide content** -- Most Gifted and Most Wished For power seasonal buying-guide content\r\n- **Category research** -- recurse a department's full subcategory tree to map an entire vertical's top products\r\n\r\n## FAQ\r\n\r\n**Is this actor affiliated with Amazon?**\r\nNo. This is a third-party actor that scrapes Amazon's public chart pages.\r\n\r\n**Does the actor guarantee \"Top 100\" for every category?**\r\nNo. It parses the ranks Amazon actually lists, capped at rank 100 and at 2 chart pages, then reports `ranksListed`, `withDetails`, and `missingDetailRanks` honestly. Amazon itself sometimes lists fewer than 100 ranks (a live amazon.com electronics probe listed 50 on page 1 and only 51-99 on page 2); the actor never fabricates the missing rank 100 or renumbers around gaps. Check the chart-metadata and run-summary records before claiming a full top 100.\r\n\r\n**Why is Movers & Shakers sometimes empty?**\r\nAmazon itself frequently has no movers-and-shakers data for a given category at a given time -- this is a real, documented state on Amazon's own site, not a scraper bug. The actor emits `emptyReason: \"empty_at_source\"` plus a chart-metadata record instead of guessing or substituting unrelated recommended products.\r\n\r\n**What do the diagnostic statuses mean?**\r\n`blocked_continue_shopping` means Amazon served its \"Continue shopping\" checkpoint (a soft block), not an empty chart. `invalid_localized_category` means the chart URL/category could not be resolved on that marketplace (e.g. a page title ending in \"in undefined\"). `partial_details` means some listed ranks could not be filled from the chart cards, nextPage XHR, or product pages. `partial_page` / `layout_unknown` mean the page loaded but did not match a known chart layout.\r\n\r\n**Why do some items have no `price` or `rating`?**\r\nAmazon only shows these when they exist on the chart card. The actor never fabricates a price or rating -- if the field is missing, it's omitted from the record entirely.\r\n\r\n**How is `rank` different from position across separate runs?**\r\n`rank` reflects Amazon's own displayed chart position at scrape time. The actor holds no state between runs, so `rankChangeDirection`/`rankChangeAmount` (Movers & Shakers only) are populated strictly from Amazon's own rank-change marker on the page, never inferred by comparing separate runs.\r\n\r\n**Does the actor need a proxy?**\r\nNo -- it uses Apify's free AUTO (datacenter) proxy by default, which works for the large majority of requests. If a session gets repeatedly blocked, the actor automatically escalates to a residential proxy session as a fallback.\r\n\r\n**Can I scrape a whole department's subcategories in one run?**\r\nYes -- set `maxDepth` to 1-3 and the actor walks each category's subcategory links (visible in Amazon's own left-nav) that many levels deep, scraping each subcategory's own chart.\r\n",
      "input": {
        "title": "Amazon Best Sellers & Rankings Scraper Input",
        "description": "Scrape Amazon's Best Sellers, New Releases, Most Wished For, Most Gifted, or Movers & Shakers charts for one or more categories.",
        "type": "object",
        "schemaVersion": 1,
        "properties": {
          "chartType": {
            "title": "Chart type",
            "type": "string",
            "description": "Which Amazon chart to scrape. A full chart URL pasted into `categoryUrls` overrides this with the URL's own chart type.",
            "editor": "select",
            "enum": [
              "bestSellers",
              "newReleases",
              "mostWishedFor",
              "mostGifted",
              "moversAndShakers"
            ],
            "enumTitles": [
              "Best Sellers",
              "New Releases",
              "Most Wished For",
              "Most Gifted",
              "Movers & Shakers"
            ],
            "default": "bestSellers",
            "prefill": "bestSellers"
          },
          "domain": {
            "title": "Amazon domain",
            "type": "string",
            "description": "Which Amazon marketplace to scrape the chart from. A full chart URL pasted into `categoryUrls` overrides this with the URL's own marketplace.",
            "editor": "select",
            "enum": [
              "amazon.com",
              "amazon.co.uk",
              "amazon.de",
              "amazon.fr",
              "amazon.it",
              "amazon.es",
              "amazon.ca",
              "amazon.com.au",
              "amazon.co.jp",
              "amazon.in",
              "amazon.com.br",
              "amazon.com.mx",
              "amazon.nl",
              "amazon.se",
              "amazon.pl",
              "amazon.com.tr",
              "amazon.ae",
              "amazon.sa",
              "amazon.sg",
              "amazon.eg"
            ],
            "enumTitles": [
              "United States (amazon.com)",
              "United Kingdom (amazon.co.uk)",
              "Germany (amazon.de)",
              "France (amazon.fr)",
              "Italy (amazon.it)",
              "Spain (amazon.es)",
              "Canada (amazon.ca)",
              "Australia (amazon.com.au)",
              "Japan (amazon.co.jp)",
              "India (amazon.in)",
              "Brazil (amazon.com.br)",
              "Mexico (amazon.com.mx)",
              "Netherlands (amazon.nl)",
              "Sweden (amazon.se)",
              "Poland (amazon.pl)",
              "Turkey (amazon.com.tr)",
              "UAE (amazon.ae)",
              "Saudi Arabia (amazon.sa)",
              "Singapore (amazon.sg)",
              "Egypt (amazon.eg)"
            ],
            "default": "amazon.com",
            "prefill": "amazon.com"
          },
          "categoryUrls": {
            "title": "Category URLs or slugs",
            "type": "array",
            "description": "Amazon category slugs (e.g. `electronics`, `electronics/172541`) or full chart URLs to scrape. A full chart URL supplies its own chart type and marketplace, e.g. `https://www.amazon.co.uk/gp/new-releases/electronics`.",
            "editor": "stringList",
            "default": [
              "electronics"
            ],
            "prefill": [
              "electronics"
            ]
          },
          "categoryNodeIds": {
            "title": "Category node IDs",
            "type": "array",
            "description": "Amazon browse-node IDs in `rootSlug/nodeId` form (e.g. `electronics/172541` for Headphones). Combined with `categoryUrls` if both are provided.",
            "editor": "stringList",
            "default": [],
            "prefill": []
          },
          "maxDepth": {
            "title": "Subcategory recursion depth",
            "type": "integer",
            "description": "When > 0, also walk each category's left-nav subcategory links this many levels deep, scraping each subcategory's own chart too. 0 = only the given categories.",
            "minimum": 0,
            "maximum": 3,
            "default": 0,
            "prefill": 0
          },
          "startPage": {
            "title": "Start page",
            "type": "integer",
            "description": "First chart page to fetch (1 or 2). Pages are capped at 2 so a chart never exceeds the real top-100 boundary.",
            "minimum": 1,
            "maximum": 2,
            "default": 1,
            "prefill": 1
          },
          "maxPages": {
            "title": "Max pages per category",
            "type": "integer",
            "description": "Maximum number of chart pages to fetch per category, starting at `startPage`. Capped at 2 (top 100).",
            "minimum": 1,
            "maximum": 2,
            "default": 2,
            "prefill": 2
          },
          "maxItemsPerCategory": {
            "title": "Max items per category",
            "type": "integer",
            "description": "Hard cap on chart items emitted per category (across all its pages). Maximum 100; coverage fields still report the full listed-rank range.",
            "minimum": 1,
            "maximum": 100,
            "default": 100,
            "prefill": 20
          },
          "maxItems": {
            "title": "Max total items",
            "type": "integer",
            "description": "Hard cap on total chart items emitted across all categories in this run.",
            "minimum": 1,
            "maximum": 2000,
            "default": 200,
            "prefill": 20
          },
          "includeProductDetails": {
            "title": "Enrich with product detail page",
            "type": "boolean",
            "description": "For each chart item, also fetch its product detail page for list-price and in-stock data. Slower and bounded by `maxProductDetails`.",
            "default": false,
            "prefill": false
          },
          "maxProductDetails": {
            "title": "Max product detail fetches",
            "type": "integer",
            "description": "Hard cap on how many chart items get product-detail enrichment when `includeProductDetails` is on.",
            "minimum": 1,
            "maximum": 100,
            "default": 10,
            "prefill": 5
          },
          "maxMissingDetailFetches": {
            "title": "Max missing-detail product fetches",
            "type": "integer",
            "description": "Per-category cap on best-effort product-page fetches used to fill ranks the nextPage response did not cover. Set 0 to disable product-page fill.",
            "minimum": 0,
            "maximum": 100,
            "default": 50,
            "prefill": 0
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify proxy used to fetch chart pages. Datacenter (AUTO) is used by default and works for most requests; the actor escalates to residential only after repeated blocks on a session.",
            "editor": "proxy",
            "prefill": {
              "useApifyProxy": true
            },
            "default": {
              "useApifyProxy": true
            }
          }
        },
        "required": [
          "chartType"
        ]
      },
      "output": {
        "actorOutputSchemaVersion": 1,
        "title": "Amazon Best Sellers & Rankings Scraper Output",
        "description": "Ranked chart items from Amazon's Best Sellers, New Releases, Most Wished For, Most Gifted, and Movers & Shakers pages -- authoritative rank/ASIN axis, details, coverage, and truthful run diagnostics.",
        "properties": {
          "chartItems": {
            "type": "string",
            "title": "Amazon chart items",
            "description": "Dataset containing chart items plus per-chart coverage/diagnostic metadata records.",
            "template": "{{links.apiDefaultDatasetUrl}}/items"
          },
          "runSummary": {
            "type": "string",
            "title": "Run summary and coverage",
            "description": "The same dataset also contains one runSummary record with ranksListed/withDetails/missingDetailRanks, coverageStatus, and emptyReason.",
            "template": "{{links.apiDefaultDatasetUrl}}/items?format=json"
          }
        }
      },
      "defaultMemoryMbytes": 2048,
      "minMemoryMbytes": 2048,
      "storages": {
        "dataset": {
          "actorSpecification": 1,
          "views": {
            "overview": {
              "title": "Chart items",
              "transformation": {
                "fields": [
                  "rank",
                  "asin",
                  "title",
                  "brand",
                  "byline",
                  "format",
                  "chartType",
                  "category",
                  "price",
                  "listPrice",
                  "offersCount",
                  "stars",
                  "reviewsCount",
                  "badge",
                  "isPrime",
                  "url",
                  "detailSource"
                ]
              },
              "display": {
                "component": "table",
                "properties": {}
              }
            },
            "coverage": {
              "title": "Coverage & diagnostics",
              "transformation": {
                "fields": [
                  "recordType",
                  "chartType",
                  "category",
                  "categoryUrl",
                  "ranksListed",
                  "withDetails",
                  "missingDetailRanks",
                  "itemsEmitted",
                  "coverageStatus",
                  "emptyReason",
                  "truncatedByLimit",
                  "pagesFetched",
                  "message"
                ]
              },
              "display": {
                "component": "table",
                "properties": {}
              }
            }
          }
        }
      },
      "environmentVariables": {}
    },
    "buildNumber": "1.0.2",
    "imageDigest": "2923fc84d453a86a15c0976dc4230e4f88229372c83ec86bd5f76813d4a67ad3",
    "actVersion": {
      "sourceType": "SOURCE_FILES",
      "buildTag": "latest",
      "versionNumber": "1.0"
    },
    "usage": {
      "ACTOR_COMPUTE_UNITS": 0.039114444444444445
    }
  }
}