# Total Wine Scraper (`confidential_gnat/totalwine-scraper`) Actor Scrape Total Wine & More (totalwine.com) wine, liquor and beer prices, sizes, ratings, reviews, badges, ABV, origin and taste profile from search, category or product URLs. Unofficial Total Wine API with JSON, CSV and Excel export. - **URL**: https://apify.com/confidential\_gnat/totalwine-scraper.md - **Developed by:** [ActorFlow](https://apify.com/confidential_gnat) (community) - **Stats:** 2 total users, 1 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. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 & More Scraper: Wine, Liquor & Beer Prices **Scrape wine, liquor and beer prices from Total Wine & More (totalwine.com)** without writing code. This **Total Wine scraper** extracts product names, **prices**, bottle sizes, customer ratings, review counts, badges, brand, country, region, ABV, taste profile and full descriptions from any search, category or product page. Paste a URL, press **Start**, and download the data as JSON, CSV or Excel, or use it as a **Total Wine API** from Python, JavaScript or any HTTP client. **Target website:** [totalwine.com](https://www.totalwine.com) ### ✨ Why use this Total Wine scraper? - **Wine, spirits and beer price data**: price, size, rating, review count, expert rating, badges, image and product URL for every product on a Total Wine search or category page. - **Full product details on demand**: switch on *Scrape product detail pages* to add description, ABV, country, region, spirit or wine type, taste profile, all size options, images, breadcrumbs and the full attribute table. - **Works with any Total Wine URL**: search, category and product URLs are detected automatically, so you can mix them in one run. - **Full pagination for search and category pages**: results are followed page after page until your `maxItems` limit is reached, so you can collect every product for a keyword or a whole category. - **120 products per page**: listings are always requested at the largest page size, so large result sets need far fewer requests. - **Cross-run deduplication**: set a project name and products scraped in earlier runs are skipped, which makes it ideal for daily price tracking. - **No browser required**: runs are fast and cheap, and no proxy setup is needed. ### πŸ“‹ What data can you extract from Total Wine? | Data | Fields | Available in | | ------------------- | -------------------------------------------------------------------- | -------------------- | | Product identity | `id`, `sku`, `name`, `url`, `brand`, `image` | Listing and detail | | Price and size | `price`, `currency`, `size`, `sizeOptions`, `containerType` | Listing and detail | | Ratings and reviews | `rating`, `reviewsCount`, `expertRating`, `expertRatingSource` | Listing and detail | | Merchandising | `badges` (e.g. top pick, award winner, limited edition) | Listing and detail | | Store and stock | `storeName`, `stockLevel`, `stockMessage` | Listing (when shown) | | Origin and style | `country`, `region`, `type`, `abv`, `style`, `body` | Mostly detail pages | | Tasting and content | `description`, `tasteProfile`, `attributes`, `breadcrumbs`, `images` | Detail pages | ### πŸš€ How to scrape Total Wine prices in 5 steps 1. [Sign up](https://apify.com/sign-up) for a free Apify account. It includes **$5 monthly credit**. 2. Open the actor page and click **Try for free**. 3. Paste one or more Total Wine search, category or product URLs into **Start URLs**, for example `https://www.totalwine.com/search/all?text=scotch`. 4. Click **Start** and wait for the run to complete. 5. Download results from the **Output** tab in JSON, CSV, or Excel format. You can also run this actor via the [Apify API](https://docs.apify.com/api/v2) or integrate it directly into your workflows using [Zapier](https://zapier.com/apps/apify), [Make](https://www.make.com/), or [n8n](https://n8n.io/). ### πŸ’° How much does it cost to scrape Total Wine? This actor uses **pay-per-result** billing based on the compute units a run consumes. - New Apify accounts include **$5 of free monthly credit**, enough to test the scraper on real Total Wine data. - It doesn't run a browser on your account, so it costs significantly less to run than browser-based scrapers. - Proxies are off by default and not needed, which keeps runs cheapest. - Listing mode (the default) is the cheapest way to collect Total Wine prices: each page returns up to 120 products, and several pages are collected per request. ### πŸ”§ Total Wine scraper input | Field | Type | Required | Default | Description | | -------------------- | ------- | -------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `startUrls` | array | βœ… | `https://www.totalwine.com/search/all?text=scotch` | Total Wine search, category or product URLs. The type of each URL is detected automatically. | | `maxItems` | integer | β€” | `5` | Maximum number of products to scrape for each search or category URL. Product URLs always return one item. | | `scrapeDetails` | boolean | β€” | `false` | Off: products are taken straight from the listing pages. On: each product's own page is also opened for description, ABV, origin, taste profile and more. | | `projectName` | string | β€” | β€” | Products already scraped under this project name in a previous run are skipped. Leave empty to disable cross-run caching. | | `proxyConfiguration` | object | β€” | `{ "useApifyProxy": false }` | Not needed; leave off to keep runs cheapest. | **Supported Total Wine URL types:** - Search: `https://www.totalwine.com/search/all?text=scotch` - Category: `https://www.totalwine.com/spirits/bourbon/c/000773` (filters and `page`/`pageSize` parameters are kept) - Product: `https://www.totalwine.com/spirits/scotch/dalmore-valour/p/2126267783` **Example input:** ```json { "startUrls": [ { "url": "https://www.totalwine.com/spirits/bourbon/c/000773" }, { "url": "https://www.totalwine.com/search/all?text=cabernet" } ], "maxItems": 100, "scrapeDetails": false, "projectName": "daily-bourbon-prices" } ``` ### πŸ“¦ Total Wine scraper output data Each product is one JSON record with the fields `id`, `sku`, `name`, `url`, `brand`, `price`, `currency`, `size`, `rating`, `reviewsCount`, `country`, `region`, `type`, `abv`, `description`, `image`, `images`, `sizeOptions`, `tasteProfile`, `attributes`, `breadcrumbs`, `containerType`, `expertRating`, `expertRatingSource`, `style`, `body`, `badges`, `storeName`, `stockLevel`, `stockMessage` and `scrapedAt`. Fields that are not available for a product are `null`; the detail-only fields (`description`, `abv`, `tasteProfile`, …) are filled when *Scrape product detail pages* is on or when you pass a product URL. The dataset has 2 views. **Overview** is a compact table with image, name, size, price, rating, reviews, stock and URL. **Product details** shows brand, type, country, region, ABV, taste profile and description. **Sample output:** ```json [ { "id": "2126267783", "sku": "2126267783-1", "name": "Dalmore Valour Single Malt Scotch", "url": "https://www.totalwine.com/spirits/scotch/dalmore-valour/p/2126267783?s=3101&igrules=true", "brand": "Dalmore", "price": 82.99, "currency": "USD", "size": "750ml Bottle", "rating": 4.7, "reviewsCount": 9, "country": "Scotland", "region": "Highland", "type": "Scotch", "abv": "43.8%", "description": "Scotland - Highland - 43.8% – Remarkably smooth with a sweet, balanced flavor. Ripe plums, citrus, and crΓ¨me caramel are accented by candied orange, pineapple, and chocolate fudge. Forest fruits, coconut, figs, and marzipan create an elegant finish.", "image": "https://www.totalwine.com/dynamic/x1000,sq/images/2126267783/2126267783-1-fr.png", "images": ["https://www.totalwine.com/dynamic/x1000,sq/images/2126267783/2126267783-1-fr.png"], "sizeOptions": ["750ml (Single)"], "tasteProfile": { "finish": "Balanced", "style": "Medium" }, "attributes": { "Country": "Scotland", "State": "Highland", "Brand": "Dalmore", "Spirits Type": "Scotch", "ABV": "43.8%", "Taste": "Sherry", "SKU": "2126267783-1" }, "breadcrumbs": ["Home", "Spirits", "Scotch", "Dalmore Valour Single Malt Scotch"], "containerType": null, "expertRating": null, "expertRatingSource": null, "style": null, "body": null, "badges": ["limited-edition"], "storeName": null, "stockLevel": null, "stockMessage": null, "scrapedAt": "2026-09-25T14:55:30.037Z" } ] ``` ### 🐍 How to scrape Total Wine with Python, JavaScript or the API Run the actor programmatically with the official Apify clients. Replace `` with the token from your [Apify Console](https://console.apify.com/account/integrations). **Python** (`pip install apify-client`): ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("/totalwine-scraper").call(run_input={ "startUrls": [{"url": "https://www.totalwine.com/search/all?text=scotch"}], "maxItems": 20, "scrapeDetails": False, }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["name"], item["price"]) ``` **JavaScript** (`npm install apify-client`): ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: '' }); const run = await client.actor('/totalwine-scraper').call({ startUrls: [{ url: 'https://www.totalwine.com/search/all?text=scotch' }], maxItems: 20, scrapeDetails: false, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` **cURL**: start a run and wait for the dataset: ```bash curl -X POST "https://api.apify.com/v2/acts/~totalwine-scraper/run-sync-get-dataset-items?token=" \ -H "Content-Type: application/json" \ -d '{"startUrls":[{"url":"https://www.totalwine.com/search/all?text=scotch"}],"maxItems":20,"scrapeDetails":false}' ``` ### πŸ’‘ What you can use Total Wine price data for - **Liquor price monitoring**: track wine, spirits and beer prices over time and catch promotions and price drops. - **Competitor price analysis**: compare your liquor store's pricing and assortment against Total Wine & More. - **Assortment and market research**: see which brands, countries, regions and styles dominate a category. - **Rating and review analysis**: find top-rated bottles, award winners and products with fast-growing review counts. - **Product catalog enrichment**: fill in ABV, origin, taste profile, images and descriptions for your own product database or e-commerce store. - **Price-comparison sites and apps**: feed up-to-date Total Wine prices into wine and whiskey comparison tools. Liquor retailers, beverage distributors, wine and spirits brands, market researchers, data analysts and price-comparison sites use Total Wine data across the alcoholic beverage and retail industry. ### ⚠️ Total Wine scraper limitations - **Very deep keyword searches are capped**: a search URL is paginated up to page 41 (about 4,900 products). Category URLs have no page cap. - **Prices are store-specific**: Total Wine prices vary by store, so the same product can show a different price depending on the store in the URL (the `s=` parameter). - **Listing fields vary slightly between runs**: brand, store and stock level come from listing pages when available; otherwise they are `null`. Turn on *Scrape product detail pages* for a complete brand, origin and ABV on every product. ### ❓ Frequently asked questions about scraping Total Wine #### Does Total Wine have a public API? No, Total Wine & More doesn't offer a public product or pricing API. This scraper works as an unofficial Total Wine API: you send search, category or product URLs and get structured JSON back, either from the Apify Console or through the Apify API. #### How do I track Total Wine prices over time? Schedule the scraper with [Apify Schedules](https://docs.apify.com/platform/schedules) to run daily or weekly on the categories you care about, then compare `price` by product `id` between runs. Set a **Project name** if you only want products you haven't scraped before, e.g. to monitor new arrivals. #### How many products can I scrape from Total Wine? Search and category URLs are both paginated until `maxItems` is reached or the results run out, at 120 products per page. A broad search or category can give you thousands of products (a "red wine" search lists over 4,000); a keyword search can return up to about 4,900. #### Can I get ABV, tasting notes and descriptions from Total Wine? Yes. Turn on **Scrape product detail pages** and each product also gets its description, ABV, country, region, spirit or wine type, taste profile (e.g. finish and style), all size options, images and the full attribute table. Pass a product URL directly to get the same details for one product. #### Why is the same Total Wine product a different price in my results? Total Wine sets prices per store. The store is part of the product URL (the `s=` parameter), so the same bottle can show different prices at different stores. Keep the store consistent in your start URLs if you compare prices over time. #### Is it legal to scrape Total Wine? This actor only collects product information that is publicly visible on totalwine.com. It doesn't log in or access private content. Scraping publicly available data is generally considered lawful (see *hiQ Labs v. LinkedIn*), but you are responsible for complying with Total Wine's Terms of Service and applicable laws. #### Do I need a proxy to scrape totalwine.com? No. The actor handles site access itself, so leave the proxy setting off and your runs stay as cheap as possible. ### πŸ”— Other actors you may find useful - E-commerce, Reviews and Data Scrapers | Actor | Description | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | πŸ›’ [Tokopedia Product Scraper](https://apify.com/confidential_gnat/tokopedia-products-scraper) | Scrapes Tokopedia product data (title, shop, price in IDR, stock, category and images) from keyword listings or product URLs. | | 🏠 [AmberStudent Accommodation Scraper](https://apify.com/confidential_gnat/amberstudent-accomodation-scraper) | Scrapes AmberStudent student accommodation listings with pricing, availability, photos, amenities, location and reviews. | | 🏒 [German Imprint (Impressum) Scraper](https://apify.com/confidential_gnat/german-imprint-scraper) | Finds the Impressum page on German websites and extracts decision makers, company address, emails, phones, register number and VAT ID with AI. | | ⭐ [Google Play Store Reviews Scraper](https://apify.com/confidential_gnat/google-play-reviews-scraper) | Scrapes Google Play app reviews with text, star rating, author, date, developer replies and optional sentiment tagging. | | πŸ“œ [Google Patents Scraper](https://apify.com/confidential_gnat/google-patents-scraper) | Scrapes Google Patents by keyword or URL: title, abstract, inventors, assignee, dates, citations, figures and PDF links. | ### πŸ’¬ Support & Contact If you encounter any issues or have questions, please [open an issue](https://apify.com/confidential_gnat/totalwine-scraper/issues/open) You can also find more of our actors on the [Actor Flow ](https://apify.com/confidential_gnat). # Actor input Schema ## `startUrls` (type: `array`): Total Wine search (e.g. /search/all?text=scotch), category (e.g. /spirits/bourbon/c/000773) or product (e.g. /spirits/scotch/dalmore-valour/p/2126267783) URLs. The type of each URL is detected automatically. ## `maxItems` (type: `integer`): Maximum number of products to scrape for each search or category URL. Product URLs always return one item. ## `scrapeDetails` (type: `boolean`): Off: products are taken straight from the search/category pages (faster, cheaper). On: every product's own page is also opened to add description, ABV, origin, taste profile, size options, all images and breadcrumbs. ## `projectName` (type: `string`): Products already scraped under this project name in a previous run are skipped. Leave empty to disable cross-run caching. ## `proxyConfiguration` (type: `object`): Not needed: the Actor handles site access itself. Leave off to keep runs cheapest. ## Actor input object example ```json { "startUrls": [ { "url": "https://www.totalwine.com/search/all?text=scotch" } ], "maxItems": 5, "scrapeDetails": false, "proxyConfiguration": { "useApifyProxy": false } } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://www.totalwine.com/search/all?text=scotch" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("confidential_gnat/totalwine-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://www.totalwine.com/search/all?text=scotch" }] } # Run the Actor and wait for it to finish run = client.actor("confidential_gnat/totalwine-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 '{ "startUrls": [ { "url": "https://www.totalwine.com/search/all?text=scotch" } ] }' | apify call confidential_gnat/totalwine-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,confidential_gnat/totalwine-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 ` 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/ujtH4Y6VoNCDSsaK1/builds/Of9bYuEpT67MUTLCU/openapi.json