# Amazon Search, Category & Seller Listings Extractor (`dataspryva/amazon-search-category-and-seller-listings`) Actor

Get Amazon products from search results, categories, seller storefronts, or ASIN lookups across 20+ marketplaces, with price, rating, badges, deals, and delivery details.

- **URL**: https://apify.com/dataspryva/amazon-search-category-and-seller-listings.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** E-commerce, Automation, Lead generation
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 66.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Amazon Search, Category & Seller Listings Extractor

Pull Amazon product listings from **keyword search, category/search URLs, browse-node IDs, seller
storefronts, ASINs, and exact product URLs** in one run. Every record carries the listing card
data — price, brand, rating, badges, images, delivery hints, and organic/sponsored position — and
optional product-detail enrichment adds specifications, the full gallery, seller identity, rating
histogram, variants, and bestseller ranks. No login, cookies, or API key needed.

### What this actor does

- **Six additive input modes.** Combine `keywords`, `categoryUrls`, `categoryNodeIds`,
  `sellerIds`, `asins`, and `productUrls` in the same run; every source is processed and
  deduplicated by ASIN.
- **Exact product lookup.** ASIN and product-URL modes open `/dp/{ASIN}` directly. They never
  fall back to an Amazon keyword search, so a known product cannot turn into an unrelated result.
- **Real category listings.** Node IDs use Amazon's `/s?rh=n:{node}&fs=true` listing route, not
  the `/b?node=` merchandising landing page. Search, seller (`/s?me=`), and seller-profile
  (`/sp?seller=`) URLs are routed automatically.
- **Playwright reliability.** Each marketplace session is warmed up on the homepage and paced
  with human-like jitter. Continue-shopping interstitials, dog pages, rate limits, and
  interstitial challenges are classified and retried. Proxy selection is automatic: an available
  non-residential (datacenter/static) group in the marketplace's country, never residential by
  default.
- **Listing intelligence.** Brand, card image set and large image, organic position, sponsored
  flag, ships-to line, variant count, unit price, deal text, stock hint, sold-by line, and a
  genuine list price kept separate from Amazon's "Typical price".
- **Detail enrichment.** Specifications, gallery images, rating histogram, reviews link, seller
  ID/name/URL, variant dimensions, BSR, breadcrumbs, description, features, and stock status.
- **Safe output.** Empty fields are omitted at every depth; nothing is emitted as `null`.

### Output per product

#### Listing fields (all modes)

- `asin`, `title`, `url`, `marketplace`, `sourceMode`, `searchQuery`
- `price` `{value, currency, display}`, `listPrice`, `typicalPrice`, `discountPercent`
- `stars`, `reviewsCount`, `brand`
- `thumbnailImage`, `images`, `imageLarge`
- `badge`, `coupon`, `dealText`, `stockText`, `unitPrice`, `soldByText`, `moreOptionsText`
- `boughtInPastMonth`, `boughtInPastMonthText`
- `deliveryEstimate`, `shipsTo`, `sustainabilityFeatures`, `variantsCount`
- `offerCount`, `lowestOfferPrice`
- `sponsored` / `isSponsored`, `resultType`, `prime` / `isPrime`
- `organicPosition`, `categoryPosition`
- `categoryUrl`, `categoryPage`, `sourceLayout`, `position`
- `resultsTotal`, `resultsFrom`, `resultsTo`, `facets`, `relatedSearches`
- `scrapedAt`

#### Product-detail fields (detail enrichment or ASIN/product-URL modes)

- `brand`, `inStock`, `inStockText`, `currency`
- `specifications` (overview + technical tables)
- `images` (gallery), `imageLarge`
- `starsBreakdown` (share per star, 0.0-1.0)
- `reviewsLink`, `answeredQuestions`
- `breadCrumbs`, `description`, `features`
- `variantAsins`, `variantAttributes`, `priceVariants`
- `delivery`, `fastestDelivery`, `shippingPrice`, `returnPolicy`, `support`
- `seller` `{name, id, url}` — omitted when no real seller ID can be resolved
- `bestsellerRanks`, `locationText`

Fields that Amazon does not render for a specific product are omitted, never fabricated. This
includes render-dependent badges (Prime, sponsored), seller identity, and some buy-box details.

