| Field | Type | Required | Description |
|---|---|---|---|
startUrls | array of strings | No | One or more The Knot marketplace URLs. Paste category + city URLs (/marketplace/wedding-photographers-new-york-ny) or individual vendor profile URLs. Leave empty to use the structured inputs below. |
maxItems | integer | No | Free plans cap at 10. Paid plans up to 1,000,000. |
category | enum | No | Vendor category slug (25 options). Used with city + stateCode when startUrls is empty. |
city | string | No | Lowercase hyphenated city (new-york, los-angeles, chicago). |
stateCode | enum | No | Two-letter US state code (50 states + DC). |
sort | enum | No | recommended (default), featured, popular, newest, rating. |
includeDetails | boolean | No | Visit every vendor's profile page to pull phone, email, website, socials, full bio, awards. Slower (one extra request per vendor) but much richer. |
| #### ๐ Wedding planners and coordinators - Build short-lists by city, category, and review threshold - Track who is Best of Weddings or Hall of Fame in your market - Compare price bands across rival vendors - Maintain a private vendor CRM with phone and email | #### ๐ฑ Wedding-tech SaaS and marketplaces - Power a vendor-directory feature with rich profile cards - Seed a new region with thousands of vendors in one run - Refresh photos, ratings, and review counts on a schedule - A/B test recommendation models on a real-world directory |
| #### ๐ฃ Local vendor marketing - Generate lead lists by category, city, and tier - Find non-claimed vendors to pitch claim-and-promote services - Build a competitor scoreboard with award counts and review velocity - Spot under-promoted vendors with high ratings but low impressions | #### ๐งช Researchers and journalists - Pricing-band distributions across markets - Award concentration analysis (who holds Hall of Fame status) - Diversity and ownership-attribute breakdowns per metro - Longitudinal coverage of vendor churn and rating drift |
| #### ๐ Research and academia - Empirical datasets for papers, thesis work, and coursework - Longitudinal studies tracking changes across snapshots - Reproducible research with cited, versioned data pulls - Classroom exercises on data analysis and ethical scraping | #### ๐จ Personal and creative - Side projects, portfolio demos, and indie app launches - Data visualizations, dashboards, and infographics - Content research for bloggers, YouTubers, and podcasters - Hobbyist collections and personal trackers |
| #### ๐ค Non-profit and civic - Transparency reporting and accountability projects - Advocacy campaigns backed by public-interest data - Community-run databases for local issues - Investigative journalism on public records | #### ๐งช Experimentation - Prototype AI and machine-learning pipelines with real data - Validate product-market hypotheses before engineering spend - Train small domain-specific models on niche corpora - Test dashboard concepts with live input |
error field describing the cause (proxy block, timeout, malformed URL). The Actor keeps going so one bad URL never stops the whole run. Listings and profile-page enrichment are retried up to four times with exponential backoff before being marked as an error row.
/marketplace/{category}-{city}-{state}, e.g. /marketplace/florists-chicago-il. New York, Los Angeles, Chicago, Miami, Austin, Dallas, Atlanta, Seattle, Boston, and all 50 states plus DC are covered. Smaller towns often map to the nearest metro area.
includeDetails to true and the Actor fetches each vendor's profile page to pull phone, email, website, social handles, the full bio, and category-specific facets. The trade-off is one extra request per vendor.
city, state, and serviceArea but leave address and postalCode empty by design. That is source behaviour, not a scraper bug.
priceMin and priceMax come straight from the vendor's published range. Some vendors publish a single starting price (no upper bound, so priceMax is null). The startingPriceRange field is The Knot's quintile band ($, $$, $$$, $$$$, $$$$$) in its raw text form. Both are the values shown to couples on the live site.
BOW2024, BOW2025, BOW2026 are the Best of Weddings winner for that year. BOWHOF is Hall of Fame status (awarded after multiple Best of Weddings wins). The two booleans isBestOfWeddings and isHallOfFame flag the current-year winner and Hall of Fame status respectively.