Yelp Real-Time Data — Live Business Intelligence Scraper

Turn Yelp into structured JSON — search results, full contact profiles, reviews, photos, category listings, events, and arbitrary URL scraping. Enable features with checkboxes — Business Search is on by default. One feature runs per start (if multiple are checked, highest priority wins). Every row is tagged with featureType so agents, CRMs, and data pipelines can filter without guessing.

Built for lead generation, local SEO, reputation monitoring, market research, and real-time data feeds — with optional email enrichment from business websites and 40+ data fields per business.

---

Why teams choose this Actor

• Rich, join-friendly JSON — identity, contact, location, reputation, operations, and media in one canonical schema
• Eight specialized modes — search, details, reviews, photos, category browse, URL scraper, events, full pipeline
• Checkbox UX — enable only what you need; Business Search on by default; one feature per run
• Lead-gen ready — phone, E.164 phone, website, resolved URL, optional email, completeness score
• Filter-rich — Yelp-native filters on requests + post-scrape filters before save
• Apify-native — API, schedules, webhooks, dataset views, CSV/Excel export
• Agent & MCP friendly — documented input/output contracts below for LLM tool use

---

Use cases

Use case	Enable	What you get
B2B lead lists	enableBusinessSearch + searchEnrichContacts	Businesses with phone, website, rating, address; optional email from website
One-click lead gen	enableFullPipeline	Search → full contact profile (+ optional reviews) in one run
CRM enrichment	enableBusinessDetails	Deep profile for known Yelp URLs: hours, amenities, social links
Outbound sales prospecting	enableBusinessSearch + filterPreset: lead_gen	Pre-filtered rows: phone required, min rating, email enrichment
Local SEO audits	enableBusinessDetails or enableCategoryBrowse	Claimed status, hours, categories, review counts, completeness score
Competitor mapping	enableCategoryBrowse or enableBusinessSearch	All businesses in a category + geo with filters
Reputation monitoring	enableBusinessReviews	Paginated review text with business contact embedded on each row
Sentiment & NLP pipelines	enableBusinessReviews	Star rating, date, author, text, keyword filters
Brand / visual audit	enableBusinessPhotos	Photo URLs, captions, dates, categories
Event marketing	enableEvents	Local events by city or URL with date/category filters
Ad-hoc research	enableScrapeByUrl	Paste any Yelp URL — auto-detects page type
Data warehouse / lake	Any enabled feature	Stable featureType + ISO timestamps for incremental loads
AI agent workflows	Any enabled feature	Structured input schema + typed output rows (see below)

---

Data richness — what each business row can include

When data exists on Yelp (and optionally the business website for email), business-facing rows populate fields from this canonical profile:

Identity & links

Field	Type	Description
name	string	Business name
bizId	string | null	Yelp slug ID (from URL)
encBizId	string | null	Encoded ID for joins / GraphQL
url	string	Yelp page URL
yelpProfileUrl	string | null	Canonical profile URL
categories	string[]	All category labels
primaryCategory	string | null	Main category
description	string | null	About / snippet text

Contact (high value for lead gen)

Field	Type	Description
phone	string | null	Display phone
phoneE164	string | null	Normalized E.164
website	string | null	Raw website (may be Yelp redirect)
websiteFinal	string | null	Dereferenced external URL
email	string | null	From website enrichment when enabled
emailSource	string | null	website, jsonld, or mailto
socialLinks	object[]	Platform + URL pairs

Location

Field	Type	Description
address	object | null	Structured: street, city, state, zip, country, formatted
neighborhood	string | null	Neighborhood name
city, state, zip, country	string | null	Flat address parts
coordinates	object | null	{ latitude, longitude }

Reputation

Field	Type	Description
rating	number | null	Average stars (1–5)
reviewCount	number | null	Total reviews
priceRange	string | null	$ – $$$$
ratingDistribution	object | null	Star histogram (details mode)
isClaimed	boolean | null	Profile claimed by owner
isClosed	boolean | null	Permanently closed flag

Operations & media (details mode)

Field	Type	Description
hours	object[]	Day, open, close, overnight
isOpenNow	boolean | null	Computed open status
amenities	string[]	Highlights / amenities
serviceArea, paymentMethods	various	When available
photoUrls, logoUrl, menuUrl	string | null	Media and menu links
imageUrl	string | null	Primary listing image

Meta (every row)

Field	Type	Description
featureType	string	Which mode produced the row — filter on this
locale	string	Region code (e.g. US)
scrapedAt	string	ISO-8601 collection time
dataCompletenessScore	number	0–100 based on populated fields