### Input

At least one of `categoryUrls`, `keywords`, `productUrls`, `asins`, `sellerIds`, or
`categoryNodeIds` is required. All modes are additive.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `categoryUrls` | array | – | Search, category, seller-profile, or product URLs; routed automatically |
| `keywords` | array | – | Search phrases; each builds `/s?k={query}` |
| `productUrls` | array | – | Exact product URLs; normalized to `/dp/{ASIN}` on their own marketplace |
| `asins` | array | – | Exact ASINs; each opens `/dp/{ASIN}` directly |
| `sellerIds` | array | – | Seller/merchant IDs; each builds `/s?me={id}` |
| `categoryNodeIds` | array | – | Browse-node IDs; each builds `/s?rh=n:{id}&fs=true` |
| `marketplaceDomain` | select | `amazon.com` | Marketplace for keyword/ASIN/seller/node modes (21 domains) |
| `maxItems` | integer | `0` | Global cap across all sources; `0` means unlimited |
| `maxItemsPerCategory` | integer | `10` | Cap per keyword/URL/seller/node source (1-10000) |
| `maxPages` | integer | `1` | Pages per listing source (1-50); keyword search itself stops at 7 |
| `scrapeProductDetails` | boolean | `true` | Visit each accepted product page for detail fields |
| `includeSpecifications` | boolean | `true` | Include the specifications object when detail pages are scraped |
| `sortBy` | select | `relevanceblender` | Featured, price, review, newest, or best-seller sort |
| `priceMin`, `priceMax` | number | – | Price range in the marketplace currency |
| `minRating` | number | – | Minimum star rating (0-5) |
| `includeSponsored` | boolean | `true` | Include sponsored placements |
| `onlyDeals` | boolean | `false` | Keep only cards with visible deal evidence |
| `primeOnly` | boolean | `false` | Keep only cards with a visible Prime badge |
| `rateLimitDelay` | integer | `2` | Base delay in seconds between requests (1-30) |

#### Example: keyword search, cards only

```json
{
  "keywords": ["wireless earbuds", "bluetooth speaker"],
  "maxItemsPerCategory": 100,
  "maxPages": 3,
  "scrapeProductDetails": false,
  "sortBy": "review-rank",
  "minRating": 4
}
```

#### Example: exact products and a product URL together

```json
{
  "asins": ["B08N5WRWNW", "B09X7MPX8L"],
  "productUrls": ["https://www.amazon.de/dp/B08N5WRWNW"],
  "scrapeProductDetails": true,
  "includeSpecifications": true
}
```

#### Example: category node, seller storefront, and filters

```json
{
  "categoryNodeIds": ["172282"],
  "sellerIds": ["A1B2C3D4E5F6G7"],
  "marketplaceDomain": "amazon.co.uk",
  "maxItemsPerCategory": 50,
  "onlyDeals": true,
  "maxPages": 3
}
```

### Supported Amazon Marketplaces

amazon.com (US), amazon.co.uk (UK), amazon.de (Germany), amazon.fr (France), amazon.it (Italy),
amazon.es (Spain), amazon.ca (Canada), amazon.com.au (Australia), amazon.co.jp (Japan),
amazon.in (India), amazon.com.br (Brazil), amazon.com.mx (Mexico), amazon.nl (Netherlands),
amazon.se (Sweden), amazon.pl (Poland), amazon.com.tr (Turkey), amazon.ae (UAE),
amazon.sa (Saudi Arabia), amazon.sg (Singapore), amazon.com.be (Belgium), amazon.eg (Egypt).

### Use cases

- **Competitor price tracking** — monitor price, list price, typical price, and deal evidence.
- **Category and keyword research** — collect top products with brand, rating, and organic rank.
- **Sponsored-placement analysis** — compare organic position with sponsored rows.
- **Seller storefront audits** — enumerate a seller's listed products.
- **Product research** — pull full specifications, gallery, variants, and BSR for a shortlist.
- **Multi-marketplace checks** — compare the same ASIN or keyword across 21 storefronts.

### FAQ

**Do I need Amazon cookies or an API key?**
No. The actor reads public search, category, seller, and product pages anonymously. No account,
cookie, token, or API key is required.

