Totalwine Product Search Scraper

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

{
  "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

{
  "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

{
  "id": "2126226621",
  "sku_id": "2126226621-1",
  "name": "Sera Fiore Black",
  "brand": "Sera Fiore",
  "product_url": "https://www.totalwine.com//wine/champagne-sparkling-wine/sparkling-red-wine/sera-fiore-black/p/2126226621",
  "categories": [
    {
      "label": "PRODUCT_TYPE",
      "value": "Champagne & Sparkling Wine"
    },
    {
      "label": "VARIETAL_TYPE",
      "value": "Sparkling Red Wine"
    }
  ],
  "container_type": "Bottle",
  "package_description": "750ml Bottle",
  "package_value": "Single",
  "volume": "",
  "attributes": [
    {
      "label": "Taste Profile",
      "value": "Dark Berry"
    },
    {
      "label": "Style",
      "value": "Blackberry"
    },
    {
      "label": "Body",
      "value": "Raspberry"
    }
  ],
  "price": 9.99,
  "currency": "USD",
  "prices": [
    {
      "type": "EDLP",
      "price": 9.99
    }
  ],
  "promotions": [
    {
      "code": "mixcase6-10percent",
      "name": "mixcase6-10percent",
      "type": "DigitalPricing",
      "sub_type": "MIXCASE6",
      "description": "Mix 6 for $8.99 each",
      "tooltip": "Receive a special discount when you buy six or more of any bottles with the Mix 6 tag! Savings automatically applied in cart."
    }
  ],
  "customer_average_rating": 4.7,
  "customer_reviews_count": 240,
  "expert_rating": null,
  "expert_rating_source": null,
  "tasting_note": "Italy - Deep purple in color with flavors of ripe black fruits and juicy red berries. Rich, full-bodied and elegant with the perfect amount of sweetness. Serve chilled and pair with fresh fruit, cheese, or spicy cuisine. Made with all natural flavors!",
  "sales_strategy": "Winery Direct",
  "sales_strategy_code": "WD",
  "store_id": "1108",
  "store_name": "Sacramento",
  "store_distance": 1.392951e-06,
  "aisle_location": "Aisle 17, Right",
  "bay": "Bay Bay 03",
  "stock_quantity": 16,
  "purchase_limit": 6,
  "availability": [
    {
      "method": "SHIPPING",
      "eligible": false,
      "selected": false,
      "location": "US-CA",
      "messages": [
        "Out of Stock"
      ],
      "stock_message": "Get in 1-5 days",
      "add_to_cart_message": "Add to cart",
      "can_add_to_cart": true
    },
    {
      "method": "INSTORE_PICKUP",
      "eligible": true,
      "selected": true,
      "location": "Sacramento, California",
      "messages": [],
      "stock_message": "In stock",
      "add_to_cart_message": "Add to cart",
      "can_add_to_cart": true
    },
    {
      "method": "DELIVERY",
      "eligible": true,
      "selected": false,
      "location": "Sacramento, California",
      "messages": [],
      "stock_message": "Available",
      "add_to_cart_message": "Add to cart",
      "can_add_to_cart": true
    }
  ],
  "stock_flags": {
    "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
  },
  "is_transactional": true,
  "priority_access": false,
  "concierge": false,
  "engravable": false,
  "image_url": "https://www.totalwine.com/images/2126226621/2126226621-1-fr.png",
  "images": [
    {
      "type": "DEFAULT",
      "url": "https://www.totalwine.com/images/2126226621/2126226621-1-fr.png",
      "thumbnail_url": "https://www.totalwine.com/images/2126226621/2126226621-1-fr.png",
      "mobile_url": "https://www.totalwine.com/images/2126226621/2126226621-1-fr.png",
      "zoom_url": "https://www.totalwine.com/images/2126226621/2126226621-1-fr.png",
      "alt_text": "Sera Fiore Black"
    }
  ],
  "image_count": 1,
  "raw_data": null,
  "from_url": "https://www.totalwine.com/search/all?text=red"
}

The scraper returns JSON data with each product as an object containing detailed fields. Understanding field purposes enables effective analysis and application.

Product Identification

ID: Unique product identifier on Total Wine. Purpose: Database indexing, tracking products over time, avoiding duplicates.

SKU ID: Stock keeping unit identifier of the specific sellable variant. Purpose: Inventory matching, variant-level tracking.

Name: Full product name including vintage. Purpose: Display, search, and keyword analysis.

Brand: Brand or producer name. Purpose: Brand-level analysis, assortment and competitor comparison.

Product URL: Direct link to the product page. Purpose: Accessing full details, verification of scraped data.

Classification

Categories: Array of {label, value} objects describing region, product type, varietal and other classifications. Purpose: Flexible segmentation by region, wine type or grape variety without fixed columns.

Container Type: Type of container (e.g., Bottle). Purpose: Separating bottles, cans, kegs and other formats.

Package Description: Size and format of the package (e.g., 750ml Bottle). Purpose: Normalizing prices across package sizes.

Package Value: Package multiplicity (e.g., Single). Purpose: Distinguishing single units from multipacks.

Volume: Volume value when provided (may be empty). Purpose: Unit-price calculation when available.

Attributes: Array of {label, value} objects with flavor and style descriptors (taste profile, style, body). Purpose: Flavor-based filtering and recommendation.

Pricing and Promotions

Price: Primary selling price as a number. Purpose: Price comparison, market monitoring, budget filtering.

Currency: Currency of the price (USD). Purpose: Correct financial interpretation across datasets.

Prices: Array of {type, price} objects for every price type (e.g., EDLP = everyday low price). Purpose: Tracking regular versus promotional or tiered pricing.

Promotions: Array of promotion objects with code, name, type, sub type, description and tooltip. Purpose: Analyzing discounts such as mix-case deals and their conditions.

Ratings and Reviews

Customer Average Rating: Average customer score (out of 5). Purpose: Quality and popularity benchmarking.

Customer Reviews Count: Number of customer reviews. Purpose: Judging reliability of the average rating.

Expert Rating: Professional critic score (e.g., 92 points). Purpose: Quality assessment and premium positioning analysis.

Expert Rating Source: Publication or panel that issued the expert rating. Purpose: Evaluating credibility of the score.

Tasting Note: Critic or retailer description of aroma, flavor and structure. Purpose: Content analysis, marketing copy and flavor extraction.

Sales and Store

Sales Strategy: Sales program name (e.g., Winery Direct). Purpose: Understanding sourcing and margin model.

Sales Strategy Code: Short code of the sales program (e.g., WD). Purpose: Filtering and grouping by program.

Store ID: Identifier of the store the data was collected for. Purpose: Store-level joins and comparisons.

Store Name: Name of the store. Purpose: Display and regional analysis.

Store Distance: Distance from the reference location to the store. Purpose: Proximity analysis.

Aisle Location: Aisle and shelf side where the product is placed in store. Purpose: In-store merchandising and navigation analysis.

Bay: Shelf bay label inside the aisle. Purpose: Precise shelf placement analysis.

Stock and Availability

Stock Quantity: Units in stock at the store. Purpose: Inventory monitoring and demand signals.

Purchase Limit: Maximum units a customer can buy per order. Purpose: Identifying allocated or restricted products.

Availability: Array of objects per fulfillment method (shipping, in-store pickup, delivery) with eligibility, selection, location, messages, stock message and add-to-cart status. Purpose: Comparing fulfillment options and detecting out-of-stock channels.

Stock Flags: Object of boolean flags describing digital, store and shipping stock states (in stock, limited, special order, long-term out of stock). Purpose: Fast stock-status filtering.

Is Transactional: Whether the product can be purchased online. Purpose: Separating purchasable items from display-only ones.

Priority Access: Whether the product requires priority access. Purpose: Identifying limited or allocated releases.

Concierge: Whether concierge service applies. Purpose: Identifying premium service products.

Engravable: Whether the product can be engraved. Purpose: Gift and personalization opportunities.

Media

Image URL: Main product image link. Purpose: Display in reports and dashboards.

Images: Array of image objects with type, URL, thumbnail, mobile, zoom URLs and alt text. Purpose: Downloading images, visual inspection, computer vision analysis.

Image Count: Total number of images. Purpose: Evaluating listing quality and completeness.

Raw Data

Raw Data: Complete original JSON object as scraped, without modification. Purpose: Auditing, debugging, accessing fields not included in the cleaned output, and reprocessing without re-scraping.

---

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:

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

For keywords:

{
  "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.