Vivino Wine Data Scraper: ratings, prices & taste profiles
Pricing
from $2.00 / 1,000 wine result extracteds
Extract wine ratings, prices, taste profiles, reviews, and grape varieties from Vivino. Search by wine name or URL. Fast HTTP-only approach with no browser needed. Export JSON, CSV, or Excel.
All notable changes to Vivino Wine Data Scraper are documented here.
warning to debug
(no-match-in-explore, Strategy 2.3 shortened-query skips, speculative winery-page probe failures,
transient single-attempt retries). Kept warning for genuine terminal failures and upstream 429
rate-limiting. The api-client retry log is split by status (429 → warning, 5xx → debug) to match
html-client. No matching / billing / retry logic changed; recordRateLimitTrip() accounting intact.
This makes the Apify Console "errors" tab show the real error rows (e.g. ~23) instead of 160+
cascade-noise warnings on escalation-heavy name-search runs.generateWinerySlugs now applies the -fils/-et-fils suffix to the FORWARD producer-truncation
slugs (e.g. jean-claude-bachelet → jean-claude-bachelet-fils), not only to the reversed/rotated
cores. Estates indexed as "X & Fils" on Vivino but written without "& Fils" in the catalog (e.g.
Jean Claude Bachelet & Fils — Sous le Puits, Murgers des Dents de Chien) now resolve. Advanced-only;
basic benefits via the C1 escalate-on-miss path. High-priority placement within the slug set (cap
raised 14→16 to keep both the new -fils slugs and the existing domaine-/maison- variants).
Wrong-producer bills stay guarded by the existing resolveFromWinery match gates (gate A/B).matchingMode: basic, a name search that finds nothing now retries once in advanced
before emitting NAME_SEARCH_ERROR. This recovers grower/estate wines that only the advanced
cascade surfaces (winery-page wine-list parsing / Strategy 1.5) — e.g. Domaine des Tours,
Domaine Fourrier, Pierre Peters, Simon Colin, Jamet. Zero regression on already-resolving
wines (the retry only runs when basic returns null). New escalatedRecoveries count in the
run summary; recovered rows carry a +escalated diagnostic strategy tag (stripped from output).2nd-retry-429
recovery path) rather than immediately re-hammering a throttled endpoint.proxyConfiguration input (off by default). When several runs hit Vivino in parallel,
they previously shared the Actor's single outbound datacenter IP and hit a shared 429 wall.
Enabling the proxy rotates a fresh IP per request, so concurrent runs no longer cannibalize one
IP. When enabled without a group, the RESIDENTIAL pool is coerced (Vivino often rejects
datacenter IPs). Off by default = current behavior, no imposed bandwidth cost.last-run-summary KV) now reports proxy.enabled.fetch to got-scraping (new src/http.ts single-shot
transport routed through the opt-in proxy). With the proxy off, behavior is preserved (better TLS
fingerprints, never worse against 429). The shared rate-limiter cooldown is now mutable
(RateLimiter.setCooldown in wine-core). 445 tests.reconcileVintage re-fetches the wine page with
?year=requested and overlays the vintage-specific fields (vintage, price, currency, rating, image, url).wineId::vintage key more accurate — two inputs for
different vintages of the same wine that explore collapsed to one representative vintage are now billed
distinctly. Cost: one extra fetch per explore-resolved wine whose vintage differs from the request.price:null (correct year, no offer) where it previously
showed a wrong-year price — this is intended (BI correctness); the price null-rate drift metric may tick up
legitimately. TDD: 6 cases (parser extraction + 5 reconcile branches). Adversarial review SHIP (no holes). 436 tests.GRAPE_SYNONYMS) are canonicalized so the same
wine labelled differently is not over-rejected (adversarial-review fix).cruMisalignmentPenalty — an ADDITIVE tie-break (0.1) subtracted in processExploreMatches when a
candidate carries a Premier/Grand Cru level the query did NOT ask for. 0.1 > the rating tie-break (≤0.05)
so the village wins; 0.1 < one word-match (≥0.5) so it NEVER flips a real match (a cru that matches a
REQUESTED lieu-dit stays on top). Floor 0.001 + the >0 filter preserve coverage (a lone cru still resolves).rankWineEntriesByQuery) already prefers the village via its matchCount/nameWords
length-normalization — penalty deliberately omitted there. TDD 7 cases, adversarial review SHIP. 421 tests.candidateMatchesQueryCuvee) passed VACUOUSLY when the requested cuvée is
homonymous with the producer. "Clos des Grillons – Grillons": the cuvée word "grillons" collapses
into the winery (isWineryWord) → baseDistinctive empties → gate accepted ANY cuvée of the right
producer (it billed "Le Clos des Grillons / Œillet Rouge"). Right producer, wrong cuvée billed.baseDistinctive is empty AND a winery word repeats ≥2× in the raw query tokens
(producer span + homonym cuvée), require that repeated word in the candidate NAME or region;
else not-found. A bare-producer query (no repeat) is untouched → its top wine still resolves.coherent=∅ so post
was vacuously true. Closed the vacuous-post hole: when the coherent set empties but distinctive words
remain (all producer-span), accept only if a DISTINCTIVE query word (excl. stop/hierarchy articles)
matches the candidate WINERY (producerConfirmed) — keeps the legitimate "cuvée producer" order
(Sassicaia Tenuta San Guido) while rejecting inter-entity recombination. Monotonic (only hardens
pre&&post; reviewer-proven NEW.post ⟹ OLD.post). 414 tests.hasCuveeEvidence,
no B1 fallback). Without it, a degenerate single-token producer guess ("papes") + fuzzy + the
gate's appellation fallback billed the generic wine of a HOMONYM estate ("Clos des Papes –
Châteauneuf-du-Pape" → Caves/Château des Papes CNDP) — the C1 class reopened. Verified RED→GREEN
on the colliding-estate regression test.{wineryId, winerySeoName, wineryName} for
every resolved name-search primary.rate_limited_during_search > 0 retry the full
searchWineByName once (the 429 window has cooled) → _strategy: '2nd-retry-429'.deriveProducerGuesses) is matched against the index with strictProducerMatch
(ALL distinctive words, fuzzy ±1 — never a partial match), then resolved via the
new resolveWineFromKnownWinery (explore-by-winery + page-2 rule + winery-page
wine-list fallback) → _strategy: '2nd-producer-reuse'. Acceptance gates
(cuvée gate, ranking, non-winery coverage) are STRICTLY unchanged — recovery is
pure discovery.processedKeys,
finalize, atomic push+charge — billed as confirmed successes). If the recovered wine
was already pushed under another query, the original error row is pushed instead
(traceability preserved, no duplicate billed row).chargeLimitReached, per-row try/catch (a recovery failure never kills the
rest — the original error row is pushed).last-run-summary gains secondPass: {attempted, recovered429, recoveredProducer}2nd-* strategies are counted in output.strategies; the
final status message appends (+N recovered) when N > 0.run.ts: the per-row enrich/dedup/count/finalize/push+charge block is extracted into
a shared pushRow helper (used by both passes); the primary-row construction from a
SearchWineByNameResult is extracted into wineryResultToPrimary (shared with
processName). No behavior change on the main path.findWineryIdBySlug re-fetched the same
/wineries/<slug> page on every call — catalog reruns paid the full slug-probing
fetch volume again. The slug→wineryId mapping is now cached in the vivino-wine-cache
KV store: positive entries 14 days (CACHE_TTL_WINERY_SLUG_MS), negative entries
(404 slug) 3 days (CACHE_TTL_WINERY_SLUG_NEG_MS). Keys: winery-slug-<slug>.{ wineryId, html: null }. The two call paths that need the HTML (the Advanced
wine-list fallback in resolveFromWinery, and the Strategy 2.1 discovered-slug
fallback) lazily re-fetch it via fetchWineryPageHtml — same cost as a cache miss
on that rare path, zero extra fetches in Basic mode (which never uses the HTML).last-run-summary (KV, checkpointed every 20 wines +
final) now carries a quality block: nullRates = per-field null-rate percentages
(wine-core computeNullRates) for the key fields price, alcohol, image_url,
region, computed over the RESOLVED primary rows only (error rows are all-null by
construction and would drown the drift signal; alternatives are excluded too);
sampleSize; and errorRate = error rows / primary rows. A rising null rate between
runs is the earliest selector-rot signal.errorRate > 0.5 (ERROR_RATE_ALERT_THRESHOLD),
the FINAL terminal status message is prefixed with ⚠ so a degraded run is visible
at a glance in the Console run list.per_page=50 records while large catalogs carry more (records_matched up to >100 —
114 on the real Penfolds fixture), so a requested cuvée beyond the first 50 was
unreachable on the S1 path. Now, when page 1 yields NO gate-passing candidate AND
records_matched > 50, a single page=2 fetch is made and evaluated with the exact
same gates (relevance probe → ranking → non-winery coverage). Strict cap at page 2 —
never a page 3 (no match across 100 entries is a plausible not-found, not a fetch pit).
When page 1 satisfies, NO extra fetch (zero cost on the common path).fetchExploreByWinery gains an optional page option and propagates
explore_vintage.records_matched; the page-1/page-2 evaluation is factored into
evaluateExplorePage inside resolveFromWinery (S1 and the 2.1b/2.4 pivots benefit).requested_vintage = the vintage
year parsed from the INPUT (free-text/catalog name, or a URL's ?year= param), echoed on
EVERY pushed row — resolved, alternative AND error rows, name and URL paths alike. Null
when the input carried no vintage. Distinct from vintage (the RESOLVED year, which can
differ when Vivino lacks the requested year) — comparing the two verifies the delivered
row matches the asked-for year. Null-coerced by finalizeRow (column always present).vintage).merchant_url (price.url, the
merchant buy link), discounted_from / discount_percent (price discount; Vivino sends
discounted_from: 0 + discount_percent: null when no discount), bottle_volume_ml
(price.bottle_type.volume_ml — 750/1500…), vfm_score / vfm_category (price-level
value-for-money), is_natural (wine.is_natural boolean), winery_id /
winery_seo_name (wine.winery — stable join keys), region_id (wine.region.id),
country_code (wine.region.country.code, origin country), label_image_url
(image.variations.label_large with label_medium/label fallback, https:-prefixed like
image_url). All columns always present on every pushed row (null-coerced by finalizeRow).finalizeRow now COPIES the privately-parsed _wineryId /
_winerySeoName into the public winery_id / winery_seo_name before stripping them,
so URL rows expose the producer ids too.offers is an
array of AggregateOffer with NO price key → the HTML path emitted price: null even
though the page carries the ship-to market price inline. New bounded fallback
extractInlineMarketPrice: anchored on the "prices_and_availability" block of the main
wine's <script> (same script as the island, often BEYOND the 60k island cap), cut before
"merchants_with_prices". Primary = availability.price.amount (current offer for the
ship-to market, same semantics as JSON-LD offers.price); fallback =
availability.median.amount (market median); currency from market.currency.code.
Plausibility guard 0 < price < 100 000.offers.price stays primary (Raveneau vintage fixture keeps 1695 EUR). Verified on
real fixtures: Cloudy Bay 18978 → 27.95 EUR (median 28.25), H3 Wines 1136600 →
13.88 EUR. Carousel/highlight "price":{…} objects are never taken (no
prices_and_availability anchor → null).wine_average_rating /
wine_ratings_count = the wine's rating across ALL vintages, distinct from
average_rating / ratings_count which KEEP their vintage-level semantics (explore:
vintage.statistics.ratings_*; HTML: JSON-LD aggregateRating). Always present on a pushed
row (coerced to null by finalizeRow when the source carries no wine-level stats).wine.statistics.wine_ratings_* (documented location)
with fallback to vintage.statistics.wine_ratings_* — where the real explore response
actually carries it (verified on the fixture).wine_ratings_* keys; the wine-level lives in the
island's "statistics":{"status":…,…,"vintages_count":M} object — vintages_count is the
discriminant (vintage-level stats carry reviews_count instead). Verified on real pages:
Raveneau 2010 vintage page → average_rating 4.7/41 (JSON-LD, vintage) vs
wine_average_rating 4.6/782 (island, wine).dataset_schema.json: 2 new columns + detailed view.matches[].vintage.wine.taste — structure + flavor, same shape as the tastes-API
response). exploreMatchToScrapedWine now maps it through the existing
tastesToTasteProfile mapper (no duplication) → explore-ranked name-search rows carry
taste_profile with ZERO extra fetch.enrichWine skips the /tastes API call when the row already carries a taste profile;
HTML-path rows and explore matches without taste keep the API fallback.includeTasteProfile opt-out is unchanged: finalizeRow still strips the column when
the option is off — the option controls the column's PRESENCE, not its cost.neutralizeProducerColor nulls the color when its token appears as a standalone
word of a candidate winery name or the producerHint (safe direction: disables the tie-break,
pre-I1 behavior). Also: alternativeCount no longer early-breaks (color promotion makes the
ranked list non-monotonic; full bounded scan). 3 new tests.scoring.ts: queryColor (standalone color-token detection — compound grape
names like «Pinot Blanc»/«Sauvignon Blanc» are NOT a color; mixed/no signal → null),
candidateColorConflict, colorScoreFactor, TYPE_ID_COLORS (Vivino type_id 1=Red,
2=White, 4=Rosé; 3=Sparkling stays neutral). Factors: COLOR_CONFLICT_PENALTY (×0.5) on a
conflicting candidate, COLOR_AGREEMENT_BOOST (×1.1) on explicit agreement.rankWineEntriesByQuery (seoName words only),
and into the explore path (processExploreMatches scoring + rankExploreCandidates) where
the wine type_id is a stronger signal than name words. A color-conflicting candidate is
also demoted AFTER vintage / exact-appellation promotion: color correctness outranks
carrying the requested year of the WRONG color variant.candidateMatchesQueryCuvee) is
untouched — the GRAPE_WORDS fallback (plain «Bourgogne Blanc») still resolves.candidateMatchesQueryCuvee
validated the query's distinctive words against one folded haystack, so query tokens could
recombine ACROSS candidate entities — one word matching the winery, another the wine name,
with no single entity coherently matching. Three real wrong BILLED production matches:
«Clos des Grillons Rouge» → a Chilean Cabernet by Clos des Fous ('grillons' fuzzy-hit
'grillos' in the name, 'clos' hit the winery); «Domaine Chaume-Arnaud Pontias» → a Chablis
by Domaine Jérémy Arnaud ('chaume' in the name, 'arnaud' in the winery); «Roc des Pins
Grenache» → «Les Pins» by Closerie Saint Roc ('roc' in winery, 'pins' in name).pre && post (verdict on the pre-lift distinctive set AND on the
coherent set), so the producer-span lifts can only flip accept→reject, never reject→accept.
Without it, a producer-LAST query ("Meursault Charmes Roulot") had its lieu-dit swallowed
by the backward lift, the kernel fell to the appellation, and a NEIGHBOURING lieu-dit
("Les Luchets") re-passed the gate — re-opening the v0.4.34 SEV-4 class. 3 producer-last
regression tests added. All generic fallbacks kept: appellation-only fallback (Bourgogne
Aligoté), Penfolds Grange trailing-words tolerance, region-carried kernel (B1), fuzzy ±1
producer spelling (Bernaudau). fuzzyMatch's min length 4 already prevents stop-class
article bridges (des↛les) — now locked by a test.error/errorMessage;
the 429 counter was run-level only — a 429-starved miss was indistinguishable from a
genuine Vivino absence (confirmed pain: the Dauvissat investigation). Name-search
error rows now carry a public rate_limited_during_search field: the number of 429s
encountered DURING the search for THAT wine (snapshot of the run-level trip counter
around searchWineByName). 0 = likely a real absence; >= 1 = retry in a smaller
batch before concluding. Resolved rows and URL-path error rows do NOT carry the field.last-run-summary and no
progress status (both were written once at run end) — diagnosing a 3h timed-out 670-wine
run required log archaeology. The summary builder is now a closure (buildSummary(partial))
over the run counters, and every 20 wines the loop checkpoints a partial: true snapshot
to the last-run-summary KV key plus a progress status message
(Processed N/total — X errors, Y 429). The final summary carries partial: false.
Checkpoint writes are best-effort (try/catch, log.debug) — they can never kill the run.
New errorCount run counter (pushed error rows) feeds the progress message.Actor.setStatusMessage now passes
{ isStatusMessageTerminal: true } so the Console keeps it as the run's terminal status,
and appends (stopped: charge limit) when the run stopped on eventChargeLimitReached.parseWineHtml extracted winery/region/country/wine name/grapes/
alcohol/food (and the extractMax rating fallback) with PAGE-GLOBAL regexes taking the FIRST
occurrence anywhere in the ~1 MB page. A Vivino page embeds other wines inline (carousels,
recommendations): any foreign JSON appearing before the main wine's silently contaminated
every field. New findWineIsland(html, wineId) locates the main wine's inline JSON island
(anchor "wine":{"id":<wineId>, bounded by the enclosing </script> capped at 60 000 chars
— deepest main-wine field observed on real 1.1 MB pages sits at ~+49 100). All inline-JSON
regexes now run against the island; page-global extraction remains ONLY as a fallback when
the island is absent, surfaced by a log.warning drift canary. JSON-LD stays the primary
rating/price source (untouched). 10 new tests (synthetic contamination, fallback canary,
3 real-page fixtures × 2 — skipped gracefully when local gitignored fixtures are absent —
plus a perf sanity: 1.1 MB page parsed in ~83 ms).parseVivinoUrl always returned vintage: null for /wines/{id} URLs,
even when a ?year= parameter was present. The /seo/w/{id}?year= branch already read
searchParams.get('year') correctly; the /wines/{id} branch now does the same.
1 new test.fetchTasteProfile cached all-null taste profiles for 30 days. An all-null
structure + zero flavor notes has no value to cache (re-fetching may recover data later). Added
isUsefulTasteProfile gate before setCached; profiles with at least one non-null structure
field or ≥1 flavor note are cached as before. 2 new tests.rateLimiter.waitIfNeeded() was called once before the retry loop in both
fetchApi (api-client.ts) and fetchHtml (html-client.ts). Subsequent retry attempts skipped
the limiter entirely. Moved await rateLimiter.waitIfNeeded() inside the loop in both functions.
1 new test using spy on sharedRateLimiter.waitIfNeeded.getCached returned null for expired entries but left the stale record in
KV storage indefinitely. Added store.setValue(key, null) on expiry (Apify KV convention: null
value deletes the record). 1 new test verifying the delete call.currency was always 'EUR' even when price is null. Three sites
fixed: EMPTY_SCRAPED constant, exploreMatchToScrapedWine, htmlToScrapedWine. Rule: currency
is non-null only when a price is present (price?.amount != null); falls back to 'EUR' when the
price exists but currency.code is absent (keeps backward compat for priced rows). currency type
widened to string | null in ScrapedWine. One existing test updated (htmlToScrapedWine with no
price in HTML asserting currency: 'EUR' → now asserts currency: null); 5 new tests added.Price, Image,
Alcohol content changed from "Yes" → "When available*"; footnote added explaining availability
conditions. Stale _noCharge comment in types.ts updated to reflect the 2026-06-02 policy (all
error rows unbilled). CLAUDE.md: version, test count, memory default, billing rule updated.result.chargedCount > 0 was unreliable — apify SDK v3.7.2 merges the
synthetic apify-default-dataset-item event into chargedCount (typically 2 per call). The
=== 0 failure-detection branch was unreachable in practice. Fix: snapshot
Actor.getChargingManager().getChargedEventCount(PPE_EVENT_WINE) before the push and compare
after; billed = countAfter > countBefore. Deleted the dead else if (chargedCount === 0) branch.isAlternative = true) called processedKeys.add(key),
which meant a later query whose PRIMARY is the same wine would be silently skipped (no billed row,
no error row). Fix: alternatives CHECK the set (still deduped if already pushed by a primary) but
no longer RESERVE the key via add().pushData platform error simply counted a charge failure and
lost the row. Fix: one automatic retry of pushData(scraped, PPE_EVENT_WINE); if the retry also
fails, a best-effort plain Actor.pushData(scraped) (no event) preserves the data un-billed.
Uses per-event counter (I2 fix) to avoid double-billing if the first attempt silently succeeded.getChargingManager added to
ActorMock, per-event counters tracked, beforeEach restores pushData to canonical impl. 268
tests pass.producerHint. An A/B re-run on the
250-wine Rhône list showed it regressed: resolved 46% → 40%, with 3 previously-correct matches
broken (Monier-Perréol Châtelet, Coulet Brise Cailloux, Croze-Granier Élise). Cause: the extracted
producer hint (sometimes carrying a parenthetical, e.g. "Domaine du Coulet (Matthieu Barret)") fed
the strict producer filter and rejected correct candidates — the same failure mode as the rejected
LWIN producer-hint experiment. The original "dash = 68% error vs 36%" signal was confounded: dashed
entries are simply harder, more-specific cuvées, and some old "resolved" rows were wrong matches.matchingMode to the input table,
refreshed the stale memory guidance (1024 MB default, no need to raise) and the large-volume tips
(split into ≤250-wine parallel batches), and corrected an apify blog URL missing ?fpr=.input_schema: rewrote the matchingMode description to match (250 cap, 1024 default, billing-safe).wines input at 250 per runinput_schema wines gains maxItems: 250 — the Console and API now reject inputs over
250 wines. Rationale: a 670-wine Advanced run timed out at 3 h (461/670 processed; ~2.6-3.6
wines/min on hard micro-domaine names). 250 finishes in ~1.5 h worst-case, with comfortable
timeout margin. Memory is unaffected by count (per-wine streaming; ~350-390 MiB peak regardless),
so 1024 MB is ample. For larger lists, split into ≤250-wine batches (run them in parallel)..actor/actor.json defaultMemoryMbytes and defaultRunOptions.memoryMbytes 512 → 1024
(both are needed; the live default is also set via the Apify API since apify push does not
update defaultRunOptions on an existing actor). A 670-wine basic run reproducibly OOM'd
(exit 137) at 512 MB; steady working set is ~350 MiB but transient HTML-parse spikes on large
batches cross 512. 1024 gives comfortable headroom. Under pay-per-event the consumer price is
unchanged (charged per wine-result, not per compute).matchingMode description): for messy/divergent lists use
Advanced matching at 1024 MB and split into ~130-wine batches — this resolves the
hard micro-domaine cases (Comtes Lafon Bouchères, Bernard Moreau Cardeuse, Bachey-Legros, etc.)
with zero regression, and keeps 429 rate-limiting low. (An LWIN-canonical normalization layer was
prototyped and rejected: it regressed matches — e.g. Château Les Carmes Haut-Brion — and added no
coverage over Advanced; kept in git history on feat/lwin-canonical-resolution for reference.).actor/actor.json maxMemoryMbytes 1024 → 2048, giving Advanced runs OOM headroom (Advanced + bundled match-table + large winery HTML pages could SIGKILL/exit-137 at 512 MB on big batches). defaultMemoryMbytes stays 512 (Basic is light).input_schema matchingMode description now tells users to run large Advanced jobs at 1024–2048 MB and to split into ~130-wine batches (each finishes well under the 3 h timeout and keeps rate-limiting low).name/winery/wine_type/region/country = null (was "Unknown"), so a run with many unmatched wines no longer looks like rows of fake "Unknown" wines — the absence is read from the error column. Resolved rows are unchanged (a real wine with a genuinely missing field still falls back to "Unknown"). These fields are now typed string | null; dataset_schema updated.lwin (Liv-ex LWIN-7) + lwin_canonical (AVA canonical name) when the queried wine is confidently in the bundled AVA match-table — letting Vivino output be joined to an LWIN/AVA catalog. "Confident" = a new resolveLwinSafe (wine-core): exact key OR an order-independent token-set match, but only when exactly one canonical shares that token set (ambiguous short forms → null). Never guesses, so a returned LWIN is trustworthy. null when unknown (column always present).resolveLwinSafe tests (exact, order-independent, ambiguous→null); 257 vivino + 97 wine-core pass. Typecheck clean. dataset_schema gains the two columns.matchingMode input (Basic / Advanced) to fix large-batch throughput/429The fallback strategies added in v0.4.34–v0.4.39 (winery-page list, search-hit pivot, shortened-query, bare-producer search, plus the -fils/domaine-/maison- slug variants) collectively drove ~40-60 HTTP fetches per failing wine, tripping Vivino rate-limiting (429) on large batches — a 378-wine run reached only ~167 wines with an inflated error rate (resolvable wines failing on 429). New input field lets the user pick:
LastName↔FirstName reversal + single-word) + Strategy 1 (explore) + Strategy 2.1 (discovered slug) + Strategy 2.2 (top entry). ~3-6 fetches/wine, predictable cost, no 429 spiral. For lists named like Vivino.All zero-fetch quality guards (cuvée gate, exact-appellation tie-break, IDF ranking, grape/fuzzy logic) stay active in both modes, so neither mode bills a wrong match. last-run-summary records matchingMode.
rankWineEntriesByQuery's near-match branch now also accepts a fuzzy ±1 match (in addition to prefix), so a catalog cuvée spelled one letter off from Vivino's surfaces the right entry instead of a sibling: "Maltroye" → Vivino "Maltroie", "La Reine" → "la Reina". The cuvée gate already tolerated this; the ranker didn't, so the correct entry never reached the gate. Half weight (exact match still wins). → Pierre-Yves Colin-Morey "Chassagne Maltroye" resolves.deriveProducerGuesses + strictProducerMatch), and resolves the requested cuvée from its full winery page. The strict match (every producer word must fuzzy-match the winery) prevents billing a wrong same-lieu-dit producer — e.g. a "Colin Morey" query resolves to Pierre-Yves Colin-Morey and never to Joseph Colin (which shares only "colin"). Runs only on otherwise-not-found queries.& Fils, domaine-des-…, locale prefixes), Strategy 1's slug guesses 404 and the search page surfaces only a subset of the producer's cuvées — so a requested cuvée absent from that subset returned not-found even though it's on Vivino (e.g. Comtes Lafon "Meursault Les Bouchères", Bernaudeau "Les Terres Blanches", Colin-Morey, Marc Colin). parseWineHtml now extracts the wine's winery seo_name + id; new Strategy 2.1b takes a producer-matching search hit, reads its winery slug, and resolves the full winery range (explore + winery-page list) from there. The slug-loop body is refactored into a shared resolveFromWinery helper._winerySeoName/_wineryId fields carry the slug through and are stripped before push.generateWinerySlugs now emits -fils / -et-fils winery-slug variants. Vivino indexes "Jean Claude Bachelet & Fils" at slug jean-claude-bachelet-fils (winery_id 20909), whose page lists every cuvée — Murgers des Dents de Chien (w/1927348), Sous le Puits, Les Encégnières, Les Combes au Sud, Blanchot-Dessus, Bienvenues-Bâtard, … The catalog writes only "Bachelet Jean Claude", so that slug was never generated; the search page surfaced at most one Bachelet wine per query, too few for slug-discovery (needs ≥2). Earlier I wrongly classified those cuvées as Vivino absences — they were simply unreachable. The producer cores now also get -fils / -et-fils suffixes (high priority) so Strategy 1 fetches the full winery page.HIERARCHY_WORDS token — which wrongly included fils / fille / freres / pere. Those legitimately end a winery slug (…-fils, …-pere-et-fils), so they're now exempt; slug cap raised 12 → 14 to fit the variants.les-coqueries, les-nourrissons, les-ongles-blanc) but processWineEntries's producer-word check (matchCount) and candidateMatchesQueryCuvee's winery-word exclusion both compared exactly, so "bernaudau" both failed the producer guard and was mistaken for a distinctive cuvée word no wine name contains. Both now use the existing fuzzyMatch (edit-distance ≤1), consistent with how cuvée tokens already tolerate singular/plural and typos. → the four Bernaudeau cuvées resolve.w/9432554) lost to "Les Résistants Savagnin" and returned not-found; Labet "La Reina Chardonnay" / "Cuvée du hasard" similarly mis-resolved. rankWineEntriesByQuery now weights each query word by inverse document frequency across the candidate entries (a word in many entries → weak signal; a rare lieu-dit → strong), so the distinctive cuvée surfaces. Only re-orders the score>0 set (same inclusion), so non-affected producers are unchanged. findWineFromWineryPage now also selects the first entry that passes the cuvée gate, not just the top — recovering the right cuvée if a sibling still edges ahead. Side benefit: fewer wasted wine-page fetches per query (throughput)..actor/actor.json defaultRunOptions.timeoutSecs). The 30-min default silently truncated batches (the 378-wine run TIMED-OUT at 1 h having done 128); 2 h is a ceiling — runs still stop when work is done, so small runs are unaffected — covering ~250 wines/run. Larger batches should still be split or given a higher per-run timeout (≈28 s/wine).\uXXXX JSON escapes now decoded in regex-extracted winery/region/country (the real "& Fils" blocker). parseWineHtml's fallback regex pulled the winery name straight from the page's inline JSON without unescaping — so "Jean Claude Bachelet & Fils" arrived as Jean Claude Bachelet & Fils. The producer surname guard then tokenized the literal escape and took "u0026" as the surname, which (never in any query) dropped every wine of any "& Fils" / "& Fille" domaine — a whole class of Burgundy estates. Now decodeJsonUnicode unescapes the three regex-extracted JSON string fields, so the winery reads "Jean Claude Bachelet & Fils" → surname "bachelet" → the wines resolve. Also fixes accent mojibake (é → é) on that extraction path.generateWinerySlugs rotates a 3-word producer to "first-middle-surname". Catalogs list producers "LastName FirstName(s)" — e.g. "Bachelet Jean Claude". The producer-order reversal (v0.4.24) only swapped the first two words → jean-bachelet (a different Mâcon winery); the rotation now also moves the leading surname to the end of the first three words → jean-claude-bachelet, with domaine-/maison- variants. General improvement for 3-word producers whose Vivino winery page lives at that slug (a 2-word producer just 404s the extra probe harmlessly).candidateMatchesQueryCuvee's first distinctive word is the appellation ("saint-aubin"), shared by every wine of the appellation. When the exact lieu-dit was absent on Vivino, the gate billed a neighbouring one (Bachelet Murgers → billed Bachelet Derrière la Tour). The gate now skips words that belong to the candidate's own region/appellation and requires the first non-appellation distinctive word (the lieu-dit kernel "murgers") to match — falling back to the appellation word only when every distinctive word is appellation (generic-named wines, B1, unchanged). searchWineByName now also threads the candidate region into the Strategy 2.2 / 2.3 gate calls so the kernel test applies on the search-page path (where the Murgers mis-match occurred). Penfolds-Grange-style trailing-descriptor tolerance is preserved (no region passed → kernel = first distinctive).Re-ran the original 82-wine ITQS catalog (run N9g6V8KyM01Kpqt92) on the current build. Error rate fell from 35/82 (build 0.4.18) to 4. Of those four, the real, fixable defect was two BILLED wrong-cuvée matches (the worst class — the user pays for the wrong wine):
rankExploreCandidates returned — and billed — the WRONG cuvée: Charmes-Chambertin Grand Cru (2022) instead of Chambertin Grand Cru, Puligny-Montrachet Les Enseignères instead of Le Montrachet Grand Cru. All *-Chambertin / *-Montrachet candidates tie on scoreWineMatch, then processExploreMatches vintage-promotes whichever has the requested year — so the wrong wine, having a closer vintage, won the primary slot and the correct one was demoted to an (unbilled) alternative. New promoteExactAppellationHead (scoring.ts) lifts the candidate whose name head is the exact appellation ("Chambertin Grand Cru") above same-suffix neighbours ("Charmes-Chambertin") before the per-wine collapse — cuvée correctness now outranks getting the exact year of the wrong wine. Vintage promotion still decides among vintages of the correct wine. Validated end-to-end on build 0.4.43: both now resolve to the right Grand Cru as the billed primary, with the others demoted to unbilled alternatives; 5 control wines (Roumier Bonnes-Mares, Sauzet Chevalier-Montrachet, Rousseau Ruchottes-Chambertin, Mugneret-Gibourg Échezeaux, Colin Marc Montrachet) unchanged — no regression.isExactAppellationHead, promoteExactAppellationHead); 232 pass. Typecheck clean.matchesProducer drops it because the catalog's first name "Claire" is absent from Vivino's "Henri …". This cannot be relaxed by name alone without re-admitting genuinely-distinct same-surname estates (e.g. Anne-Claude Leflaive vs Olivier Leflaive). Remains an unbilled not-found (3 vintages).girardin-pierre-richebourg 404, no search hit). Correctly unbilled.domaine-de-la-vougeraie, which we can't reconstruct from "La Vougeraie"), but explore-by-winery has no cuvée match, we now parse that winery page's own wine list (its HTML was already fetched for the id) — exactly like Strategy 1.5 does for the slug loop. Reaches rare cuvées absent from BOTH explore-by-winery and the search page but present on the winery page: Domaine de la Vougeraie Musigny Grand Cru (w/2376338) now resolves instead of a not-found.generateWinerySlugs no longer emits slugs ending in a hierarchy/appellation/négoce word (…-igp, …-pays, …-cru, …-neg) — a producer name never ends that way, so those only burned winery-page fetches (and 429 budget). Producer-prefix truncations are also capped at 3 segments (from 5), and the slug list is capped at 12. Producer-focused slugs (reversed, single-word, domaine-/maison- prefixed, négoce) are preserved. Cuts ~3-5 winery fetches per appellation-laden multi-word query.processWineEntries's winery guard required ≥50% of the Vivino winery's words to appear in the query — which wrongly skipped wines whose producer the catalog abbreviates: "De Vogue" is 1/4 of "Domaine Comte Georges de Vogüé", "Mugnier" 1/4 of "Domaine Jacques-Frédéric Mugnier". The HTML search page does return these wines (verified via the run log), but the filter dropped them. Now the guard only requires one producer word in common; the surname check (last significant winery word must be in the query) remains the real producer-identity gate. Fixes De Vogüé Bourgogne Blanc and Mugnier Bonnes-Mares.<70% non-winery-coverage check is extracted into a shared passesNonWineryCoverage helper (no behaviour change; reused for clarity)./api/explore/explore?q=…) was prototyped and dropped — the live API ignores the free-text q param (returned nothing for de Vogüé while the HTML search page returned it), so it was a no-op that only added a request.explore-by-winery returns no (or no relevant) matches — the wines exist only on the winery landing page. findWineryIdBySlug now returns the page HTML alongside the id; when the explore path yields nothing usable, findWineFromWineryPage parses the winery page's own wine list (every cuvée is linked as /<seo>/w/<id>) and runs it through processWineEntries + the cuvée gate. New _strategy value winery-entries (counted in the Strategy-2-fallback stat). Wine-page dedup (seenWineIds) is now shared across Strategy 1.5 / 2.2 / 2.3.pays to HIERARCHY_WORDS so appellation-category noise ("IGP Pays d'Hérault") no longer becomes the gating distinctive token — lets generic-named Vin-de-France/IGP wines ("Rouge") match on their region.domaine-/maison- prefix the catalog label omits. generateWinerySlugs now appends domaine-<core> / maison-<core> variants of the producer-core slugs (reversed, single-word, forward 2-word) as low-priority candidates — fixes e.g. "Renaudin Maxime" → domaine-maxime-renaudin, "Glandien Cruci" → maison-glandien. Cores already carrying a prefix are skipped (no domaine-domaine-).NEGOCE_TOKENS ("neg", "nego", "negoce", …). When a query carries one (e.g. "Leroy Neg …"), the producer is a maison: maison-<core> (core = words before the marker) is tried first, so it resolves to "Maison Leroy" rather than the unrelated "Domaine Leroy". The marker is also stripped from buildQueryWords so it never pollutes scoring or the cuvée gate.APPELLATION_TYPOS map applied in buildQueryWords (mersault→meursault, echezaux→echezeaux, …) — fixes "Coche Dury Mersault Rougeots".fuzzyMatch now tolerates one insertion/deletion (not just one substitution) and is applied consistently across the four name checkpoints that previously used exact includes: distinctiveWordsFilter, the relevance probe, the <70% non-winery fallback, and the B1 cuvée gate (candidateMatchesQueryCuvee). Fixes singular/plural & missing-letter mismatches (cote↔cotes, village↔villages) — "Leroy Neg Côtes de Nuits village" now resolves to Vivino "Côte de Nuits Villages" (winery found via A2, wine no longer rejected by the multiple exact-match gates).extractWineryIdFromText now also reads the app deep-link vivino://?winery_id=<N> present on every /wineries/<slug> page. Small producers (few wines) embed their id ONLY there — without this, the A1/A2 slugs resolved to a real page (HTTP 200) but the id could not be parsed, so they still 404'd logically. Confirmed via Firecrawl (Domaine Maxime Renaudin = 293195).domaine-comte-georges-de-vogue from the search page) needs winery seo_name extraction, not a prefix-cap change (which would over-extend into appellations) — to be done separately.distinctiveWordsFilter (active only at ≥2 distinctive words) let the explore path return ANY wine of the right producer — e.g. "La Vougeraie Musigny" → Bonnes-Mares Grand Cru (matchScore 0.5), "Mugneret-Gibourg Echezeaux" → NSG Chaignots (1), "Girardin Richebourg" → Vosne-Romanée (1), "Selosse Carelles" → Millésime (0.5, with the real Carelles demoted to alternative). These were returned as successful, billed rows.rankExploreCandidates now applies a region-aware cuvée gate — the query's first distinctive token must appear in the candidate's name, region, or appellation (candidateMatchesQueryCuvee gains an extraHaystack param). Wrong cuvées are rejected; the Strategy-2 search fallback then has a chance to surface the correct wine, and otherwise the row is a (non-billed) not-found instead of confidently-wrong data. Generic-named wines ("Bourgogne Blanc", "Rouge") still pass via the region/appellation haystack.rankExploreCandidates collapses candidates by wineId (keeping the best-ranked vintage) before selecting alternatives, and pulls a wider explore pool (maxResults: 20) so enough distinct cuvées remain. Previously "Domaine Leflaive Puligny-Montrachet" returned the same wine (Les Pucelles) three times.alternativeCount now gates every runner-up on closeness to the top (within ALT_GAP_RATIO) — or surfaces alternatives wholesale only when the top match is itself low-confidence. A near-tie no longer drags in a far, irrelevant runner-up (e.g. a score-1 Gevrey alongside a score-9 primary).Charles Lachaux (slug charles-lachaux, winery 273769) now resolves from the catalog label "Lachaux Charles …".tests/, vitest.config.ts, and dist/*.map from Apify sourceFiles[] via .gitignore (CLAUDE.md rule #3): test files carried internal commentary and the bundle source map exposed bundled wine-core source. Files remain tracked in git; only the deploy upload is trimmed.ALT_TOP_SCORE_FLOOR) or the runner-up is a near-tie (within ALT_GAP_RATIO of the top), the Actor now also emits up to ALT_MAX_ALTERNATIVES (2) alternative rows — other cuvées from the same producer — so the user can disambiguate.
matchScore (relevance of the match; on every name-search row) and isAlternative (true on alternative rows)._noCharge / isAlternative rows are pushed via plain pushData (no wine-result event). You pay for one primary result per input.searchWineByName surfaces matchScore + alternatives (DRY rankExploreCandidates / selectionFromRanked helpers shared by s1 and s2.1); alternativeCount is a pure, unit-tested decision function. processName now returns ScrapedWine[] and the runActor loop iterates rows, deduping and enriching each. README + dataset schema updated; the stale "error rows are billable" note corrected (error rows are not billed since the 2026-06-02 policy).Lachaux Charles) while Vivino indexes them "FirstName LastName" (charles-lachaux). generateWinerySlugs now also emits the reversed 2-word producer slug (winery prefix stripped) as an additional candidate, so wineries like Charles Lachaux Côte de Nuits-Villages "Aux Montagnes" resolve instead of 404-ing on every lachaux-charles-* slug. The forward slug stays the first candidate; the reversal is additive. Uses producerHint when available, falling back to the query's winery part.wines field title to "Wines or Vivino URLs or mix of both" to make explicit that an entry can be a wine name, a Vivino URL, or any mix (each line is auto-detected).wineNames and wineUrls input fields — superseded by the unified wines field. collectInputs (run.ts) no longer reads them. ⚠️ Backward-compat: integrations still sending wineNames/wineUrls will have those entries ignored — migrate to wines.matchesProducer required every producer-hint word to be a substring of Vivino's winery name (.every), and filterByProducer drops all results when none match. Once parseWineName started supplying a producerHint (v0.4.19) and it was threaded into Strategy 2 (processWineEntries), a catalog label carrying a non-winery token — e.g. "Leroy Neg" (négociant marker) vs Vivino's "Maison Leroy" — dropped every valid result → NAME_SEARCH_ERROR. Now only distinctive (≥4-char) producer words must all match; short tokens (négociant markers, initials) are tolerated, with a fall-back to all words when the hint has no ≥4-char word. Preserves precision (e.g. "Pierre Girardin" still does NOT match "Pierre-Yves Colin-Morey"). filterByProducer also treats a hint that normalizes to no usable words (prefix + initial) as no-hint instead of dropping all.search.ts: destructure producerHint once in searchWineByName instead of repeating opts.producerHint ?? null at six call sites (behavior-preserving).matchesProducer/filterByProducer cases (Leroy Neg recovered; shared-first-name false-positive guard; short-surname fallback; prefix+initial no-op). 192 tests passing (was 187). Typecheck + build clean.NAME_SEARCH_ERROR (definitive not-found after a real search) was charged the wine-result event ("success or error item", the X-1 stance). Following run N9g6V8KyM01Kpqt92 (a catalog batch that showed 49% billed error rows — a figure inflated by the now-fixed parseWineName regression) and a monetization review, the policy is now charge on confirmed success only: every error row (NAME_SEARCH_ERROR, URL_PROCESSING_ERROR, infra/transient failures) is pushed to the dataset for visibility but never billed. Single gate in run.ts: noCharge = _noCharge || error != null. PPE doctrine — if the user did not get a wine, the event does not fire.pay_per_event.json wine-result description updated to state success-only billing and that error rows are not charged (renders on the Pricing tab).charged (1) < pushed (2). 187 tests passing. Typecheck + build clean.WINE_TYPES had Vivino type_id 3 and 4 swapped (3: 'Rosé', 4: 'Sparkling'), a latent bug inherited verbatim from the monolith. Every sparkling wine was labeled "Rosé" and every rosé "Sparkling". Surfaced by run N9g6V8KyM01Kpqt92: Jacques Selosse Les Carelles Blanc de Blancs (a Chardonnay sparkling Champagne) came back wine_type: "Rosé" — only possible from type_id 3, which Vivino assigns to sparkling. Corrected to 3: 'Sparkling', 4: 'Rosé' (src/constants.ts). Affects both the explore and HTML paths (wineTypeLabel).resolveShipTo(shipTo, countryCode) in run.ts. Vivino prices come from the Explore API keyed by country_code = the delivery market (= shipTo), not countryCode (origin filter only). When shipTo is empty/invalid but countryCode is a valid 2-letter code, the actor now falls back shipTo := countryCode and logs a warning. In run N9g6V8KyM01Kpqt92 the user set countryCode: "FR" with empty shipTo and got price null on 100% of rows; this fallback would have unlocked prices. Explicit shipTo still wins.resolveShipTo unit tests (tests/run.test.ts), +4 wine_type mapping tests incl. type_id 3→Sparkling / 4→Rosé (tests/parser.test.ts).parseWineName (spreadsheet-column split + catalog cleanup + producer-hint derivation) was never ported during the TS migration, so tab-separated catalog rows (Producer⇥Cuvée⇥Vintage⇥Color) were sent verbatim to search — tabs and the color token included. Live run N9g6V8KyM01Kpqt92 showed the impact: vintage null on 100% of rows (the year is a middle column, and the TS parseWineQuery only matched a leading/trailing year), color/tabs polluting every query, producerHint never set, and same-wine vintages collapsing under the wineId::'' dedup key.src/wine-name.ts parseWineName(name, searchMode) → { cleanedName, vintage, producerHint }, faithfully ported from the monolith: multi-column rows (vintage from any column, color/level dropped via GENERIC_SKIP, winery prefix stripped from the query but kept in producerHint), the 2-column description ⇥ vintage|NV format (cleanCatalogText + region-prefix strip), and classic free-text (inline vintage + bottle-volume strip). French abbreviations expanded (NSG → Nuits-Saint-Georges, 1er → Premier, CDP, VV, …) so the validator recognizes them in Vivino names.run.ts now parses name inputs through parseWineName; producerHint is threaded through searchWineByName → processExploreMatches / distinctiveWordsFilter / processWineEntries (previously hard-coded null, the documented "Phase 3" TODO). This restores per-vintage dedup, feeds producer disambiguation for short négociant names, and removes color/tab noise from the search query. searchQuery output unchanged for non-tab inputs (still the cleaned query).tests/wine-name.test.ts (multi-column split, abbreviation expansion, winery-prefix strip, name_only vintage handling, 2-column NV/vintage, region-prefix strip, classic trailing vintage, bottle-volume strip)._noCharge flag, consistent with the HTML-fetch-failure branches. NAME_SEARCH_ERROR (not-found after a real search) stays billable. Audit X-1.URL_PROCESSING_ERROR / "HTML fetch failed") are now pushed for visibility but NOT billed: they carry an internal _noCharge flag that suppresses the wine-result event. An infrastructure/transient failure delivers zero value (Apify PPE doctrine). NAME_SEARCH_ERROR (no match found after a real search) remains billable — a definitive not-found is a delivered result per the documented policy. The _noCharge flag is stripped before the dataset push. Audit 2026-06-01 finding X-1.image_url is now always a string (or null). When a wine page's JSON-LD ships image as an array of URLs (observed on ~27% of live rows in the 2026-06-01 audit), the HTML parser previously emitted the raw array into image_url, violating the dataset schema (["string","null"]). Now coerced to the first URL (parser.ts:237).seenWineIds: Set<number> initialized at the top of the Strategy 2 block. Previously, on difficult queries (e.g. Penfolds Grange Bin 95 Shiraz where 2.2 surfaced Bin variants that failed candidateMatchesQueryCuvee), Strategy 2.3 would re-fetch the same processWineEntries candidates already retrieved by 2.2 - up to 30-40 HTTP roundtrips per query. processWineEntries now accepts an optional seenWineIds parameter, skips entries whose wineId is already in the Set, and adds successfully-fetched wineIds back to it.'Unknown' (region / country) or null (appellation). Vivino sometimes returns region: { name: "" } (or whitespace-only) instead of dropping the key entirely, which made the previous ?? 'Unknown' fallback emit "" verbatim into the dataset. New helper normalizeOrUnknown(s) in src/parser.ts collapses null / undefined / whitespace-only strings, applied to both exploreMatchToScrapedWine and htmlToScrapedWine paths.!sqResp?.ok) no longer fall through silently. The 5xx case now emits log.warning and calls recordRateLimitTrip() so the run-level counter surfaces the upstream pressure mode that previously hid behind a silent continue.tests/wine-entries.test.ts (seenWineIds dedup: pre-populated Set skips entry; cross-call persistence; combined with skipNameFilter).tests/parser.test.ts (empty / whitespace-only region / country / appellation normalization across both extractor paths).Chateau Margaux had its chateau prefix stripped, then the residual margaux was used as a fallback winery slug - which on Vivino resolves to an unrelated winery whose explore matches passed the relevance probe by sharing only chateau and margaux words with the query.REGION_NAMES_BLOCKLIST in src/constants.ts: lowercase, accent-stripped region names that must not be used as winery-slug fallbacks. Expandable on observation of similar false-positives.min(2, qw.length) as the per-match threshold instead of a hard-coded >= 2. Previously, when buildQueryWords returned a single distinctive word (e.g. "Chateau Margaux" -> qw = ['margaux'] because chateau is filtered as a WINERY_PREFIX stop word), the probe was mathematically impossible to pass, so the correct winery slug (chateau-margaux -> winery 1319) was rejected and the actor fell through to Strategy 2, which surfaced "Andrena Margaux" (winery "Château Le Coteau") as the documented false positive. The relaxed threshold allows single-word matches to land on the right producer while keeping the protective behavior for multi-word queries (e.g. the T12 "Jean Other Specific Cuvee" path still requires 2/4 matching words).Sprint 6.1: fix last-run-summary.output.charged observability counter.
pushDataAndCharge (apify/dist/charging.js:407-412) auto-schedules BOTH the explicit event (wine-result) AND the synthetic apify-default-dataset-item event when pushing to the default dataset. mergeChargeResults sums chargedCount across both. So every successful Actor.pushData(item, 'wine-result') returned chargedCount = 2 (1 wine-result + 1 synthetic). The pre-fix counter accumulated raw chargedCount, producing charged = pushed * 2 on every run.src/run.ts:336 now collapses chargedCount > 0 to a +1 increment. This restores the original observability intent (track "rows actually billed" for revenue-leak detection — Sprint 5 goal) by ignoring the synthetic dataset event.charging.js:290-294 skips apify- synthetic events). Only wine-result × $0.003 was ever charged.chargedCount = 2 each, summary showed charged: 20. After fix the same scenario will report charged: 10.chargedCount = 2 per call and asserts charged === pushed).Sprint 6 of the post-audit roadmap: Penfolds Grange Strategy 2 deep-dive. Closes a known parity gap where the user query "Penfolds Grange Bin 95 Shiraz" produced a wrong-wine row (Bin 128 Shiraz) instead of the correct Penfolds Grange.
Penfolds Grange correctly surfaces Grange (wineId 1136930).candidateMatchesQueryCuvee(name, winery, query) in scoring.ts - softer than distinctiveWordsFilter, asserts only that the user query's first distinctive word (the cuvee kernel, e.g., 'grange') appears in the candidate's name. Used to reject candidates that pass score thresholds but miss the cuvee.processWineEntries on search-page entries) now runs the cuvee check on its top result. Candidates that fail fall through to Strategy 2.3 instead of being emitted as wrong-wine rows._strategy value s2-shortened for rows surfaced via Strategy 2.3; counted in last-run-summary.output.strategies and in the Strategy 2 fallback aggregate.candidateMatchesQueryCuvee + 2 covering Strategy 2.3 behavior end-to-end).Sprint 5 of the post-audit roadmap: schema-level cleanups + observability honesty.
_strategy diagnostic field stripped from every public dataset row at push time (was previously emitted but undeclared in dataset_schema.json). The aggregate strategy distribution stays available in last-run-summary.output.strategies.last-run-summary now distinguish pushed (rows in the dataset) from charged (rows successfully billed via PPE). On runs with zero charge failures these two numbers are identical; when they diverge it is a real revenue-leak signal worth investigating.dataset_schema.json:fields now declares nullable types (["string","null"] etc.) for every field that the runtime can actually emit as null (winery, vivino_url, appellation, average_rating, price, alcohol, image_url, wineId, vintageId, inputSource, shipTo, vintage, wine_description, taste_profile, reviews, searchQuery). Clients that validate the schema against the rows no longer get type-mismatch warnings.key_value_store_schema.json now embeds a full jsonSchema for the last-run-summary blob so the Apify Console auto-documents the structure and any future shape drift in the code is caught.Sprint 4 of the post-audit roadmap: observability + documentation.
last-run-summary at the end of every run. Captures timing, input shape, strategy distribution, cache stats, and resilience counters. Useful for offline drift detection and capacity planning.key_value_store_schema.json declares the last-run-summary collection so the Apify Console surfaces it next to OUTPUT.error / errorMessage fields, the diagnostic _strategy field, and the Key-Value Store run summary. Includes a sample error row and a sample summary blob.Note: adoption of the speculative /api/wines/{id} JSON endpoint (originally on the Sprint 4 plan) was deferred to a dedicated research sprint - the endpoint shape needs validation against the live Vivino API with debug-tagged probes before going to production.
Sprint 3 of the post-audit roadmap.
Actor.pushData(item, 'wine-result') shortcut (Apify v3.4+). Closes the brief push-without-charge gap that existed when push and charge were separate calls.WINERY_SUFFIXES constant out of the per-entry loop in processWineEntries.exploreToScrapedWine export and its 11 tests; deleted the unused SearchPageResult interface.scripts/canary-vivino.sh runs the live Actor against a 3-wine canary input (one per strategy) and asserts that core fields are still present. Designed to be wired as a daily Apify scheduled task for early detection of Vivino API/HTML drift.Sprint 2 of the post-audit roadmap: Phase 4 hygiene + 2 quality fixes + diagnostic field.
NODE_ENV=production and uses npm ci against a committed package-lock.json (reproducible installs).actor.json metadata updated post TypeScript migration (templateId is now ts-empty, minMemoryMbytes bumped from 128 to 256 for Node 22 + cheerio reliability, defaultRunOptions now pins build: latest and memoryMbytes: 512).searchQuery, inputSource, error, errorMessage, scrapedAt.winery now returns null (instead of the placeholder 'Unknown') when extraction fails on a successful row. This restores parity with the JS monolith and stops the downstream quality filter from treating 'Unknown' as a real producer name. Error rows still use 'Unknown' for display._strategy field (url, s1, s2-discovered-slug, s2-entries, error) so operators can trace which code path produced each result. Diagnostic-only - safe to ignore in client integrations._strategy smoke).Post-promotion hotfix surfaced by the 5-audit batch (apify-scraper-builder + apify-monetization-expert + scraper-audit-expert + scraping-expert + code-reviewer + code-simplifier).
_food_pairings private taste-profile field no longer leaks into the public dataset; it is now stripped after enrichment.food_pairings correctly backfills from the taste profile when the API result lacked it (parity with the JS monolith).taste_profile and reviews are now omitted from the dataset row when the user opts out (previously shipped as explicit null).searchMode: name_only now actually disables vintage extraction (previously declared in the input schema but ignored by the code).wineNames and wineUrls legacy fields are now declared in the input schema (still merged with wines at runtime).WINERY_PREFIXES, stripAccents) now imported from the canonical modules.htmlToScrapedWine accepts a fallbackName option, removing post-construction mutation in processWineEntries.extractMaxFloat and extractMaxInt consolidated into a single generic extractMax helper.Full TypeScript rewrite preserving the original scraping methodology.
average_rating is no longer silently 0 when Vivino has rated the wine. The HTML rating extractor was looking for a field name (average_rating) that Vivino does not use in its inline data; the actual field is ratings_average (plus wine_ratings_average for wine-level fallback). When extraction failed, the output reported average_rating: 0 together with a non-zero ratings_count, suggesting a real "zero star" rating that did not exist. The scraper now scans the correct field names (with the legacy spelling as a last-chance fallback) and prefers wine-level rating when the vintage-level rating is unavailable. Fields with no rating data return average_rating: null so consumers can distinguish "unrated" from "actually zero".NSG, Gds, VV, BLC, RGE, 1er, P.C., G.C., CDP, CDR, SGN, VT, MC (monopole) are expanded to their full form (Nuits-Saint-Georges, Grandes, Vieilles Vignes, Blanc, Rouge, Premier, Premier Cru, Grand Cru, Chateauneuf-du-Pape, Cotes du Rhone, Selection de Grains Nobles, Vendanges Tardives, Monopole) so the quality filter recognizes them in Vivino result names. Recovers previously-rejected wines such as Mugneret Gerard NSG Aux Cras (now matches Nuits-Saint-Georges 1er Cru 'Aux Cras').AOC, AOP, IGP, VDF, VDP, DOC, IGT, and others) and 4-digit years are now stripped from the search query. They are derived from the vintage field already, so leaving them in the search text just polluted Vivino's matcher and confused the quality filter into rejecting good results. Knock-on effect: previously-rejected wines like Clos de la Hutte (Thibaud Boudignon Savennières) and Marc Kreydenweiss Clos du Val D'Eléon should now match.Fils, Fille, Frères, Père) are now treated as non-distinctive when comparing the query against a match. This stops false rejections on wines like Boulard & Fille Les Murgiers and Dehours & Fils Grande Réserve.Champagne Blanc., L'Alsace., La Corse., Le Rhône Septentrional., La Côte Chalonnaise et le Mâconnais. — have that prefix removed automatically. The remaining text is what gets searched on Vivino, so the producer and wine name become the leading tokens (e.g. Franck Pascal Fluence Brut Nature instead of Champagne Blanc. S.A. Franck Pascal "Fluence" Brut Nature 50). Substantially improves match rate on wine-list-style catalog exports.Champagne Blanc. S.A. Franck Pascal "Fluence" Brut Nature 50<TAB>NV) are now parsed correctly: the description column is used as the search query, the vintage column accepts both years and NV, and stray catalog elements are stripped before searching: curly quotes (""''), legal-entity markers (S.A., SCEA, SARL, SAS, EARL, GAEC`), and a trailing price.Jean-Claude Bachelet, Chassagne-Montrachet, La Boudriotte Rouge, the scraper could previously return a wine from Jean-Claude Ramonet because the first two words ("jean", "claude") matched. The validator now also requires the producer's family name (last significant word in the winery) to appear in the query.Domaine des Comtes Lafon, Meursault Premier Cru, Charmes) are now correctly tokenized, restoring matches that were previously rejected by the validator due to trailing characters attached to words. Expected effect: significantly higher extraction success rate on real catalog inputs.winery field, which also disabled the downstream quality filter and let unrelated wines be returned. The filter now activates correctly on these cases and rejects results whose distinctive query words do not appear in the matched wine. Side effect: fewer null prices in the output, since most of the missing prices came from these mismatched results.ACTOR_MAX_TOTAL_CHARGE_USD setting users can configure in Run options to cap per-run spending.error and errorMessage dataset fields documented as null on success.wines field prefill in the Console form now showcases the 6 accepted input shapes pedagogically: wine name only, name with vintage, Vivino URL (canonical), Vivino URL with ?year= parameter, scheme-less Vivino URL (auto-prefixed with https://), and Vivino URL with locale path (/fr/). Helps users discover the breadth of accepted formats without reading the docs.wineUrls + wineNames with a single wines array that auto-routes URLs and names by shape. Mix freely; the actor handles routing.maxResultsPerSearch (now hardcoded to 1 -- best match only) and proxyConfig (was unused).sectionCaption/sectionDescription keys. All inputs are visible without expanding sections.wineUrls and wineNames keys still work silently. Existing scheduled tasks and API integrations continue running without change. No deprecation warning.## Is it legal to scrape Vivino? canonical H2 (hiQ Labs reference, GDPR caveat for EU review data, Apify blog link)## Support & feedback closing block at end of README with Issues tab linkactor.json title, and seoTitle (was 3 different forms)seoTitle$49/month → $29/month (~9,600 wines/month)console.apify.com/settings/integrations now includes ?fpr=mrbridgeetc. from L49 wine-type listing and from dataset_schema.json wine_type descriptionPromise.all with Promise.allSettled in dual-search (with/without shipTo) and enrichment (taste+reviews) so a transient Vivino failure on one fetch no longer drops the whole wine. Charge errors now logged as warnings with a per-run counter exposed in the final status message (silent revenue loss becomes observable).reviews field omitted when includeReviews: false, taste_profile and food_pairings omitted when includeTasteProfile: false. Eliminates empty columns in exported data.fetchHtml), global rate limit cooldown shared across all conc