**Do ASIN inputs still search Amazon?**
No. ASIN and product-URL modes fetch the exact `/dp/{ASIN}` page. Keyword mode is the only mode
that performs a search.

**Why is `listPrice` missing on a product that shows a "Typical price"?**
"Typical price" is not a strike-through list price. It is returned separately as `typicalPrice`,
and `discountPercent` is calculated only from a genuine current price plus list price. This
prevents fake discounts.

**Why are Prime or sponsored fields missing from some records?**
Amazon does not render Prime icons or sponsored labels for every marketplace, exit country, or
layout. The actor reports only what the page actually shows and never claims a product is "not
Prime" from a missing badge.

**Why do I get fewer results than `maxPages` suggests?**
Amazon caps keyword search at page 7. Category listings can go deeper. For more than a keyword
surface allows, split the query by category, brand, or price band and combine the runs.

**Does the actor need my proxy?**
No. Proxy selection is automatic: it uses an available non-residential Apify Proxy group in the
marketplace's own country and never switches to residential billing on its own. There is no proxy
input to configure.

**Why do prices appear in a currency different from the marketplace domain?**
Amazon localizes currency and delivery to the request's exit country. The actor sets the
marketplace country automatically and reports the resolved `currency`; cross-border renders can
still differ from the domain's nominal currency.

**How expensive is detail enrichment?**
Each detail page is a full Amazon product page (roughly 2.5-3.1 MB). Set
`scrapeProductDetails` to `false` for large listing runs and enable it only for a shortlist or
for ASIN/product-URL modes.

**Is this affiliated with Amazon?**
No. It is an independent third-party actor that reads Amazon's public pages.

# Actor input Schema

## `categoryUrls` (type: `array`):

Amazon search, category, seller-profile, or exact product URLs. Search pages (/s?k=), browse nodes (/b?node=), seller profiles (/sp?seller=), and product pages (/dp/) are routed automatically. Combine with any other mode.

## `keywords` (type: `array`):

Plain search keywords or phrases. Each keyword builds an Amazon search URL (/s?k={query}).

## `productUrls` (type: `array`):

Exact Amazon product URLs. Each URL is normalized to /dp/{ASIN} on its own marketplace and fetched directly (never as a search).

## `asins` (type: `array`):

Amazon ASINs to fetch exactly. Each ASIN opens its own product page (/dp/{ASIN}) directly, never a keyword search.

## `sellerIds` (type: `array`):

Amazon seller/merchant IDs. Each ID builds that seller's storefront listing (/s?me={sellerId}).

## `categoryNodeIds` (type: `array`):

Amazon browse-node IDs. Each node builds a real category listing (/s?rh=n:{node}\&fs=true), with a merchandising fallback only when Amazon renders no listing grid.

## `marketplaceDomain` (type: `string`):

Amazon marketplace used for keyword, ASIN, seller, and node modes. URLs in categoryUrls/productUrls keep their own marketplace.

## `maxItems` (type: `integer`):

Global cap across every source in the run. 0 means no global cap.

## `maxItemsPerCategory` (type: `integer`):

Maximum products to return from each keyword, URL, seller, or node source.

## `maxPages` (type: `integer`):

Maximum listing pages per source. Amazon keyword search itself stops at page 7; category listings go deeper.

## `scrapeProductDetails` (type: `boolean`):

If true, visit each accepted product's own page for specs, gallery images, seller, BSR, variants, and histogram. ASIN/product-URL modes always use detail pages. If false, only listing-card fields are returned.

## `includeSpecifications` (type: `boolean`):

If true (and detail pages are scraped), return the specifications object parsed from the overview and technical-detail tables.

## `sortBy` (type: `string`):

Sort order applied to search and category listings.

## `priceMin` (type: `number`):

Only return products priced at or above this amount (marketplace currency).

## `priceMax` (type: `number`):

Only return products priced at or below this amount (marketplace currency).

## `minRating` (type: `number`):

Only return products with a star rating at or above this value (0-5).

## `includeSponsored` (type: `boolean`):

If true (default), sponsored/ad placements are included. Set false to return organic results only.

## `onlyDeals` (type: `boolean`):

