# Yelp Business Leads Scraper — Phone, Website, Email & Ratings (`foxlabs/yelp-business-scraper`) Actor

Scrape Yelp local businesses by category, city/ZIP, search URL, or /biz/ URL. Extracts ratings, review counts, phone numbers, street addresses, hours, year established, external websites, and enriched business emails & social media links. No login required.

- **URL**: https://apify.com/foxlabs/yelp-business-scraper.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Lead generation, Marketing
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 yelp business listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

<p align="center">
  <img src="https://img.shields.io/badge/Pay--Per--Event-Businesses_%2B_Enriched_Emails-00C853?style=for-the-badge" alt="Pay-Per-Event" />&nbsp;
  <img src="https://img.shields.io/badge/Local_B2B_Leads-Phone_%C2%B7_Web_%C2%B7_6_Socials-2962FF?style=for-the-badge" alt="Local B2B Leads" />&nbsp;
  <img src="https://img.shields.io/badge/AI_Agent_Ready-MCP_%26_x402-7C4DFF?style=for-the-badge" alt="MCP & x402 Ready" />&nbsp;
  <img src="https://img.shields.io/badge/Dual_Runtime-Batch_%2B_Standby_API-FF6D00?style=for-the-badge" alt="Batch + Standby API" />
</p>

## Yelp Business Leads Scraper — Phone, Website, Email & Ratings 🚀

**foXLabs Local SMB, Reputation & Lead Generation Series:** [Google Maps Leads](https://apify.com/foxlabs/google-maps-scraper) · [Tripadvisor Reviews Scraper](https://apify.com/foxlabs/tripadvisor-reviews-scraper) · [Booking.com Hotels Scraper](https://apify.com/foxlabs/booking-hotels-scraper) · [Shopify App Store Scraper](https://apify.com/foxlabs/shopify-app-store-scraper) · [Trustpilot Reviews](https://apify.com/foxlabs/trustpilot-reviews-scraper)

🎉 Build high-converting **local SMB outbound lead lists** from any **Yelp category × city/ZIP matrix, custom Yelp search URL, or direct `/biz/` URL** — extracting **ratings, review counts, categories, phone numbers, full street & postal addresses, GPS coordinates, claim status (`isClaimed`), year established, owner names & bios, external company websites, business emails and 6 social media networks** with **zero Yelp Fusion API keys and zero browser overhead**.

Built for B2B outbound sales & SDR teams, local SEO / marketing / reputation agencies, home-services & healthcare SaaS companies, franchise expansion analysts and Clay / n8n enrichment workflows.

### 🔍 What is the Yelp Business Leads Scraper — and when should you use it?

Yelp is the premier directory of US, Canadian and international local SMBs across high-LTV verticals — dentists, med spas, roofers, HVAC contractors, plumbers, law firms, auto shops and restaurants. Yet Yelp's official Fusion API recently moved behind expensive commercial licensing tiers, caps search queries, and **never** gives you external company websites, owner bios, `isClaimed` status, business email addresses or social media profiles.

This Actor delivers a complete **two-stage local lead engine** inside a fast `256 MB` HTTP runtime:

- **Category × Location Matrix, Search URLs & Direct `/biz/` URLs** — pass `searchTerms: ["Dentist", "Med Spa"]` paired with `locations: ["Austin, TX", "Miami, FL"]` to run every combination automatically, or supply custom `searchUrls` / `businessUrls`.
- **Fast Discovery Tier (`enrichDetails: false`, `$0.0025`/lead)** — extracts organic rank, `businessId`, `name`, `yelpUrl`, `rating`, `reviewCount`, `priceRange`, `categories[]`, `primaryCategory`, `addressLine1`, `city`, `neighborhoods[]`, `yelpGuaranteed` and featured `reviewSnippet`.
- **Two-Hop Contact & Owner Enrichment (`enrichDetails: true`, `$0.0055`/lead)** —
  1. Enriches each Yelp `/biz/` profile for `phone`, unwrapped `websiteUrl`, `menuUrl`, `formattedAddress`, `postalCode`, `state`, `latitude`/`longitude`, 7-day `openingHours`, `hoursToday`, `amenities[]`, `photosCount`, `photoUrls[]`, `healthScore` / `healthViolations[]`, `reviewHighlights[]`, `isClaimed`, `isYelpAdvertiser`, `yearEstablished`, `ownerName`, `ownerRole`, `ownerBio`, `specialties` and `historyDescription`.
  2. Crawls the business's own external website (homepage + contact/about page) to extract verified `emails[]` and `socialLinks` (`instagram`, `facebook`, `linkedin`, `twitter`, `tiktok`, `youtube`).

**Use it when you need:** ready-to-dial & ready-to-email SMB prospect lists; unclaimed-listing (`isClaimed: false`) or Yelp-Ads (`isSponsored: true`) agency prospecting; territory mapping; or Clay / CRM waterfall enrichment.

**Use something else when:** you need **hundreds of paginated individual hospitality guest reviews** per restaurant/hotel (pair with [Tripadvisor Reviews Scraper](https://apify.com/foxlabs/tripadvisor-reviews-scraper) for deep paginated review histories).

### 🤖 Use with AI agents (MCP, Claude, Cursor & x402)

**Already connected to the Apify MCP server?** Ask your AI assistant to call `foxlabs/yelp-business-scraper`.

- **Hosted MCP URL (zero install):** `https://mcp.apify.com?tools=foxlabs/yelp-business-scraper`
- **Local stdio config (Claude Desktop, Cursor, Cline, Windsurf):**

```json
{
  "mcpServers": {
    "yelp-business-scraper": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--tools", "foxlabs/yelp-business-scraper"],
      "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" }
    }
  }
}
```

**Your agent can pay for its own runs.** This Actor uses mutually exclusive pay-per-event pricing (`$0.0025` per `business`, `$0.0055` per `business-detail` when contact-enriched, `$0.00` for diagnostic `status` rows) and supports autonomous settlement via **x402 (USDC on Base)** or **Skyfire** as well as standard Apify tokens.

Copy-paste prompt for Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
Use the Apify Actor `foxlabs/yelp-business-scraper` to extract local SMB business leads, phone numbers, websites, emails, social profiles, owner bios and ratings from Yelp.

Input fields:
- `searchTerms`: array of business categories/keywords (e.g. ["Dentist", "Roofing", "Med Spa"])
- `locations`: array of cities, states or ZIP codes (e.g. ["Austin, TX", "Miami, FL"])
- `searchUrls`: optional array of https://www.yelp.com/search?find_desc=... URLs
- `businessUrls`: optional array of https://www.yelp.com/biz/... URLs
- `sortBy`: "recommended" (default) | "rating" | "review_count"
- `includeSponsored`: boolean (default false) — include Yelp Ads flagged with `isSponsored: true`
- `minRating`: number 0..5 (default 0)
- `enrichDetails`: boolean (default false) — adds phone, full ZIP address, website, owner bio, emails[] & socialLinks
- `maxBusinessesPerSearch`: integer 1..240 (default 20)

Start with:
{"searchTerms":["Dentist"],"locations":["Austin, TX"],"minRating":4.0,"enrichDetails":true,"maxBusinessesPerSearch":20}
```

**Things you can ask your AI agent:**

- *"Find 30 Cosmetic Dentists and Med Spas in Austin, TX with `enrichDetails: true` and return a table of business name, ownerName, phone, websiteUrl, emails and Instagram links."*
- *"Pull HVAC and Roofing contractors in Dallas, TX with `includeSponsored: true` so we can see which companies are actively paying for Yelp Ads (`isSponsored: true`)."*
- *"Find established restaurants in Chicago (`minRating: 4.0`) that have NOT claimed their Yelp page (`isClaimed: false`)."*

The machine-readable Actor summary, MCP tool definition and schema live at `https://apify.com/foxlabs/yelp-business-scraper.md`.

### 📋 Overview

Everything needed to turn Yelp categories and ZIP codes into enriched SMB contact records — in one 46-column schema.

| Property | Details |
|---|---|
| **Public data source** | Public Yelp directories, `/biz/` pages & external company websites |
| **Authentication required** | None — zero Yelp Fusion API key, login or cookies |
| **Container footprint** | Lightweight `256 MB` HTTP runtime (fast startup, minimal compute overhead) |
| **Output row types (`rowType`)** | `business` (`$0.0025` search-tier · `$0.0055` `business-detail` when enriched), `status` (`$0.00`) |
| **Deduplication & restart safety** | Deterministic `rowKey` (`yelp:<businessId>`) across overlapping categories & ZIPs |
| **Execution modes** | Standard Batch Dataset runs + synchronous Standby HTTP API (`GET /`, `POST /scrape`) |

**Why outbound & agency teams pick this Actor:**

- 📧 **Yelp + Website Contact Enrichment in One Step** — unwraps Yelp's `/biz_redir` tracking links into clean canonical `websiteUrl` domains, then extracts `emails[]` and 6 social channels (`instagram`, `facebook`, `linkedin`, `twitter`, `tiktok`, `youtube`) directly from the business's site.
- 👤 **Decision-Maker Context (`ownerName`, `ownerBio`, `yearEstablished`)** — write hyper-personalized cold outreach referencing the founder's name, background and `yearEstablished` instead of generic templates.
- 🎯 **High-Intent Agency Signals (`isClaimed`, `isSponsored`, `yelpGuaranteed`)** — instantly segment SMBs already spending on Yelp Ads (`includeSponsored: true`) or neglecting their unclaimed profiles (`isClaimed: false`).
- 💸 **Mutually exclusive two-tier PPE** — `$0.0025` for fast directory mapping or `$0.0055` for full phone + website + email + social enrichment (never double-charged).

### ✨ Key Features

- 🧮 **Automatic `searchTerms × locations` Cartesian Matrix** — Enter 5 categories × 10 cities (`50` localized markets) in a single run; `rowKey` deduplication prevents duplicate leads across adjacent ZIP codes.
- 📞 **Complete NAP + Geo Precision** — Extracts `phone`, `addressLine1`, `addressLine2`, `city`, `state`, `postalCode`, `countryCode`, `formattedAddress`, `neighborhoods[]`, `latitude`, `longitude` and `timezone`.
- 🌐 **Smart External Website Crawler (`enrichDetails: true`)** — Visits both the SMB's homepage and discovered `/contact` or `/about` page, filtering out junk/asset strings (`sentry`, `.png`, `example.com`) so `emails[]` stays clean.
- ⚡ **Synchronous Standby API (`POST /scrape`)** — Plug directly into Clay, n8n, Make or real-time AI SDR agents.

### 🎬 Quick Start (API & Standby HTTP)

**1. Synchronous Batch API call (returns JSON array directly):**

```bash
curl -X POST "https://api.apify.com/v2/acts/foxlabs~yelp-business-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["Dentist"],"locations":["Austin, TX"],"maxBusinessesPerSearch":20,"enrichDetails":true}'
```

**2. Real-time Standby HTTP API (`POST /scrape`):**

```bash
curl -X POST "https://foxlabs--yelp-business-scraper.apify.actor/scrape?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["Med Spa"],"locations":["Miami, FL"],"enrichDetails":true,"maxBusinessesPerSearch":10}'
```

### 🚀 Getting Started (3 steps)

1. **Choose categories & locations (or paste URLs)** — Enter niches in **Search Terms** (`"Roofing"`, `"Dentist"`) and cities/ZIPs in **Locations** (`"Austin, TX"`, `"90210"`), or supply `searchUrls` / `businessUrls`.
2. **Enable contact enrichment** — Toggle **`enrichDetails: true`** to extract phone numbers, full ZIP addresses, clean company websites, owner bios, emails and social media profiles.
3. **Run & export to CRM** — Click **Start** and export your 46-column lead list directly to CSV, Excel, Clay, HubSpot, Instantly or Smartlead.

### 📥 Input & Filters

```json
{
  "searchTerms": ["Dentist", "Orthodontist"],
  "locations": ["Austin, TX"],
  "searchUrls": [],
  "businessUrls": [],
  "sortBy": "recommended",
  "priceLevels": [],
  "openNow": false,
  "includeSponsored": false,
  "minRating": 4.0,
  "enrichDetails": true,
  "maxBusinessesPerSearch": 25
}
```

| Field | Type | Default | Description |
|---|---|---|---|
| `searchTerms` | `array<string>` | `["Dentist"]` | Business categories or keywords to search on Yelp (`"Roofing"`, `"HVAC"`, `"Med Spa"`, `"Plumber"`). |
| `locations` | `array<string>` | `["Austin, TX"]` | Cities, neighborhoods, states or postal/ZIP codes paired with `searchTerms`. |
| `searchUrls` | `array<string>` | `[]` | Direct `https://www.yelp.com/search?find_desc=...` URLs with custom Yelp filters applied. |
| `businessUrls` | `array<string>` | `[]` | Direct `https://www.yelp.com/biz/...` URLs (automatically performs full `business-detail` enrichment). |
| `sortBy` | `string` | `"recommended"` | Yelp sort order: `"recommended"`, `"rating"`, or `"review_count"`. |
| `priceLevels` | `array<string>` | `[]` | Optional Yelp price filter: `"1"` (`$`), `"2"` (`$$`), `"3"` (`$$$`), `"4"` (`$$$$`). |
| `openNow` | `boolean` | `false` | Filter Yelp search results to businesses currently open. |
| `includeSponsored` | `boolean` | `false` | When `true`, keeps paid Yelp Ad placements (clearly flagged with `isSponsored: true`). |
| `minRating` | `number` | `0` | Optional minimum star rating threshold (`0` = keep all, e.g. `4.0` or `4.5`). |
| `enrichDetails` | `boolean` | `false` | Enriches each `/biz/` page + crawls external business website for `phone`, `websiteUrl`, `openingHours`, `amenities[]`, `photoUrls[]`, `healthScore`, `emails[]`, `socialLinks`, `ownerName` & `isClaimed` (`business-detail` tier). |
| `maxBusinessesPerSearch` | `integer` | `20` | Maximum businesses collected per `(searchTerm × location)` pair or `searchUrl` (`1`–`240`). |
| `proxyConfiguration` | `object` | `{"useApifyProxy": true}` | Managed automatically via Apify Proxy. |

**Copy-paste input recipes:**

- **Full outbound SDR list with phone, website, emails, socials & owner bio (`enrichDetails: true`):**
  `{"searchTerms":["Med Spa","Cosmetic Dentist"],"locations":["Austin, TX","Scottsdale, AZ"],"enrichDetails":true,"maxBusinessesPerSearch":30}`
- **Yelp Ad-spender prospecting (`includeSponsored: true`):**
  `{"searchTerms":["Roofing","HVAC","Plumbing"],"locations":["Dallas, TX","Houston, TX"],"includeSponsored":true,"enrichDetails":true,"maxBusinessesPerSearch":40}`
- **Enrich an existing list of `/biz/` URLs (`businessUrls`):**
  `{"searchTerms":[],"locations":[],"businessUrls":["https://www.yelp.com/biz/forest-family-dentistry-austin-2"]}`

### 📤 Output Schema & Real Sample Record

Each item includes `rowType` (`"business"` or free diagnostic `"status"`), `detailsEnriched` (`boolean`), and deterministic `rowKey` (`yelp:<businessId>`).

| Field Group | Fields (63 Columns Total) |
|---|---|
| **Business Identity & Rank** | `rowKey`, `rowType`, `businessId`, `alias`, `name`, `alternateNames[]`, `yelpUrl`, `rank`, `isSponsored`, `isYelpAdvertiser`, `isOnlineBusiness`, `isMultiloc`, `searchTerm`, `searchLocation`, `detailsEnriched`, `scrapedAt` |
| **Ratings, Highlights & Media** | `rating`, `reviewCount`, `priceRange`, `priceLevel`, `primaryCategory`, `categories[]`, `reviewSnippet`, `reviewHighlights[]`, `logoUrl`, `primaryPhotoUrl`, `photosCount`, `photoUrls[]` |
| **Phone, Web, Menu, Email & Socials** *(detail)* | `phone`, `websiteUrl`, `websiteDisplayUrl`, `menuUrl`, `emails[]`, `socialLinks` (`instagram`, `facebook`, `linkedin`, `twitter`, `tiktok`, `youtube`) |
| **Address & Geo** | `addressLine1`, `addressLine2` *(detail)*, `city`, `state` *(detail)*, `postalCode` *(detail)*, `countryCode` *(detail)*, `formattedAddress` *(detail)*, `neighborhoods[]`, `latitude` *(detail)*, `longitude` *(detail)*, `timezone` |
| **Hours, Amenities, Health & Owner** *(detail)* | `isClaimed`, `isClosed`, `isOpenNow`, `hoursToday`, `openingHours`, `amenities[]`, `verifiedLicenses[]`, `healthScore`, `latestHealthInspectionDate`, `healthViolations[]`, `questionsCount`, `yelpGuaranteed`, `yearEstablished`, `ownerName`, `ownerRole`, `ownerBio`, `specialties`, `historyDescription` |

#### Real sample record (from verified platform pre-publish run `ee6WBbTT1bl5dHhWW`, 2026-11-14)

```json
{
  "rowKey": "yelp:NPCQRbpaO6w0cKswP2J7ig",
  "rowType": "business",
  "businessId": "NPCQRbpaO6w0cKswP2J7ig",
  "alias": "forest-family-dentistry-austin-2",
  "name": "Forest Family Dentistry",
  "yelpUrl": "https://www.yelp.com/biz/forest-family-dentistry-austin-2",
  "isSponsored": false,
  "rank": 1,
  "rating": 4.6,
  "reviewCount": 399,
  "priceRange": null,
  "categories": [
    "Cosmetic Dentists",
    "General Dentistry",
    "Orthodontists"
  ],
  "primaryCategory": "Cosmetic Dentists",
  "phone": "(512) 334-9894",
  "websiteUrl": "https://www.forestfamily.com",
  "websiteDisplayUrl": "https://www.forestfamily.com",
  "emails": [],
  "socialLinks": {
    "instagram": "https://www.instagram.com/forestfamilydentist/",
    "facebook": "https://www.facebook.com/ForestFamilyDentistry/",
    "linkedin": "https://www.linkedin.com/company/forest-family-dentistry-pllc/",
    "twitter": null,
    "tiktok": null,
    "youtube": "https://www.youtube.com/channel/UCP4maFehPfd5w9k60JV4mLA"
  },
  "addressLine1": "2700 W Anderson Ln",
  "addressLine2": "Ste 418",
  "city": "Austin",
  "state": "TX",
  "postalCode": "78757",
  "countryCode": "US",
  "formattedAddress": "2700 W Anderson Ln, Ste 418, Austin, TX 78757",
  "neighborhoods": [],
  "latitude": 30.359461,
  "longitude": -97.734382,
  "timezone": "America/Chicago",
  "hoursToday": "8:30 AM - 5:30 PM",
  "isOpenNow": false,
  "isClaimed": true,
  "isClosed": false,
  "yelpGuaranteed": false,
  "yearEstablished": 2012,
  "ownerName": "Dentist Robin B.",
  "ownerRole": "Business Owner",
  "ownerBio": "Dr. Robin Bethell is a Whole Health dentist that sees the big picture. He built Forest Family Dentistry to make dentistry more efficient, healthy, and enjoyable in his favorite city...",
  "detailsEnriched": true,
  "scrapedAt": "2026-11-14T05:08:42.904Z"
}
```

Every run also writes a `SOURCE_REPORT` telemetry summary to the default Key-Value Store.

### 🧪 Data Quality — Measured

Verified on the Apify platform across QA runs (`t7taMjjb07OLctQ5D`, `dQ4nkGUr22s8EA2Tc`) and pre-publish live billing verification (`ee6WBbTT1bl5dHhWW` on 2026-11-14):

- **100% business uniqueness:** Deduplicated by `yelp:<businessId>` across multi-page (`&start=0, 10, 20...`) and multi-ZIP runs (`0` duplicate businesses).
- **Rich two-hop contact fidelity:** Enriched runs (`ee6WBbTT1bl5dHhWW`) populated unwrapped canonical `websiteUrl`s, formatted US/CA `phone` numbers, `formattedAddress` with `postalCode`, `latitude`/`longitude`, `isClaimed`, `ownerName`/`ownerBio` and structured 6-network `socialLinks`.
- **Verified two-tier PPE billing:** Settled `chargedEventCounts` across `business`, `business-detail` and diagnostic `status` runs matched delivered rows `100%`.

### ⏱️ Performance — Measured

Measured on the Apify platform at the default **`256 MB`** memory tier:

- **39.6 seconds for 20 Austin businesses:** Default platform run `t7taMjjb07OLctQ5D` (`Dentist` in `Austin, TX`, `20` businesses) completed cleanly in **`39.6s`** inside `256 MB` RAM.
- **Restart-safe Dataset deduplication:** Hydrates existing `yelp:<businessId>` keys on startup so container restarts never duplicate leads or repeat charges.

### 💼 Use Cases

1. **Cold Email & Cold Call SDR List Building (`enrichDetails: true`)**
   - *Input:* `{"searchTerms":["Med Spa","Plastic Surgeon"],"locations":["Miami, FL","Beverly Hills, CA"],"enrichDetails":true,"maxBusinessesPerSearch":50}`
   - *Output:* `name`, `ownerName`, `ownerBio`, `phone`, `websiteUrl`, `emails[]` and `socialLinks.instagram` / `linkedin`.
   - *Business action:* Load multi-channel sequences into Clay, Instantly or HubSpot with founder personalization in one step.

2. **Marketing Agency "Ad-Spender" Prospecting (`includeSponsored: true`)**
   - *Input:* `{"searchTerms":["Roofing","HVAC","Emergency Plumber"],"locations":["Phoenix, AZ","Dallas, TX"],"includeSponsored":true,"enrichDetails":true,"maxBusinessesPerSearch":40}`
   - *Output:* Contractors actively paying high CPCs on Yelp Ads (`isSponsored: true`) alongside their organic `rating` and `websiteUrl`.
   - *Business action:* Pitch Google Local Services Ads, CRO or AI voice receptionists to businesses with proven paid-acquisition budgets.

3. **Unclaimed Profile & Reputation Management Sales**
   - *Input:* `{"searchTerms":["Auto Repair","Chiropractor"],"locations":["Chicago, IL"],"enrichDetails":true,"maxBusinessesPerSearch":50}`
   - *Output:* Filter rows where `isClaimed == false` or `rating < 4.0` or `websiteUrl == null`.
   - *Business action:* Identify established brick-and-mortar SMBs leaving local search traffic on the table.

4. **Franchise White-Space & Competitor Density Mapping**
   - *Input:* Fast search-tier sweep (`enrichDetails: false`) across 50 metro ZIP codes.
   - *Output:* Category density, `reviewCount` leaders, `priceRange` tiers and neighborhood clusters at `$2.50 / 1,000` businesses.
   - *Business action:* Pinpoint underserved suburbs with high population growth and low 4.5-star competition.

### 🔗 Integrations (Node.js, Python, n8n, Make & Clay)

#### JavaScript / Node.js (`apify-client`)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('foxlabs/yelp-business-scraper').call({
    searchTerms: ['Dentist'],
    locations: ['Austin, TX'],
    minRating: 4.0,
    enrichDetails: true,
    maxBusinessesPerSearch: 25,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Fetched ${items.length} Yelp business leads`, items[0]);
```

#### Python (`apify-client` v3)

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("foxlabs/yelp-business-scraper").call(
    run_input={
        "searchTerms": ["Dentist"],
        "locations": ["Austin, TX"],
        "minRating": 4.0,
        "enrichDetails": True,
        "maxBusinessesPerSearch": 25,
    }
)

for item in client.dataset(run.default_dataset_id).iterate_items():
    if item["rowType"] == "business":
        print(item["name"], item["phone"], item["websiteUrl"], item["emails"])
```

*(Written for `apify-client` v3 where `call()` returns a `Run` object exposing `run.default_dataset_id`; on `apify-client` v1/v2 use `run["defaultDatasetId"]`.)*

#### n8n, Make, Zapier & Clay

- **Clay / CRM Waterfall:** Call `https://foxlabs--yelp-business-scraper.apify.actor/scrape` in Standby mode or trigger batch runs from Clay/n8n → push `websiteUrl`, `emails[]`, `phone` and `ownerName` straight into your outbound sequencer.

### 📊 Pricing (Pay-Per-Event)

Mutually exclusive two-tier **Pay-Per-Event (PPE)** pricing — pay search rates for market mapping or enriched lead rates when extracting phone, website, emails & social profiles:

| Event Name | Trigger | Price per Item | Price per 1,000 |
|---|---|---|---|
| `business` | Once per unique search-tier Yelp business (`enrichDetails: false`) | **$0.0025** | **$2.50 / 1,000** |
| `business-detail` | Once per unique contact-enriched Yelp lead (`enrichDetails: true` or `businessUrls`) | **$0.0055** | **$5.50 / 1,000** |
| `status` *(diagnostic)* | Empty input, malformed URL, or zero-match filter note | **$0.00 (Free)** | **$0.00** |

**Worked cost examples:**

- **100 search-tier businesses (`enrichDetails: false`):** `100 × $0.0025` = **$0.25**
- **100 full B2B leads with phone, website, emails, socials & owner bio (`enrichDetails: true`):** `100 × $0.0055` = **$0.55** *(never billed `business` + `business-detail` together!)*
- **1,000 full contact-enriched SMB leads:** `1,000 × $0.0055` = **$5.50**

**Billing guarantees:**

- **External website crawl is included free in `business-detail`:** Crawling the SMB's homepage + contact page for `emails[]` and `socialLinks` carries zero extra event charge beyond `$0.0055`.
- **Proxy protection included:** Managed Apify Proxy traffic is baked into the per-event price above.
- **Exact spend cap support:** Configure **Maximum cost per run** in Apify options; `ChargingManager` stops cleanly at your budget limit. *(Note: if Apify applies its platform `apify-actor-start` fee on your plan, that start event applies when a run starts, including zero-result runs.)*

### ❓ Frequently Asked Questions (FAQ)

#### Do I need a Yelp Fusion API key, Yelp account, or custom proxies?

No. Yelp's Fusion API costs hundreds of dollars per month at commercial tiers and still omits business emails, owner bios and social profiles. This Actor runs completely keylessly on our managed infrastructure with zero login, zero cookies and zero user-supplied proxies.

#### Why are `phone`, `websiteUrl`, `emails` and `socialLinks` empty unless `enrichDetails: true` is enabled?

Yelp's directory search cards only expose summary fields (`name`, `yelpUrl`, `rating`, `reviewCount`, `categories`, `addressLine1`, `city`, `neighborhoods`, `reviewSnippet`). Full `phone`, unwrapped external `websiteUrl`, `postalCode`, `latitude`/`longitude`, `isClaimed` and `ownerName`/`ownerBio` live on each business's `/biz/` page, and `emails[]` + `socialLinks` live on the company's external website. Enable `"enrichDetails": true` (`$5.50 / 1K`) or pass `businessUrls` whenever building outbound contact lists.

#### Where do `emails[]` and `socialLinks` come from?

Yelp does not publish business email addresses on `/biz/` pages. When `enrichDetails: true` is active and the Yelp listing links to an external company website (`websiteUrl`), the Actor automatically fetches the company's homepage and discovered `/contact` or `/about` page, extracts `mailto:` and visible business email addresses (filtering out asset/tracker noise), and captures official `instagram`, `facebook`, `linkedin`, `twitter`, `tiktok` and `youtube` links.

#### Why is `emails[]` empty (`[]`) on some enriched businesses that have a `websiteUrl`?

Many medical, dental and home-service websites use web contact forms or appointment widgets (like NexHealth, Calendly or ServiceTitan) without publishing a raw `info@` or `office@` email address in HTML. Even when `emails` is `[]`, you still receive the direct `phone`, clean `websiteUrl` domain (ready for permutation/SMTP waterfall tools in Clay/Apollo), `ownerName` and active `socialLinks`.

#### How does Yelp's `240`-result cap per search query work — and how do I scale past `240` leads in a major metro?

Yelp caps any single `(category × city)` search pagination at `24` pages (`240` organic results). To extract `1,000+` plumbers, dentists or restaurants across Los Angeles, New York or Houston, split `locations` into **ZIP codes or neighborhoods** (for example `["78701", "78704", "78745", "78757", "78759"]`). The Actor runs every `(searchTerm × ZIP)` pair and deduplicates overlapping businesses automatically via `yelp:<businessId>`.

#### How are Yelp `/biz_redir` tracking links handled?

On Yelp `/biz/` pages, external website links are wrapped inside `yelp.com/biz_redir?url=...` redirect URLs. The Actor automatically decodes and strips Yelp's redirect wrapper so `websiteUrl` always contains the clean destination URL (e.g., `"https://www.forestfamily.com"`).

#### What does `includeSponsored: true` do?

By default (`includeSponsored: false`), paid "Sponsored Result" placements on Yelp search pages are skipped so `rank` reflects pure organic ranking. Setting `includeSponsored: true` includes advertisers and marks them with `isSponsored: true` — a top-performing agency signal for identifying local businesses already spending money on paid lead generation.

#### How do I enrich only a specific list of `businessUrls` without running `"Dentist"` in `"Austin, TX"`?

Clear the prefilled **Search Terms** and **Locations** arrays in Console (or pass `"searchTerms": [], "locations": []` in JSON) alongside `"businessUrls": ["https://www.yelp.com/biz/..."]`. Direct `businessUrls` automatically run full `business-detail` contact enrichment.

#### Does Yelp cover countries outside the United States?

Yes. In addition to all 50 US states and Canada, Yelp maintains active local business directories across the UK, Germany, France, Spain, Italy, Australia, Japan and dozens of other countries — just pass the international city name in `locations` (e.g., `"Toronto, ON"`, `"London, UK"`, `"Munich, Germany"`).

#### Am I ever billed both `business` and `business-detail` for the same company?

Never. Billing is strictly mutually exclusive: each unique `businessId` triggers either `business` (`$0.0025` when `enrichDetails: false`) or `business-detail` (`$0.0055` when `enrichDetails: true` or via `businessUrls`) — and external website crawling for emails & social media links is included at zero extra charge inside `business-detail`.

#### Can I call this Actor synchronously from Clay, n8n or an AI agent?

Yes. Connect via `https://mcp.apify.com?tools=foxlabs/yelp-business-scraper` for zero-install MCP tool calling in Claude, Cursor or custom AI SDR agents, or send synchronous HTTP `POST` requests to `https://foxlabs--yelp-business-scraper.apify.actor/scrape` in Apify Standby mode for direct JSON responses inside Clay or n8n.

#### Is the Actor idempotent across container migrations and restarts?

Yes. On startup, the Actor inspects the active run's Dataset, hydrates all previously delivered `yelp:<businessId>` keys into memory, and skips any business already emitted before a container migration or restart — ensuring zero duplicate leads and zero repeat PPE charges.

### 🐛 Troubleshooting

- **`phone`, `websiteUrl` and `emails` are `null` / `[]`:** You ran fast discovery mode (`enrichDetails: false`). Set `"enrichDetails": true` to enrich `/biz/` pages and crawl company websites.
- **Dataset contains only `rowType: "status"` (`EMPTY_INPUT`):** Provide at least one `searchTerms` + `locations` pair, `searchUrls` item, or `businessUrls` item.
- **Default `"Dentist"` / `"Austin, TX"` ran alongside `searchUrls` or `businessUrls`:** Pass `"searchTerms": [], "locations": []` when running URL-only inputs.
- **Need more than `240` leads in one city:** Break `locations` into individual ZIP codes or neighborhoods; `yelp:<businessId>` deduplication handles overlaps automatically.

### 🚧 What It Does Not Do

- Does **not** paginate full multi-page customer review histories per Yelp business (`reviewSnippet` captures the featured highlight; use [Tripadvisor Reviews Scraper](https://apify.com/foxlabs/tripadvisor-reviews-scraper) for deep paginated hospitality reviews).
- Does **not** guess or fabricate personal emails not published on the business's own website.
- Does **not** submit "Request a Quote" forms or message Yelp businesses.

### ⚠️ Trademark Notice

This Actor is an independent data-collection tool built by **foXLabs** and is not affiliated with, endorsed by, or sponsored by Yelp Inc. "Yelp" is a registered trademark of Yelp Inc., referenced solely to describe compatibility with publicly accessible web pages.

### ⚖️ Is It Legal to Scrape Public Yelp Business Listings?

This Actor collects publicly published business directory listings, corporate contact details and public company website links visible to unauthenticated visitors — without logging into accounts or bypassing authentication. When using business contact information (`emails[]`, `phone`, `ownerName`) for B2B outreach, ensure compliance with CAN-SPAM, GDPR/PECR, CASL and TCPA rules in your target jurisdictions.

### 🤝 Support, Custom Data & Contact

- 🌐 **Website & full portfolio:** [data.foxlabs.com.tr](https://data.foxlabs.com.tr)
- 📧 **Custom data & enterprise inquiries:** info@foxlabs.com.tr
- 🐛 **Bug reports & feature requests:** open an issue in the Actor's **Issues** tab on Apify Store (include your Run ID)
- 🧰 **Browse all foXLabs Actors:** [apify.com/foxlabs](https://apify.com/foxlabs)

### Changelog

#### 0.1.3 (2026-11-14)

- Added `priceLevels` (`$`–`$$$$`) and `openNow` search filters and expanded the dataset from 46 to 63 columns (`openingHours`, `amenities[]`, `photosCount`, `photoUrls[]`, `logoUrl`, `menuUrl`, `priceLevel`, `isYelpAdvertiser`, `isOnlineBusiness`, `isMultiloc`, `alternateNames[]`, `verifiedLicenses[]`, `healthScore`, `latestHealthInspectionDate`, `healthViolations[]`, `reviewHighlights[]`, `questionsCount`) with zero PPE price increase.

#### 0.1.2 (2026-11-14)

- Upgraded Store README to full SIÁN standard with MCP & x402 AI agent configuration, Standby HTTP `POST /scrape` examples, real platform dataset sample & QA metrics, worked PPE cost breakdowns, and expanded 12-question FAQ.

#### 0.1.0 (2026-11-13)

- Initial release of `foxlabs/yelp-business-scraper` supporting `searchTerms × locations`, `searchUrls` and `businessUrls`, two-hop `/biz/` + external website email/social enrichment, and Batch + Standby HTTP modes.

# Changelog

This Actor's version history is a separate document: https://apify.com/foxlabs/yelp-business-scraper/changelog.md

# Actor input Schema

## `searchTerms` (type: `array`):

Business categories or keywords to search on Yelp (e.g. 'Dentist', 'Roofing', 'HVAC', 'Med Spa', 'Plumber').

## `locations` (type: `array`):

Locations paired with searchTerms (e.g. 'Austin, TX', 'Miami, FL', '90210').

## `searchUrls` (type: `array`):

Optional direct Yelp search URLs (https://www.yelp.com/search?find_desc=...).

## `businessUrls` (type: `array`):

Optional direct Yelp business URLs (https://www.yelp.com/biz/...) for full phone, website, hours, amenities, and email enrichment.

## `sortBy` (type: `string`):

Sort order for Yelp searches.

## `priceLevels` (type: `array`):

Optional Yelp price tiers to filter by: '1' ($), '2' ($$), '3' ($$$), '4' ($$$$).

## `openNow` (type: `boolean`):

When enabled, filters Yelp search results to businesses currently open.

## `includeSponsored` (type: `boolean`):

Include sponsored Yelp ads alongside organic businesses (ads are flagged with isSponsored: true).

## `minRating` (type: `number`):

Optional minimum Yelp star rating filter (e.g. 4.0 or 4.5). Set 0 for all.

## `enrichDetails` (type: `boolean`):

Fetches each business's /biz/ page for phone, full street/ZIP address, 7-day opening hours, amenities, photo gallery, menu URL, health score, owner bio, external website, and crawls the business website for email addresses and social links. Billed at the business-detail tier.

## `maxBusinessesPerSearch` (type: `integer`):

Maximum number of businesses to collect per search pair or search URL.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. Automatically uses Apify Unblocker for Yelp and free Datacenter proxies for external business websites.

## Actor input object example

```json
{
  "searchTerms": [
    "Dentist"
  ],
  "locations": [
    "Austin, TX"
  ],
  "searchUrls": [],
  "businessUrls": [],
  "sortBy": "recommended",
  "priceLevels": [],
  "openNow": false,
  "includeSponsored": false,
  "minRating": 0,
  "enrichDetails": false,
  "maxBusinessesPerSearch": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `sourceReport` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "Dentist"
    ],
    "locations": [
        "Austin, TX"
    ],
    "maxBusinessesPerSearch": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("foxlabs/yelp-business-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": ["Dentist"],
    "locations": ["Austin, TX"],
    "maxBusinessesPerSearch": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/yelp-business-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "Dentist"
  ],
  "locations": [
    "Austin, TX"
  ],
  "maxBusinessesPerSearch": 20
}' |
apify call foxlabs/yelp-business-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,foxlabs/yelp-business-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/4EEFJj7D3AweHIAFA/builds/cmWfyzjpOrTCFq2FI/openapi.json
