# Totalwine Product Search Scraper (`stealth_mode/totalwine-product-search-scraper`) Actor

Scrape product listings from Total Wine's vast catalog with precision. Collect prices, ratings, stock levels, brand info, and 35+ detailed fields per item — perfect for price comparison, market research, inventory tracking, and competitive analysis.

- **URL**: https://apify.com/stealth\_mode/totalwine-product-search-scraper.md
- **Developed by:** [Stealth mode](https://apify.com/stealth_mode) (community)
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 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

## Total Wine Product Search Scraper: Extract Wine & Spirits Data at Scale

***

### What Is Total Wine & More?

Total Wine & More is one of North America's largest retailers of wine, beer, and spirits, operating both online and through physical stores. The platform hosts hundreds of thousands of products with detailed attributes, customer reviews, expert ratings, and real-time inventory data. Manually gathering this product intelligence is impractical — the **Total Wine Product Search Scraper** automates the process, delivering structured product records in bulk.

***

### Overview

The **Total Wine Product Search Scraper** extracts comprehensive product listings from Total Wine's search and category pages, transforming unstructured web data into clean, actionable records. It supports two flexible scraping modes:

- **URL-based scraping** — Extract products directly from specific search result pages
- **Keyword-based scraping** — Search by product name, apply filters, and auto-paginate results

Ideal users include:

- **E-commerce competitors** monitoring pricing and inventory
- **Market researchers** analyzing product trends and availability
- **Price comparison platforms** aggregating wine and spirits data
- **Business intelligence teams** building competitive datasets

***

### Input Format

The scraper accepts configuration in two modes:

#### Mode 1: Scrape by URLs

```json
{
  "urls": [
    "https://www.totalwine.com/search/all?text=red",
    "https://www.totalwine.com/wine/c/c0020?&pageSize=24&userPrice=10-10000&bv_reviews=4%2B%20Stars&aty=1,1,0,0"
  ],
  "ignore_url_failures": true,
  "max_items_per_url": 200
}
```

**Fields:**

- `urls` — Array of Total Wine product search or category page URLs
- `ignore_url_failures` — If `true`, continues execution if some URLs fail
- `max_items_per_url` — Maximum products per URL (e.g., `200`)

#### Mode 2: Scrape by Search Filters

```json
{
  "keyword": "red",
  "sort_by": "expert-ratings",
  "price_range": "10-10000",
  "page": 2,
  "max_items_per_url": 200
}
```

**Fields:**

- `keyword` — Product search term (e.g., `"red"`, `"cabernet"`, `"bourbon"`)
- `sort_by` — Sorting method: `expert-ratings`, `customer-ratings`, `price-asc`, `price-desc`, `name-asc`, `name-desc`
- `price_range` — Filter by price (format: `"min-max"`, e.g., `"10-10000"`)
- `page` — Start page number (for pagination)
- `max_items_per_url` — Maximum items collected per search page

> **Note:** Use Mode 1 for specific URLs; leave `urls` empty when using Mode 2 filters.

***

### Output Format

**Sample output**

```json
{
  "bay": "Bay Bay 09",
  "brand": {
    "id": "Ed Edmundo",
    "name": "Ed Edmundo"
  },
  "categories": [
    {
      "id": "",
      "name": "Mendoza",
      "type": "REGION",
      "url": "",
      "storefront_url": ""
    },
    {
      "id": "",
      "name": "Red Wine",
      "type": "PRODUCT_TYPE",
      "url": "",
      "storefront_url": ""
    },
    {
      "id": "",
      "name": "Cabernet Sauvignon",
      "type": "VARIETAL_TYPE",
      "url": "",
      "storefront_url": ""
    }
  ],
  "container_type": "Bottle",
  "customer_average_rating": 4.4,
  "customer_reviews_count": 1808,
  "department": "c0020",
  "id": "213639750",
  "images": [
    {
      "image_type": "DEFAULT",
      "mobile_optimized_url": "https://www.totalwine.com/images/213639750/213639750-1-fr.png",
      "thumbnail_url": "https://www.totalwine.com/images/213639750/213639750-1-fr.png",
      "url": "https://www.totalwine.com/images/213639750/213639750-1-fr.png",
      "zoom_image_url": "https://www.totalwine.com/images/213639750/213639750-1-fr.png",
      "alt_text": "Ed Edmundo Cabernet Sauvignon, 2025"
    },
    {
      "image_type": "SUPPLEMENTAL",
      "mobile_optimized_url": "https://www.totalwine.com/images/213639750/213639750-1-m-2.png",
      "thumbnail_url": "https://www.totalwine.com/images/213639750/213639750-1-m-2.png",
      "url": "https://www.totalwine.com/images/213639750/213639750-1-m-2.png",
      "zoom_image_url": "https://www.totalwine.com/images/213639750/213639750-1-m-2.png"
    }
  ],
  "location": "Aisle 06, Right",
  "name": "Ed Edmundo Cabernet Sauvignon, 2025",
  "package_description": "750ml Bottle",
  "package_value": "Single",
  "price": [
    {
      "price": 11.99,
      "type": "EDLP"
    }
  ],
  "product_url": "/wine/red-wine/cabernet-sauvignon/ed-edmundo-cabernet-sauvignon/p/213639750",
  "review": "Argentina  - Mendoza  - Plush and elegant, with black cherry and milk chocolate ganache soothing the palate, offering a gentle, expressive richness. Beautifully balanced tannins, oak, and acidity that linger harmoniously throughout.",
  "rating": 92,
  "rating_source": "The Tasting Panel",
  "sales_strategy": {
    "name": "Winery Direct",
    "type": "WD"
  },
  "shopping_options": [
    {
      "eligible": true,
      "location": "US-CA",
      "type": "SHIPPING",
      "selected": false
    },
    {
      "eligible": true,
      "location": "Sacramento, California",
      "type": "INSTORE_PICKUP",
      "selected": true
    },
    {
      "eligible": true,
      "location": "Sacramento, California",
      "type": "DELIVERY",
      "selected": false
    }
  ],
  "sku_id": "213639750-1",
  "stock_level": [
    {
      "purchase_limit": 6,
      "stock": 174
    }
  ],
  "promo_badges": [
    {
      "badge_code": "mixcase6-10percent",
      "badge_name": "mixcase6-10percent",
      "badge_type": "DigitalPricing",
      "badge_sub_type": "MIXCASE6",
      "badge_tooltip": "Receive a special discount when you buy six or more of any bottles with the Mix 6 tag! Savings automatically applied in cart.",
      "badge_promotion_description": "Mix 6 for $10.79 each"
    }
  ],
  "store_distance": 1.392951e-06,
  "store_id": "1108",
  "store_name": "Sacramento",
  "item_taste_profile": "Vanilla",
  "item_style": "Dried Cherry",
  "item_body": "Black Currant",
  "transactional": true,
  "type": "PRODUCT",
  "volume": "",
  "stock_messages": {
    "messages": [
      {
        "shopping_method": "INSTORE_PICKUP",
        "stock_message": "In stock",
        "add_to_cart_message": "Add to cart",
        "add_to_cart_status": true
      },
      {
        "shopping_method": "DELIVERY",
        "stock_message": "Available",
        "add_to_cart_message": "Add to cart",
        "add_to_cart_status": true
      },
      {
        "shopping_method": "SHIPPING",
        "stock_message": "Get in 1-5 days",
        "add_to_cart_message": "Add to cart",
        "add_to_cart_status": true
      }
    ],
    "digital_transactional": true,
    "digital_special_order": false,
    "digital_long_term_o_o_s": false,
    "digital_limited_stock": false,
    "digital_in_stock": true,
    "store_in_stock": false,
    "shipping_transactional": true,
    "shipping_special_order": false,
    "shipping_long_term_o_o_s": false,
    "shipping_limited_stock": false,
    "shipping_in_stock": true,
    "digital_delivery_eligible": true
  },
  "priority_access": false,
  "concierge": false,
  "engravable": false,
  "from_url": "https://www.totalwine.com/search/all?text=red"
}
```

Each product record contains 35+ fields with detailed information:

#### Core Product Information

| Field | Description |
|---|---|
| `ID` | Unique internal product identifier |
| `SKU ID` | Stock keeping unit identifier |
| `Name` | Product name as displayed |
| `Brand` | Manufacturer or brand name |
| `Type` | Product category (e.g., "Red Wine", "Whiskey") |
| `Product URL` | Direct link to the product detail page |

#### Pricing & Stock

| Field | Description |
|---|---|
| `Price` | Current retail price in USD |
| `Package Value` | Suggested retail or comparative value |
| `Price Range` | Min-max pricing for variants |
| `Stock Level` | Current inventory quantity |
| `Stock Messages` | Availability status (e.g., "In Stock", "Low Stock") |
| `Shopping Options` | Available purchase methods (online, in-store, etc.) |

#### Ratings & Reviews

| Field | Description |
|---|---|
| `Customer Average Rating` | Aggregate customer star rating (1-5 scale) |
| `Customer Reviews Count` | Total number of customer reviews |
| `Rating` | Expert or system rating score |
| `Rating Source` | Origin of the rating (e.g., "Total Wine Expert", "Customer") |
| `Review` | Sample review text or summary |

#### Product Attributes

| Field | Description |
|---|---|
| `Container Type` | Packaging format (bottle, case, etc.) |
| `Volume` | Bottle size or quantity (e.g., "750ml", "1L") |
| `Item Style` | Style classification (e.g., "Full-bodied", "Dry") |
| `Item Body` | Body weight description (light, medium, full) |
| `Item Taste Profile` | Tasting notes or flavor profile |
| `Department` | Department category within Total Wine |
| `Categories` | Multiple category tags the product belongs to |
| `Package Description` | Detailed packaging and product description |

#### Location & Store Data

| Field | Description |
|---|---|
| `Bay` | Physical shelf location in-store (if applicable) |
| `Location` | Regional or warehouse location |
| `Store Name` | Name of the nearest or selected store |
| `Store ID` | Unique store identifier |
| `Store Distance` | Distance to the store (in miles) |

#### Promotional & Service Flags

| Field | Description |
|---|---|
| `Promo Badges` | Active promotions or special offer tags |
| `Sales Strategy` | Marketing approach or promotion type |
| `Priority Access` | Whether item has priority or early access status |
| `Concierge` | Whether concierge service is available |
| `Engravable` | Whether the product can be engraved |
| `Transactional` | Transaction or purchase-related flags |

#### Visual Assets

| Field | Description |
|---|---|
| `Images` | Array of product image URLs |

***

### How to Use

#### Step 1: Choose Your Scraping Mode

- **URL mode:** Gather specific search result pages by copying their URLs directly
- **Keyword mode:** Search by product name and let the scraper handle pagination

#### Step 2: Configure Input

For URLs:

```json
{
  "urls": ["https://www.totalwine.com/wine/c/c0020?..."],
  "max_items_per_url": 200
}
```

For keywords:

```json
{
  "keyword": "cabernet sauvignon",
  "sort_by": "customer-ratings",
  "price_range": "15-50",
  "max_items_per_url": 100
}
```

#### Step 3: Run & Monitor

- Start the scraper and monitor progress in the run log
- Enable `ignore_url_failures: true` for large runs to prevent interruptions

#### Step 4: Export Data

- Download results as JSON, CSV, or Excel
- Import into spreadsheets, databases, or BI platforms

**Best practices:**

- Use `expert-ratings` sort to find top-quality products
- Apply `price_range` filters to focus on target segments
- Set realistic `max_items_per_url` limits (200 is recommended)

***

### Use Cases & Business Value

- **Price monitoring:** Track competitor pricing in real-time across product categories
- **Inventory insights:** Monitor stock levels and availability patterns
- **Market research:** Analyze customer ratings and review trends
- **Product comparison platforms:** Aggregate Total Wine data alongside other retailers
- **Business analytics:** Build datasets for demand forecasting and trend analysis

The scraper eliminates manual browsing, delivering hundreds of products with complete attributes in a single run—saving hours of research while ensuring data consistency.

***

### Conclusion

The **Total Wine Product Search Scraper** is a powerful tool for anyone needing reliable wine and spirits product data. With support for flexible search filters, real-time stock data, and 35+ detailed fields, it streamlines competitive research and market intelligence gathering. Start scraping today and unlock insights from Total Wine's comprehensive catalog.

# Actor input Schema

## `urls` (type: `array`):

Add the URLs of the product search list urls you want to scrape. You can paste URLs one by one, or use the Bulk edit section to add a prepared list.

## `ignore_url_failures` (type: `boolean`):

If true, the scraper will continue running even if some URLs fail to be scraped.

## `keyword` (type: `string`):

Enter the keyword to search for items

## `sort_by` (type: `string`):

Sort items by options

## `price_range` (type: `string`):

Enter the price range to search for items

## `page` (type: `integer`):

The page number to start scraping from.

## `max_items_per_url` (type: `integer`):

The maximum number of items to scrape per URL.

## `proxy` (type: `object`):

Select proxies to be used by your scraper.

## Actor input object example

```json
{
  "urls": [
    "https://www.totalwine.com/wine/c/c0020?&pageSize=24&bv_reviews=4%2B%20Stars&userPrice=10-10000&sort=expert-ratings&aty=1,1,0,0"
  ],
  "ignore_url_failures": true,
  "max_items_per_url": 20,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "urls": [
        "https://www.totalwine.com/wine/c/c0020?&pageSize=24&bv_reviews=4%2B%20Stars&userPrice=10-10000&sort=expert-ratings&aty=1,1,0,0"
    ],
    "ignore_url_failures": true,
    "max_items_per_url": 20,
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("stealth_mode/totalwine-product-search-scraper").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 = {
    "urls": ["https://www.totalwine.com/wine/c/c0020?&pageSize=24&bv_reviews=4%2B%20Stars&userPrice=10-10000&sort=expert-ratings&aty=1,1,0,0"],
    "ignore_url_failures": True,
    "max_items_per_url": 20,
    "proxy": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("stealth_mode/totalwine-product-search-scraper").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 '{
  "urls": [
    "https://www.totalwine.com/wine/c/c0020?&pageSize=24&bv_reviews=4%2B%20Stars&userPrice=10-10000&sort=expert-ratings&aty=1,1,0,0"
  ],
  "ignore_url_failures": true,
  "max_items_per_url": 20,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call stealth_mode/totalwine-product-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,stealth_mode/totalwine-product-search-scraper"
        }
    }
}
```

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/7iwqjCj4C1GdfaJtq/builds/fAMVThCCmIFAaqaKo/openapi.json