If true, only return products with visible deal evidence (coupon, limited-time-deal badge, or genuine strike-through list price).

## `primeOnly` (type: `boolean`):

If true, only return products with a visible Amazon Prime badge. Badges are render-dependent in some marketplaces.

## `rateLimitDelay` (type: `integer`):

Base pacing delay between live requests. Product-detail requests always add human-like jitter.

## Actor input object example

```json
{
  "categoryUrls": [
    "https://www.amazon.com/s?k=laptops",
    "https://www.amazon.com/dp/B08N5WRWNW"
  ],
  "keywords": [
    "wireless earbuds",
    "bluetooth speaker"
  ],
  "productUrls": [
    "https://www.amazon.com/dp/B08N5WRWNW"
  ],
  "asins": [
    "B08N5WRWNW",
    "B09X7MPX8L"
  ],
  "sellerIds": [
    "A1B2C3D4E5F6G7"
  ],
  "categoryNodeIds": [
    "172282"
  ],
  "marketplaceDomain": "amazon.com",
  "maxItems": 3,
  "maxItemsPerCategory": 3,
  "maxPages": 1,
  "scrapeProductDetails": false,
  "includeSpecifications": false,
  "sortBy": "relevanceblender",
  "includeSponsored": true,
  "onlyDeals": false,
  "primeOnly": false,
  "rateLimitDelay": 2
}
```

# Actor output Schema

## `title` (type: `string`):

Product title

## `url` (type: `string`):

Direct Amazon URL for the product page

## `marketplace` (type: `string`):

Bare Amazon marketplace domain this record came from (e.g. amazon.com)

## `sourceMode` (type: `string`):

Input mode that produced this record: keywords, categoryUrls, categoryNodeIds, sellerIds, asins, or productUrls

## `searchQuery` (type: `string`):

Keyword, node ID, or seller ID that produced this listing record

## `asin` (type: `string`):

Amazon Standard Identification Number

## `brand` (type: `string`):

Product brand name

## `images` (type: `string`):

All deduplicated image URLs for the product (JSON array)

## `imageLarge` (type: `string`):

Largest product image URL available (upscaled Amazon media URL)

## `price` (type: `string`):

Current price (JSON object with value, currency, display)

## `listPrice` (type: `string`):

Genuine list/strike-through price only; never Amazon's "Typical price" reference

## `typicalPrice` (type: `string`):

Amazon's separate "Typical price" reference price (never used as listPrice)

## `discountPercent` (type: `string`):

Discount percentage, calculated only from a genuine current price and strike-through list price

## `currency` (type: `string`):

ISO currency code resolved from the product price, when available

## `stars` (type: `string`):

Average star rating from 1 to 5

## `starsBreakdown` (type: `string`):

Rating breakdown by star count as a share per star, 0.0-1.0 (JSON object), from the product detail page when rendered

## `reviewsCount` (type: `string`):

Total number of customer reviews

## `answeredQuestions` (type: `string`):

Answered-question count, only when the detail page renders it

## `inStock` (type: `string`):

Whether the product is currently in stock

## `inStockText` (type: `string`):

Detailed stock availability text

## `thumbnailImage` (type: `string`):

Main product image URL

## `features` (type: `string`):

List of product features and bullet points (JSON array)

## `description` (type: `string`):

Full product description

## `breadCrumbs` (type: `string`):

Product category breadcrumb path

## `bestsellerRanks` (type: `string`):

Bestseller rankings in different categories (JSON array)

## `specifications` (type: `string`):

Deduplicated product specifications (JSON object), from the overview and technical-detail tables

## `seller` (type: `string`):

Seller identity {name, id, url}; omitted when no real seller ID can be resolved

## `delivery` (type: `string`):

Delivery information and estimated date

## `fastestDelivery` (type: `string`):

Fastest delivery estimate, only when the detail page renders it

## `returnPolicy` (type: `string`):

Return policy text, from the product detail page

## `support` (type: `string`):

Support/warranty information, only when the detail page renders it

## `priceVariants` (type: `string`):

Per-variant price map, only when the detail page exposes one

## `locationText` (type: `string`):

Delivery destination the product detail page rendered for

## `shippingPrice` (type: `string`):

Shipping cost when explicitly shown (0 means free shipping)

## `variantAsins` (type: `string`):

List of variant product ASINs (JSON array)

## `variantAttributes` (type: `string`):

Visible variant dimensions (JSON array of {name, values}), when a twister widget exists

## `reviewsLink` (type: `string`):

Absolute link to the full reviews page, when available

## `categoryUrl` (type: `string`):

Source category/search URL

## `categoryPage` (type: `string`):

Page number in search results

## `categoryPosition` (type: `string`):

Position in search results

## `organicPosition` (type: `string`):

Position among organic results (sponsored rows are excluded from this count)

## `scrapedAt` (type: `string`):

ISO timestamp when the data was scraped

## `sourceLayout` (type: `string`):

Which page layout this card was extracted from: SEARCH_GRID, MERCHANDISING_LANDING, or MIXED

## `sponsored` (type: `string`):

Whether this result is a sponsored/ad placement (evidence-only)

## `isSponsored` (type: `string`):

Same true/false value as `sponsored`

## `resultType` (type: `string`):

Result classification: ORGANIC, SPONSORED, EDITORIAL, or OTHER

## `badge` (type: `string`):

Merchandising badge shown on the card (e.g. BestSeller, AmazonsChoice)

## `boughtInPastMonth` (type: `string`):

Number of units bought in the past month, parsed from the card's compact-count hint

## `boughtInPastMonthText` (type: `string`):

Raw "X+ bought in past month" card text

## `coupon` (type: `string`):

Coupon text shown on the card, if any

## `stockText` (type: `string`):

Raw stock hint shown on the listing card

## `unitPrice` (type: `string`):

Per-unit price text shown on the listing card

## `dealText` (type: `string`):

Raw deal/percent-off text shown on the listing card

## `soldByText` (type: `string`):

Raw "Sold by" line shown on the listing card

## `moreOptionsText` (type: `string`):

Raw "More options" hint shown on the listing card

## `deliveryEstimate` (type: `string`):

Estimated delivery text shown on the card

## `shipsTo` (type: `string`):

Ships-to location text shown on the card, if any

## `sustainabilityFeatures` (type: `string`):

Sustainability/Climate Pledge Friendly badge labels (JSON array)

## `variantsCount` (type: `string`):

Number of additional color/style variants shown via the card's "+N" hint

## `prime` (type: `string`):

Whether the card shows an Amazon Prime badge (evidence-only)

## `isPrime` (type: `string`):

Same true/false value as `prime`

## `offerCount` (type: `string`):

Number of "More Buying Choices" offers shown on the card

## `lowestOfferPrice` (type: `string`):

Lowest "More Buying Choices" offer price (JSON object with value and currency)

## `resultsTotal` (type: `string`):

Total number of results reported by the results-info bar

## `resultsFrom` (type: `string`):

Starting result index reported by the results-info bar

## `resultsTo` (type: `string`):

Ending result index reported by the results-info bar

## `position` (type: `string`):

Position metadata (JSON object with page, positionOnPage, globalPosition, uuid)

## `facets` (type: `string`):

Refinement facets available on this results page (JSON array)

## `relatedSearches` (type: `string`):

Related search suggestions shown on this results page (JSON array of text/url pairs)

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "wireless earbuds"
    ],
    "marketplaceDomain": "amazon.com",
    "maxItems": 3,
    "maxItemsPerCategory": 3,
    "scrapeProductDetails": false,
    "includeSpecifications": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/amazon-search-category-and-seller-listings").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "keywords": ["wireless earbuds"],
    "marketplaceDomain": "amazon.com",
    "maxItems": 3,
    "maxItemsPerCategory": 3,
    "scrapeProductDetails": False,
    "includeSpecifications": False,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/amazon-search-category-and-seller-listings").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "wireless earbuds"
  ],
  "marketplaceDomain": "amazon.com",
  "maxItems": 3,
  "maxItemsPerCategory": 3,
  "scrapeProductDetails": false,
  "includeSpecifications": false
}' |
apify call dataspryva/amazon-search-category-and-seller-listings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/amazon-search-category-and-seller-listings"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jLafkpWTCRAFfUa54/builds/aAJedoI4DhBVoe0x1/openapi.json