{
  "openapi": "3.0.1",
  "info": {
    "title": "Vivino Wine Scraper $1.2💰 Ratings, Prices, Reviews & Offers",
    "description": "From $1.2/1K. Scrape Vivino.com for wine ratings, prices, taste profiles, food pairings, grapes, and reviews. Search by wine names or URLs, or discover wines by type, price, rating, country, and grape. Returns 50+ fields, including multi-merchant offers and value scores.",
    "version": "1.0",
    "x-build-id": "OSH62SIGxwH8ZU0pF"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/abotapi~vivino-wine-data-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-abotapi-vivino-wine-data-scraper",
        "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/abotapi~vivino-wine-data-scraper/runs": {
      "post": {
        "operationId": "runs-sync-abotapi-vivino-wine-data-scraper",
        "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/abotapi~vivino-wine-data-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-abotapi-vivino-wine-data-scraper",
        "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",
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "lookup",
              "discovery"
            ],
            "type": "string",
            "description": "Lookup: scrape the exact wines you list below (by name or Vivino URL). Discovery: ignore the list and find wines by filter + sort.",
            "default": "lookup"
          },
          "wines": {
            "title": "Wine names or URLs",
            "type": "array",
            "description": "Mixed list of wine names (e.g. \"Opus One 2019\") and Vivino wine URLs (e.g. https://www.vivino.com/.../w/1127795?year=2015). One record per entry. Required for Lookup mode; ignored in Discovery mode.",
            "items": {
              "type": "string"
            }
          },
          "searchMode": {
            "title": "Vintage handling (Lookup, name entries)",
            "enum": [
              "auto",
              "name_and_vintage",
              "name_only"
            ],
            "type": "string",
            "description": "How vintages are handled when looking up by name. auto: use the vintage when present. name_and_vintage: keep the vintage in the query. name_only: strip the year and match the wine.",
            "default": "auto"
          },
          "matchingMode": {
            "title": "Matching effort (Lookup, name entries)",
            "enum": [
              "basic",
              "advanced"
            ],
            "type": "string",
            "description": "basic: take the top match. advanced: also surface one alternative candidate per name for uncertain matches. The alternative is a normal record: it counts toward Max wines, gets the same enrichment, and is billed the same as any other row.",
            "default": "basic"
          },
          "wineTypes": {
            "title": "Wine types",
            "type": "array",
            "description": "Filter by wine type. Leave empty for all types.",
            "items": {
              "type": "string",
              "enum": [
                "Red",
                "White",
                "Sparkling",
                "Rosé",
                "Dessert",
                "Fortified"
              ]
            },
            "default": []
          },
          "minRating": {
            "title": "Minimum rating",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Only wines with a Vivino average rating at or above this value (1 to 4.5)."
          },
          "priceMin": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "integer",
            "description": "Lowest price (in the selected currency) for discovery results."
          },
          "priceMax": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "integer",
            "description": "Highest price (in the selected currency) for discovery results."
          },
          "originCountries": {
            "title": "Origin countries",
            "type": "array",
            "description": "Filter by the wine's country of origin (ISO 3166-1 alpha-2 codes, e.g. fr, it, us). Leave empty for all.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "grapes": {
            "title": "Grape IDs",
            "type": "array",
            "description": "Filter by Vivino grape IDs. Leave empty for all grapes.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "sortBy": {
            "title": "Sort order",
            "enum": [
              "relevance",
              "rating_desc",
              "rating_asc",
              "price_asc",
              "price_desc",
              "popularity",
              "discount_desc"
            ],
            "type": "string",
            "description": "Sort discovery results. Sponsored placements are not used.",
            "default": "relevance"
          },
          "countryCode": {
            "title": "Market country",
            "type": "string",
            "description": "Market used for pricing and availability (ISO 3166-1 alpha-2, e.g. FR, US, GB).",
            "default": "FR"
          },
          "currencyCode": {
            "title": "Currency",
            "type": "string",
            "description": "Currency for displayed prices (ISO 4217, e.g. EUR, USD, GBP).",
            "default": "EUR"
          },
          "shipTo": {
            "title": "Ship-to country",
            "type": "string",
            "description": "Optional shipping destination (ISO 3166-1 alpha-2). Echoed on each record."
          },
          "includeTasteProfile": {
            "title": "Include taste profile",
            "type": "boolean",
            "description": "Fetch body, acidity, tannins, sweetness, fizziness, intensity, and flavor notes per wine.",
            "default": true
          },
          "includeReviews": {
            "title": "Include reviews",
            "type": "boolean",
            "description": "Fetch user reviews per wine (rating, note, language, reviewer, date). Increases run time and cost.",
            "default": false
          },
          "maxReviewsPerWine": {
            "title": "Max reviews per wine",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum reviews fetched per wine when reviews are enabled (1 to 100).",
            "default": 10
          },
          "maxItems": {
            "title": "Max wines",
            "minimum": 0,
            "type": "integer",
            "description": "Caps the total wine records returned. In Lookup mode you get one record per wine you list, so the result count is your list length (this only caps it). In Discovery mode the run collects up to this many. Set 0 for unlimited.",
            "default": 20
          },
          "maxPages": {
            "title": "Max discovery pages",
            "minimum": 0,
            "type": "integer",
            "description": "Discovery mode only: optional bound on pages walked. Leave empty to walk every result page; the run still stops at Max wines."
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. The default works on the Free plan. Choose Residential for higher reliability.",
            "default": {
              "useApifyProxy": true
            }
          },
          "mcpConnectors": {
            "title": "Pipe results into your apps (optional)",
            "type": "array",
            "description": "Optionally send results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize one under Apify, Settings, API & Integrations, then select it here. Notion gets a rich page-per-item export; other connectors get a best-effort write. Leave empty to skip; never changes the dataset output. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com)."
          },
          "notionParentPageUrl": {
            "title": "Notion parent page (Notion connector only)",
            "type": "string",
            "description": "URL or id of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors."
          },
          "maxNotifyListings": {
            "title": "Max items to export per connector",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Cap on items written to each connector per run. Does not affect the dataset.",
            "default": 50
          },
          "resumeFromRunId": {
            "title": "Resume from run ID",
            "type": "string",
            "description": "Optional: paste a previous run ID (or dataset ID) from this actor. Wines already collected there are skipped, so this run only returns new ones. Leave empty for a normal run. For recurring daily monitoring of the same wines/filters, use Incremental mode below instead."
          },
          "incrementalMode": {
            "title": "Incremental changes for scheduled runs",
            "type": "boolean",
            "description": "Turn this on for daily or recurring monitoring. The first run returns all matching wines as NEW. Later runs normally return only NEW, UPDATED, and REAPPEARED wines. Turn on \"Emit unchanged\" or \"Emit expired\" only when you also want those wines returned (and billed). State is kept separately for each wine list / discovery filter and enrichment setup; use State key when you want to name or deliberately share a monitoring campaign. To continue one specific interrupted run instead, use Resume from run ID above. Note on billing: Vivino answers from the location the request comes from, so a discovery walk returns a somewhat different set of wines each run, and a repeated wine can be quoted as a different vintage from a different merchant. Scheduled discovery runs therefore return, and bill, a substantial share of NEW/UPDATED rows every time. Lookup mode with Vivino URLs that carry ?year= is far more stable. Read the README section \"Read this before you schedule a discovery run\" first.",
            "default": false
          },
          "stateKey": {
            "title": "State key (optional, incremental mode only)",
            "type": "string",
            "description": "Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently-configured runs. Leave empty to let the actor derive a key automatically from the wine list / discovery filters and enrichment settings -- different setups then never mix state with each other."
          },
          "emitUnchanged": {
            "title": "Emit unchanged wines (incremental mode only)",
            "type": "boolean",
            "description": "Off by default. Turn on to also return wines that have not changed since the last run, marked UNCHANGED. This returns, and bills, extra rows you already have, so leave it off unless you specifically want the full snapshot every run.",
            "default": false
          },
          "emitExpired": {
            "title": "Emit expired wines (incremental mode only)",
            "type": "boolean",
            "description": "Off by default. Turn on to also return wines that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked wines/filters, not when Max wines capped it or when Resume was used. This returns, and bills, extra synthetic rows, so leave it off unless you need expiry tracking.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}