Email is not on Yelp profiles. Enable includeEmailFromWebsite: true to scan contact/about pages (bounded, no LLM).

---

Input schema (for APIs, agents, and MCP tools)

Rule: Enable one feature checkbox per run (enableBusinessSearch is on by default). If multiple are checked, priority is: Pipeline → Details → Reviews → Photos → Category → Scrape → Events → Search.

Feature checkboxes

Field	Default	Feature
enableBusinessSearch	true	Keyword + location search
enableBusinessDetails	false	Full profiles for /biz/... URLs
enableBusinessReviews	false	Paginated reviews
enableBusinessPhotos	false	Photo galleries
enableCategoryBrowse	false	Category + location listings
enableScrapeByUrl	false	Any Yelp URL (auto-detect)
enableEvents	false	Event listings
enableFullPipeline	false	Search → enrich → optional reviews

Global fields (all modes)

Console form order: General → feature sections (checkbox each) → Contact enrichment → Result filters → Proxy (last). Region defaults to US (not exposed in the form).

Field	Type	Default	Description
maxItems	integer	10	Fallback cap when a mode-specific limit is unset
includeEmailFromWebsite	boolean	false	Crawl business website for email
emailMaxContactPages	integer	5	Max pages per website (1–10)
filterPreset	enum	"none"	lead_gen, seo_audit, high_rating, or custom
filterMinRating / filterMaxRating	number	0 / 5	Post-scrape star filter
filterRequirePhone / filterRequireWebsite / filterRequireEmail	boolean	false	Require contact fields
filterExcludeClosed	boolean	true	Drop closed businesses
filterMinCompletenessScore	integer	0	Minimum 0–100 completeness
proxyConfiguration	object	residential US	Apify Proxy — last in form; use RESIDENTIAL for Yelp

When enableBusinessSearch is true — Business Search

Field	Type	Description
searchQueries	string[]	"keyword :: location" e.g. "dentists :: Miami, FL"
searchKeywords + searchLocations	string[]	Cross-product alternative to searchQueries
searchUrls	string[]	Direct Yelp search URLs
searchMaxResultsPerQuery	integer	Max businesses per query
searchMaxPages	integer	SERP pages to crawl
searchEnrichContacts	boolean	Full Lead-Gen contact scrape per result
searchSort, searchPrice, searchOpenNow, …	various	Yelp-native SERP filters

When enableBusinessDetails is true — Business Details

Field	Type	Description
businessUrls	string[]	/biz/... URLs
businessAliases	string[]	Slug IDs
encBizIds	string[]	Encoded business IDs
includeHours, includeAmenities, includePhotos, …	boolean	Toggle detail sections

When enableBusinessReviews is true — Business Reviews

Field	Type	Description
reviewsBusinessUrls / reviewsEncBizIds	string[]	Target businesses
reviewsMaxPerBusiness	integer	Reviews per business
reviewsSortBy	enum	DATE_DESC, RATING_DESC, etc.
reviewsFilterByRating	number[]	Star subset
reviewsIncludeBusinessContact	boolean	Attach phone/website to each review row

When enableBusinessPhotos is true — Business Photos

Field	Type	Description
photosBusinessUrls / photosEncBizIds	string[]	Target businesses
photosMaxPerBusiness	integer	Photo cap
photosSortBy, photosCategory, …	various	Gallery filters

When enableCategoryBrowse is true — Category Browse

Field	Type	Description
categoryNames + categoryLocation	string / string[]	e.g. "Plumbers" + "Denver, CO"
categoryUrls	string[]	Direct category listing URLs
categoryMaxBusinesses	integer	Listing cap
categoryEnrichContacts	boolean	Lead-Gen contact per listing (slow)

When enableScrapeByUrl is true — Scrape By URL

Field	Type	Description
scrapeUrls	string[]	Any Yelp URL (search, biz, reviews, photos, category, events)
scrapeExtractType	enum	auto (default) or force a page type
scrapeMaxPages	integer	Pagination for list pages
scrapeInheritFeatureFilters	boolean	Apply result filters to scraped lists

When enableEvents is true — Events

Field	Type	Description
eventsLocation	string	City/region for event search
eventsUrls	string[]	Direct events listing URLs
eventsMaxItems	integer	Event cap
eventsDateFrom / eventsDateTo	string	Date range filters

When enableFullPipeline is true — Full Pipeline

Field	Type	Description
pipelineQueries	string[]	"keyword :: location" queries
pipelineMaxBusinesses	integer	Total businesses to enrich
pipelineFetchReviews	boolean	Also scrape reviews per business
pipelineIncludeEmail	boolean	Email enrichment during pipeline

---

