{ "openapi": "3.0.1", "info": { "title": "Amazon Bestsellers Scraper", "description": "Scrape Amazon Best Sellers, New Releases, Movers & Shakers, Most Wished For and Gift Ideas rankings by category across 10 marketplaces. Returns ranked products with rank, ASIN, title, price, rating, review count, Prime status and image. HTTP-only, MCP-ready, no auth required.", "version": "0.1", "x-build-id": "dF44ryfrAZJ1bLV6c" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~amazon-bestsellers-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-amazon-bestsellers-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/khadinakbar~amazon-bestsellers-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-amazon-bestsellers-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/khadinakbar~amazon-bestsellers-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-amazon-bestsellers-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "startUrls": { "title": "Amazon chart URLs", "type": "array", "description": "Amazon ranking-chart URLs to scrape — Best Sellers, New Releases, Most Wished For, or Gift Ideas pages (e.g. https://www.amazon.com/gp/bestsellers/electronics). Paste any category or subcategory chart URL from any of the 10 supported marketplaces; the chart type and marketplace are auto-detected from each URL. Leave empty to use the Chart type + Marketplace fields below instead. This is NOT a single product (/dp/) or search (/s?k=) URL — for product detail use the amazon-product-intelligence actor.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "chartType": { "title": "Chart type", "enum": [ "bestsellers", "new-releases", "most-wished-for", "gift-ideas" ], "type": "string", "description": "Which Amazon ranking chart to scrape when you do not paste explicit Start URLs. 'bestsellers' = top 100 by sales; 'new-releases' = trending new products; 'most-wished-for' = most added to wish lists; 'gift-ideas' = most gifted. Defaults to bestsellers. Ignored when Start URLs are provided (the type is auto-detected from each URL).", "default": "bestsellers" }, "marketplace": { "title": "Marketplace", "enum": [ "US", "UK", "DE", "FR", "IT", "ES", "CA", "JP", "IN", "AU" ], "type": "string", "description": "Amazon marketplace (country) to scrape when using Chart type instead of Start URLs. Selects the domain and a geo-matched residential proxy (e.g. 'US' uses amazon.com via a US IP). One of US, UK, DE, FR, IT, ES, CA, JP, IN, AU. Defaults to US. Ignored when Start URLs are provided (the domain is read from each URL).", "default": "US" }, "categorySlug": { "title": "Category (optional)", "type": "string", "description": "Optional Amazon category slug appended to the chart when using Chart type (e.g. 'books', 'kitchen', 'toys-and-games', 'beauty'). Slugs come from that marketplace's own bestseller URLs — most are shared, but some differ by country (e.g. Electronics is 'electronics' on amazon.com but a localized node on amazon.de). Leave empty for a cross-department sample of the top ~30 products; specify a category to get the full ranked top 100. Ignored when Start URLs are provided.", "default": "" }, "maxItemsPerCategory": { "title": "Max products per chart", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of ranked products to return per chart/category page. Amazon publishes at most 100 products per chart (two pages of 50), so values above 100 are capped at 100. Defaults to 100. Lower it (for example 20) to cut cost and runtime when you only need the very top of each list.", "default": 100 }, "includeSubcategories": { "title": "Crawl subcategories", "type": "boolean", "description": "When enabled, also scrapes the immediate subcategory charts linked in the left-hand navigation of each start page (one level deep, same chart type). This greatly increases result count and cost — a department such as Electronics has 20-40 subcategories. Defaults to false (scrape only the exact pages you provide). Each subcategory is still capped by Max products per chart.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings. Amazon blocks datacenter IPs on the first request, so this defaults to Apify residential proxies geo-matched to the marketplace — keep the default unless you have a specific reason to change it. You can pin a country or supply custom proxy URLs here.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }