{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Best Sellers Scraper: all 100 ranks, not 60",
    "description": "Scrape all 100 ranks of every Amazon Best Sellers and New Releases list, not the 60 a page-only scraper gets, on amazon.com and amazon.de. Subcategory tree, product page details, entries, rank changes and exits between runs. No browser.",
    "version": "0.1",
    "x-build-id": "LZsRFbcOJmlOUh3KO"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/alexmorain~amazon-bestsellers-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-alexmorain-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/alexmorain~amazon-bestsellers-scraper/runs": {
      "post": {
        "operationId": "runs-sync-alexmorain-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/alexmorain~amazon-bestsellers-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-alexmorain-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": "Ranking URLs",
            "type": "array",
            "description": "Amazon ranking pages, one per line: <code>https://www.amazon.com/gp/bestsellers/kitchen</code>, <code>https://www.amazon.com/Best-Sellers-Kitchen-Dining-Bakeware/zgbs/kitchen/289668</code>, <code>https://www.amazon.de/gp/new-releases/kitchen</code>. Best Sellers and New Releases pages on amazon.com and amazon.de. The list type and the marketplace are read from the URL; the page number is ignored (both pages of 50 are always read).",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "title": "Categories",
            "type": "array",
            "description": "Optional, instead of or next to the URLs. One per line: a department code as in the URL (<code>kitchen</code>, <code>electronics</code>), a department with a node (<code>kitchen/289668</code>), the name of a top department (<code>Kitchen &amp; Dining</code>) or <code>All departments</code> for the ranking of each of the 34 top departments (Amazon has no ranking for the whole store). They use the <b>List</b> and <b>Marketplace</b> below.",
            "items": {
              "type": "string"
            }
          },
          "listType": {
            "title": "List",
            "enum": [
              "bestsellers",
              "new-releases"
            ],
            "type": "string",
            "description": "Which ranking to read for the categories above. <b>Best Sellers</b>: the best-selling products, updated hourly. <b>New Releases</b>: the best-selling products among those listed recently. URLs carry their own list type.",
            "default": "bestsellers"
          },
          "marketplace": {
            "title": "Marketplace",
            "enum": [
              "com",
              "de"
            ],
            "type": "string",
            "description": "Amazon site for the categories above. URLs carry their own marketplace. On amazon.de the Actor sets a Berlin delivery postcode, without which Amazon hides about a third of the prices. amazon.fr, amazon.co.uk and amazon.co.jp are not offered: they answer with a JavaScript challenge that plain HTTP cannot pass.",
            "default": "com"
          },
          "includeSubcategories": {
            "title": "Include subcategories",
            "type": "boolean",
            "description": "Also read the ranking of every subcategory listed in the left column of the page, level by level, down to <b>Max depth</b> and up to <b>Max categories</b>. Each category appears once even when several parents link to it.",
            "default": false
          },
          "maxDepth": {
            "title": "Max depth",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "How many levels below your category to read. 1 reads the direct subcategories (Kitchen &amp; Dining gives 12 more rankings), 2 reads theirs too.",
            "default": 1
          },
          "maxCategories": {
            "title": "Max categories",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Most rankings read in the run, your own categories included. Each costs 4 requests and returns up to 100 ranks.",
            "default": 50
          },
          "maxItems": {
            "title": "Max ranks",
            "minimum": 1,
            "type": "integer",
            "description": "Total ranks returned by the run, across all categories. The run stops there.",
            "default": 1000
          },
          "includeProductDetails": {
            "title": "Include product page details",
            "type": "boolean",
            "description": "Open the product page of each rank and add brand, list price, seller, delivery, rating histogram, bullet points, description, specifications, variants, images, Amazon's AI review summary and more. Billed at the higher <i>detailed ranked product</i> price for each row whose page was read; a row whose page Amazon refused is returned without details at the plain price.",
            "default": false
          },
          "monitorMode": {
            "title": "Watch",
            "enum": [
              "off",
              "newEntries",
              "rankChanges"
            ],
            "type": "string",
            "description": "Remembers each ranking from one run to the next. <b>New entries only</b> returns the products that were never returned before. <b>Entries, rank changes and exits</b> also returns the products whose rank changed (with <code>previousRank</code> and <code>rankChange</code>, positive when the product climbed) and one <code>droppedOut</code> row for each product that left the ranking. Only the rows returned are billed; exit rows are free. The first run returns everything. Schedule it daily or hourly.",
            "default": "off"
          },
          "monitorName": {
            "title": "Monitor name (Watch)",
            "type": "string",
            "description": "Without a name, the memory belongs to each ranking. With a name, every run using that name shares it. The memory lives in your key-value store <code>amazon-bestsellers-monitor</code>."
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "If set, the Actor POSTs a small JSON summary to this URL at the end of the run, <b>only when at least one rank was returned or a product left a ranking</b>: <code>actor</code>, <code>runId</code>, <code>datasetId</code>, <code>ranks</code>, <code>droppedOut</code>, <code>monitorMode</code> and one line per category. Use the final URL: a redirect is not followed, except a 307 or 308. An unreachable webhook is logged and never fails the run. Stored encrypted."
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify datacenter proxy by default, which is enough for ranking pages. If Amazon refuses datacenter IPs, the Actor falls back to residential IPs at no extra charge to you.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}