# Vivino Wine Search API (`pulse_hub/vivino-wine-search-api`) Actor Batch-match wine product names to structured Vivino-style metadata: winery, vintage, rating, review count, average price, and source URL - **URL**: https://apify.com/pulse\_hub/vivino-wine-search-api.md - **Developed by:** [Vicxyz1](https://apify.com/pulse_hub) (community) - **Categories:** E-commerce, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.50 / 1,000 wine 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Vivino Wine Search API Wrapper Find Vivino-style wine ratings and product details from a list of wine names. This Actor works as a batch-friendly Vivino API wrapper for wine catalog enrichment, wine ratings API workflows, wine price enrichment, and wine product matching. It accepts one or more wine search queries, looks them up through a managed wine search API, and saves one structured result per successful match to the default Apify dataset. Use it when you need wine ratings, review counts, winery names, vintages, average prices, and source URLs in a batch-friendly format for enrichment, research, catalog cleanup, lead qualification, or marketplace data workflows. ### What does this Actor do? - Searches wine names, product titles, or free-text wine queries. - Returns normalized wine information when a match is found. - Writes one billable dataset row per successful wine match. - Keeps failed or unmatched searches visible in the run log and `RUN_SUMMARY` key-value-store record. - Runs as a batch Actor, so results can be exported as JSON, CSV, Excel, XML, or consumed through the Apify API. ### Why use this Actor? - Success-only result billing: pay for matched wine results, not every attempted query. - No Vivino key needed: run wine search and enrichment jobs without bringing your own Vivino API credentials. - Built for catalog enrichment: submit merchant titles, SKUs, wine list entries, or internal product names in bulk. - Clean one-row-per-wine output: each successful match becomes a normalized dataset row that is easy to export or join back to your catalog. - Failed matches reported separately: unmatched and failed queries stay out of the billable result dataset and are listed in `RUN_SUMMARY`. ### Input Provide an array of wine search queries. ```json { "queries": [ "Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L", "Morillon Blanc 2024 - Jeff Carrel", "White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L", "Purcari Malbec" ] } ```` #### Input fields | Field | Type | Required | Description | | --- | --- | --- | --- | | `queries` | array of strings | Yes | Wine names, product titles, vintages, or search phrases. Each query creates one backend search request. Successful matches create one billable dataset item. Maximum: 500 unique queries per run. | ### Pricing and billing behavior This Actor uses Apify's pay-per-event pricing. - `Actor Start` is charged once when a run starts, according to the Actor's configured Apify pricing. - `Wine result` is charged through Apify's `apify-default-dataset-item` event. - Each successful wine match written to the default dataset counts as one `Wine result` event. - Unmatched queries and backend errors are not written to the default dataset, so they are not charged as `Wine result` events. For example, if you submit 100 queries and 83 wines are matched, the run produces 83 billable dataset items. ### Output The Actor stores successful wine matches in the default dataset. Each item contains the original query, a status, timing metadata, and wine fields when available. ```json { "query": "Purcari Malbec", "normalized_query": "Purcari Malbec 2020", "status": "found", "elapsed_ms": 842, "match_confidence": 0.94, "matched_at": "2026-06-28T09:20:31Z", "name": "Malbec", "winery": "Purcari", "year": 2020, "type": 1, "color": 1, "grapes": "Malbec", "alcohol": "13.5", "details": "Purcari Malbec 2020", "score": 4.1, "reviews": 1200, "url": "https://www.vivino.com/...", "avg_price": "18.50", "currency": "EUR" } ``` Unmatched queries and backend errors are reported in the run log and in the `RUN_SUMMARY` record in the default key-value store. #### Dataset fields | Field | Description | | --- | --- | | `query` | The original search query submitted to the Actor. | | `normalized_query` | Cleaned query text used for product matching and catalog enrichment. | | `status` | `found` for billable default-dataset records. | | `elapsed_ms` | Backend request duration in milliseconds. | | `match_confidence` | Approximate match confidence from 0 to 1, when available. | | `matched_at` | UTC timestamp when the Actor prepared the successful match row. | | `name` | Matched wine name, when available. | | `winery` | Matched producer or winery, when available. | | `year` | Vintage year, when available. | | `type` | Internal wine type identifier, when available. | | `color` | Internal color identifier, when available. | | `grapes` | Matched grape variety or blend, when available. | | `alcohol` | Alcohol percentage or ABV value, when available. | | `details` | Full stored wine detail text, when available. | | `score` | Wine score/rating, when available. | | `reviews` | Number of reviews, when available. | | `url` | Source wine page URL, when available. | | `avg_price` | Average price, when available. | | `currency` | Price currency, when available. | #### Run summary fields The default key-value store includes a `RUN_SUMMARY` record with: | Field | Description | | --- | --- | | `total_queries` | Number of input queries accepted for the run. | | `billable_dataset_items` | Number of successful matches written to the default dataset. This is the number of `Wine result` events. | | `found` | Number of successful wine matches. | | `not_found` | Number of unmatched queries. | | `errors` | Number of backend or request errors. | | `not_found_queries` | Input queries that did not produce a match. | | `error_items` | Failed request details, including `query`, `http_status` when available, and `error`. | ### Typical use cases - Enrich wine catalogs with ratings, review counts, vintages, and winery names. - Clean up merchant product titles by resolving them to structured wine records. - Compare wine lists across shops, marketplaces, or internal inventories. - Build datasets for pricing analysis, product matching, or wine recommendation workflows. - Run scheduled searches and export results automatically through Apify integrations. ### Examples for e-commerce teams - Merchant product title cleanup: turn messy storefront names like `Purcari Malbec rosu 0.75L 2020` into structured wine, winery, vintage, rating, review, URL, and price fields. - SKU enrichment: map internal SKU names or supplier feed rows to matched wine records for product detail pages, search filters, and marketplace listings. - Wine list rating enrichment: add wine ratings and review counts to restaurant, retail, marketplace, or subscription-box wine lists. - Price/rating research: compare average prices, ratings, and review volume across a basket of wines for merchandising, assortment, and competitor research. ### Sample product-title input These examples show realistic product titles and what the parser can infer before the backend picks the best available match. | Example query | Parsed intent | | --- | --- | | `Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L` | Romanian retail title for a dry red wine. Parses winery `Tenuta Luce`, wine `Brunello di Montalcino`, vintage `2018`, and bottle size `0.750`. | | `Morillon Blanc 2024 - Jeff Carrel` | White wine title with producer text. Parses vintage `2024` and white type; producer text may stay in the normalized name if it is not recognized as a known winery. | | `White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L` | Packaged white-wine title. Parses white type, package quantity `6`, and bottle size `0.750`; less-standard producer/appellation text may remain in the normalized name. | | `Purcari Malbec` | Concise producer and grape/wine query. Parses winery `Purcari` and grape/wine `Malbec`; no vintage specified. | ### How to use it 1. Open the Actor on Apify. 2. Add one or more wine names to the `queries` input, up to 500 unique queries per run. 3. Start the run. 4. Open the default dataset to view, filter, export, or integrate the results. You do not need to provide a separate Vivino key or backend API key. The Actor uses a managed backend connection. ### Tips for better matches - Include the winery or producer name when possible. - Add the vintage year for wines where the year matters. - Use the complete label name from the bottle or product page. - Split different wines into separate query items instead of sending one long combined query. Good queries: ```text Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L Morillon Blanc 2024 - Jeff Carrel White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L Purcari Malbec ``` Less reliable queries that illustrate API limitations: ```text red wine best merlot cheap italian bottle ``` ### Limits and reliability This Actor is designed for batch enrichment, not real-time interactive search. Runs are limited to 500 unique queries and paced against the backend API to keep performance predictable. Search results depend on available source data and matching quality. Some wines may be missing, have incomplete fields, or return a nearby match rather than the exact product label. Always review important results before using them in production pricing, inventory, or compliance workflows. ### Export and integrations Because output is stored in an Apify dataset, you can: - Export results as JSON, CSV, Excel, XML, RSS, or HTML. - Pull results through the Apify API. - Send finished runs to webhooks. - Connect the dataset to automation tools and data pipelines. - Schedule recurring runs for repeated catalog checks. ### Legal and affiliation notice This Actor is an independent data enrichment tool and is not affiliated with, endorsed by, or sponsored by Vivino. Wine names, brands, wineries, and trademarks belong to their respective owners. Use the Actor responsibly and make sure your use case complies with applicable laws, marketplace requirements, and the terms that apply to your downstream use of the data. ### Support If you run into issues, include the Actor run ID, a small sample of input queries, and the affected dataset rows when contacting support. This makes it much easier to reproduce matching or backend errors. # Actor input Schema ## `queries` (type: `array`): Wine names, product titles, or search phrases to look up. Each item becomes one backend search request. Successful matches are written to the default dataset as billable Wine result events. ## Actor input object example ```json { "queries": [ "Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L", "Morillon Blanc 2024 - Jeff Carrel", "White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L", "Purcari Malbec" ] } ``` # Actor output Schema ## `results` (type: `string`): Successful wine result items produced by this run. # 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 = { "queries": [ "Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L", "Morillon Blanc 2024 - Jeff Carrel", "White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L", "Purcari Malbec" ] }; // Run the Actor and wait for it to finish const run = await client.actor("pulse_hub/vivino-wine-search-api").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 = { "queries": [ "Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L", "Morillon Blanc 2024 - Jeff Carrel", "White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L", "Purcari Malbec", ] } # Run the Actor and wait for it to finish run = client.actor("pulse_hub/vivino-wine-search-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "queries": [ "Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L", "Morillon Blanc 2024 - Jeff Carrel", "White Wine Tenuta Ulisse Pecorino Terre D'\'' Abruzzo 13%, 6 x 0.75L", "Purcari Malbec" ] }' | apify call pulse_hub/vivino-wine-search-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=pulse_hub/vivino-wine-search-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Vivino Wine Search API", "description": "Batch-match wine product names to structured Vivino-style metadata: winery, vintage, rating, review count, average price, and source URL", "version": "1.0", "x-build-id": "kmK7dmET1bqbTIq9X" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/pulse_hub~vivino-wine-search-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-pulse_hub-vivino-wine-search-api", "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/pulse_hub~vivino-wine-search-api/runs": { "post": { "operationId": "runs-sync-pulse_hub-vivino-wine-search-api", "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/pulse_hub~vivino-wine-search-api/run-sync": { "post": { "operationId": "run-sync-pulse_hub-vivino-wine-search-api", "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", "required": [ "queries" ], "properties": { "queries": { "title": "Wine search queries", "minItems": 1, "maxItems": 500, "uniqueItems": true, "type": "array", "description": "Wine names, product titles, or search phrases to look up. Each item becomes one backend search request. Successful matches are written to the default dataset as billable Wine result events.", "items": { "type": "string", "minLength": 1 } } } }, "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 } } }, "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 } } } } } } } } } } ```