Output schema (dataset rows)

Storage: Default Apify dataset — one JSON object per scraped item.

Required on every row: featureType, locale, scrapedAt, url

featureType values — use this to route rows

featureType	Enabled by	Row shape
business_search	enableBusinessSearch	Profile core + query, position, page, isAd
business_details	enableBusinessDetails, enableFullPipeline	Profile core + hours, amenities, socialLinks, …
business_reviews	enableBusinessReviews, enableFullPipeline	Review fields + optional businessName, businessPhone, …
business_photos	enableBusinessPhotos	photoId, caption, url, linked business fields
category_browse	enableCategoryBrowse	Profile core + category, categoryUrl, position
events	enableEvents	title, date, venue, description, …
scrape_by_url	enableScrapeByUrl	Wrapper: sourceUrl, detectedPageType, nested data

Dataset API views (append ?view= to dataset URL)

View	Purpose
overview	All features — name, phone, email, rating, URL
leads	CRM export — contact + completeness score
search	SERP rows only
details	Full profiles only
reviews	Review text + linked business
photos	Photo URLs
categories	Category browse
events	Event listings

Apify API example: GET /v2/datasets/{id}/items?view=leads&format=json

---

Example inputs (copy-paste for agents)

Lead generation search

{
  "enableBusinessSearch": true,
  "searchQueries": ["dentists :: Phoenix, AZ"],
  "searchMaxResultsPerQuery": 25,
  "searchEnrichContacts": true,
  "includeEmailFromWebsite": true,
  "filterPreset": "lead_gen",
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" }
}

Full profile for one business

{
  "enableBusinessSearch": false,
  "enableBusinessDetails": true,
  "businessUrls": ["https://www.yelp.com/biz/franklin-barbecue-austin"],
  "includeHours": true,
  "includeAmenities": true,
  "includeEmailFromWebsite": true
}

Reviews with business contact

{
  "enableBusinessSearch": false,
  "enableBusinessReviews": true,
  "reviewsBusinessUrls": ["https://www.yelp.com/biz/franklin-barbecue-austin"],
  "reviewsMaxPerBusiness": 50,
  "reviewsSortBy": "DATE_DESC",
  "reviewsIncludeBusinessContact": true
}

Category mapping

{
  "enableBusinessSearch": false,
  "enableCategoryBrowse": true,
  "categoryNames": ["Plumbers"],
  "categoryLocation": "Denver, CO",
  "categoryMaxBusinesses": 30,
  "filterMinRating": 4
}

One-shot pipeline

{
  "enableBusinessSearch": false,
  "enableFullPipeline": true,
  "pipelineQueries": ["dentists :: Phoenix, AZ"],
  "pipelineMaxBusinesses": 20,
  "pipelineIncludeEmail": true,
  "pipelineFetchReviews": false
}

Scrape any Yelp URL

{
  "enableBusinessSearch": false,
  "enableScrapeByUrl": true,
  "scrapeUrls": [
    "https://www.yelp.com/biz/example-business-city",
    "https://www.yelp.com/search?find_desc=coffee&find_loc=San+Francisco%2C+CA"
  ],
  "scrapeExtractType": "auto"
}

---

How to run (Apify Console)

1. Open the Actor → Start
2. Check the feature checkbox you need — Business Search is on by default
3. Fill inputs for that mode only
4. Keep Proxy → Residential (US)
5. Run → export from Leads view or API

---

Memory recommendations

Profile	RAM	Typical workload
Light	512 MB	Search ≤25, details ≤10, no email
Standard	1024 MB	Search ≤100, email on ≤25 businesses
Heavy	2048 MB	Large review dumps, email on 100+ businesses

---

Integrating with LLMs & MCP

For tool-calling agents:

1. Enable one feature checkbox — determines which input fields are required
2. Validate required fields per mode (see Input schema above)
3. Read output from dataset; filter items where featureType matches your mode
4. Use ?view=leads when the agent needs contact columns only
5. Use dataCompletenessScore to rank rows for outreach quality

Stable join keys: encBizId or bizId or url across search → details → reviews runs (run modes separately, join in your warehouse).

Do not enable multiple modes in one run — use separate runs and merge downstream.

---

Contact & custom projects

Need a custom scraper or a web app built? I take on custom work, including:

• Web scraping / data extraction — any site, any scale (search, detail pages, contact & lead enrichment, anti-bot handling, proxies)
• Apify actors — building, optimizing, or maintaining actors
• Web apps — full-stack builds of any kind (dashboards, APIs, automation, integrations)

Reach out and let's build it:

• Email: dubem115@gmail.com
• GitHub: github.com/DrunkCodes