# Yelp Business Leads & Reviews Scraper (`scrapers_lat/yelp-scraper`) Actor

Scrape Yelp business listings by keyword and location. Get name, address, phone, website, categories, rating, review count, price level, hours and review highlights, plus optional AI lead scoring. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/scrapers\_lat/yelp-scraper.md
- **Developed by:** [Scrapers Lat](https://apify.com/scrapers_lat) (community)
- **Categories:** Lead generation, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $37.82 / 1,000 business results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

[![Yelp Business Leads & Reviews Scraper](https://scrapers.lat/banners/yelp-scraper.png)](https://console.apify.com/actors/8qQlb5CU2y3Eoof8D/input)

## Yelp Business Leads & Reviews Scraper

Here is one real result, with every field the actor returns:

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "businessName": "Capital City Plumbing and Drain",
  "alias": "capital-city-plumbing-and-drain-leander",
  "yelpUrl": "https://www.yelp.com/biz/capital-city-plumbing-and-drain-leander",
  "categories": ["Water Heater Installation/Repair", "Plumbing"],
  "primaryCategory": "Water Heater Installation/Repair",
  "rating": 4.8,
  "reviewCount": 231,
  "priceLevel": null,
  "address": "180 Antlers Trail",
  "neighborhoods": [],
  "serviceArea": null,
  "phone": "(512) 630-0852",
  "isAd": true,
  "rankPosition": 2,
  "website": "http://capitalcityplumbing.services",
  "hours": [
    "Mon Open 24 hours", "Tue Open 24 hours", "Wed Open 24 hours",
    "Thu Open 24 hours", "Fri Open 24 hours", "Sat Open 24 hours", "Sun Open 24 hours"
  ],
  "verifiedLicense": true,
  "photoCount": 48,
  "businessDescription": "The pros at Capital City Plumbing & Drain are ready to take care of all your commercial plumbing needs. Our commercial plumber in Austin, TX can complete repair and remodeling projects of all sizes...",
  "reviewHighlights": ["Get pricing & availability."],
  "reviewHighlightCount": 1,
  "aiLeadScore": 85,
  "aiLeadTier": "Hot",
  "aiLeadRationale": "High rating and review count indicate strong customer satisfaction and visibility.",
  "source": "yelp.com",
  "observedAt": "2026-08-20T01:18:47.544Z"
}
```

The most complete Yelp business scraper available. It returns every listing field Yelp exposes for a search (name, categories, rating, review count, price level, address, neighborhoods and phone), plus an optional detail pass that adds website, opening hours, verified license, photo count, business description and review highlights, plus an optional AI lead score, and gives you six filters to target exactly the businesses you need.

**📥 [Input](https://apify.com/scrapers_lat/yelp-scraper/input-schema) · 📤 [Output](https://apify.com/scrapers_lat/yelp-scraper/output-schema) · 💰 [Pricing](https://apify.com/scrapers_lat/yelp-scraper/pricing) · ▶️ [Examples](https://apify.com/scrapers_lat/yelp-scraper/examples)**

![Apify](https://img.shields.io/badge/Platform-Apify-1CE1CE?logo=apify\&logoColor=white)
![Coverage](https://img.shields.io/badge/Coverage-Yelp-red)
![Output](https://img.shields.io/badge/Output-JSON%20%7C%20CSV%20%7C%20Excel-orange)
![Billing](https://img.shields.io/badge/Billing-Pay%20per%20result-brightgreen)

### Table of contents

- [What it does](#what-it-does)
- [Quickstart](#quickstart)
- [Input reference](#input-reference)
- [Output reference](#output-reference)
- [Example output record](#example-output-record)
- [Run via API and CLI](#run-via-api-and-cli)
- [Fetch results](#fetch-results)
- [Billing and limits](#billing-and-limits)
- [FAQ and troubleshooting](#faq-and-troubleshooting)

### What it does

Give the actor one or more search terms (a category or business type) and one or more locations (city and state, or a ZIP code). It runs each term in each location on Yelp, paginates the search results, and writes one normalized record per business to the run dataset. Every business comes back with its name, Yelp URL, categories, star rating, review count, price level, address, neighborhoods and phone when Yelp lists it.

Two optional add-ons enrich each business further:

- **Contact enrichment** opens each business page and adds the phone, website, opening hours by day, verified license flag, photo count, business description and review highlights. This is the lead data most people want. It is off by default and charged only when a phone or website is found.
- **AI lead score** rates each business as a sales prospect from 0 to 100, assigns a tier (Hot, Warm, Cold) and gives a one-line rationale. Off by default, charged only when a usable score is returned.

Missing values are returned as `null`, never invented. Anti-bot handling is fully internal, so you do not configure proxies or supply any login.

### Quickstart

Open the actor, paste this into the input, and press Run. It returns the 10 top coffee shops in Seattle.

```json
{
  "searchTerms": ["coffee"],
  "locations": ["Seattle, WA"],
  "maxBusinesses": 10,
  "sortBy": "Most Reviewed"
}
```

To get full contact details and AI lead scores, add the two add-ons (a paid Apify plan is required for add-ons):

```json
{
  "searchTerms": ["plumbers", "electricians"],
  "locations": ["Austin, TX"],
  "maxBusinesses": 50,
  "withContacts": true,
  "withLeadScore": true
}
```

### Input reference

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `searchTerms` | array of strings | yes | `["plumbers"]` | Categories or business types to search. Each term is searched in each location. |
| `locations` | array of strings | yes | `["Austin, TX"]` | Places to search: city and state, or a ZIP code. Each location is searched with every term. |
| `maxBusinesses` | integer | no | `10` | Maximum businesses to collect across the whole run (all terms and locations combined). Free plans are capped at 10. |
| `sortBy` | enum | no | `Most Reviewed` | Result order: `Recommended`, `Highest Rated`, `Most Reviewed`, or `Distance`. |
| `priceLevels` | array of strings | no | `["1","2"]` | Keep only these price levels: `1` = $, `2` = $$, `3` = $$$, `4` = $$$$. Empty for all. |
| `openNow` | boolean | no | `false` | Only return businesses open at run time. |
| `minRating` | integer | no | `0` | Keep only businesses rated at least this many stars (1 to 5). `0` disables the filter. |
| `withContacts` | boolean | no | `false` | Paid add-on, off by default. Fetch each business page for phone, website, hours, license, photos, description and review highlights. Charged only on a phone or website hit. |
| `withLeadScore` | boolean | no | `false` | Paid add-on, off by default. AI lead score, tier and rationale per business. Charged only on a usable score. |

Terms and locations combine as a cross product: two terms and two locations run four searches. `withContacts` and `withLeadScore` are disabled on free Apify plans.

### Output reference

One dataset item per business. Types: `string`, `number`, `integer`, `boolean`, `string[]`, or `null` when a value is absent.

| Field | Type | Description |
|---|---|---|
| `searchTerm` | string | Search term that produced this business. |
| `location` | string | Location that was searched. |
| `businessName` | string | Business name. |
| `alias` | string | Yelp business alias (URL slug). |
| `yelpUrl` | string | Full Yelp business page URL. |
| `categories` | string\[] | All Yelp categories for the business. |
| `primaryCategory` | string | First listed category. |
| `rating` | number | Star rating, 1 to 5 (may be `0` for some sponsored listings). |
| `reviewCount` | integer | Number of reviews. |
| `priceLevel` | string | Price level `$` to `$$$$`, or `null`. |
| `address` | string | Street address as listed, or `null`. |
| `neighborhoods` | string\[] | Neighborhoods, when listed. |
| `serviceArea` | string | Service area text for mobile or at-home businesses, or `null`. |
| `phone` | string | Phone number. Filled from the search listing, and from the detail page when contact enrichment runs. |
| `isAd` | boolean | Whether the listing was returned in a sponsored slot. |
| `rankPosition` | integer | Position of the business in the collected result set. |
| `website` | string | Business website (contact enrichment). `null` otherwise. |
| `hours` | string\[] | Opening hours by day (contact enrichment). |
| `verifiedLicense` | boolean | Yelp verified business license (contact enrichment). |
| `photoCount` | integer | Number of photos on the business page (contact enrichment). |
| `businessDescription` | string | Business self-description (contact enrichment). |
| `reviewHighlights` | string\[] | Top review highlight quotes (contact enrichment). |
| `reviewHighlightCount` | integer | Number of review highlights captured. |
| `aiLeadScore` | integer | AI lead score 0 to 100 (AI add-on). |
| `aiLeadTier` | string | AI lead tier: `Hot`, `Warm`, or `Cold` (AI add-on). |
| `aiLeadRationale` | string | One-line rationale for the score (AI add-on). |
| `source` | string | Always `yelp.com`. |
| `observedAt` | string | ISO 8601 timestamp when the record was collected. |
| `error` | string | `null` on success. On a failed run a single item with a populated `error` field is written instead. |

### Example output record

Real record from a live run (input `{"searchTerms":["plumbers"],"locations":["Austin, TX"],"maxBusinesses":3,"withContacts":true,"withLeadScore":true}`):

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "businessName": "Radiant Plumbing & Air Conditioning - Austin",
  "alias": "radiant-plumbing-and-air-conditioning-austin-austin",
  "yelpUrl": "https://www.yelp.com/biz/radiant-plumbing-and-air-conditioning-austin-austin",
  "categories": ["Plumbing", "Heating & Air Conditioning/HVAC", "Water Heater Installation/Repair"],
  "primaryCategory": "Plumbing",
  "reviewCount": 849,
  "address": "901 Reinli St",
  "phone": "(512) 690-4932",
  "website": "https://radiantplumbing.com/austin/",
  "hours": ["Mon Open 24 hours", "Tue Open 24 hours", "Wed Open 24 hours", "Thu Open 24 hours", "Fri Open 24 hours", "Sat Open 24 hours", "Sun Open 24 hours"],
  "verifiedLicense": true,
  "photoCount": 128,
  "reviewHighlights": [
    "came out the next day and was very thorough and efficient in fixing the marked-up areas.",
    "I would highly recommend Radiant to anyone - Ian, Woody, Joe, and the install crew are top-notch!"
  ],
  "reviewHighlightCount": 3,
  "aiLeadScore": 85,
  "aiLeadTier": "Hot",
  "aiLeadRationale": "High review volume and positive feedback indicate strong customer satisfaction and visibility.",
  "source": "yelp.com",
  "observedAt": "2026-08-20T01:19:35.003Z"
}
```

### Run via API and CLI

Start a run and read the dataset. Replace `<TOKEN>` with your Apify API token.

Run synchronously and get dataset items in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~yelp-scraper/run-sync-get-dataset-items?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["coffee"],"locations":["Seattle, WA"],"maxBusinesses":25,"sortBy":"Most Reviewed"}'
```

Start a run asynchronously with the paid add-ons:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~yelp-scraper/runs?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["dentists"],"locations":["Miami, FL"],"maxBusinesses":100,"withContacts":true,"withLeadScore":true}'
```

Apify CLI:

```bash
apify call scrapers_lat/yelp-scraper \
  --input '{"searchTerms":["law firms"],"locations":["Chicago, IL"],"maxBusinesses":50}'
```

### Fetch results

Every run writes to a dataset. Fetch items as JSON, CSV, or Excel by changing `format`:

```bash
## JSON
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=json"

## CSV
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=csv"

## Paginate large datasets
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&offset=1000&limit=1000"
```

`<DATASET_ID>` is returned as `defaultDatasetId` in the run object. Use `offset` and `limit` to page through large result sets.

### Billing and limits

- **Pay per result.** You are charged one `result` event per business returned. A one-time `actor-start` event is charged when a run begins.
- **Add-ons are opt-in.** Contact enrichment (`contacts`) and AI lead score (`ai_lead_score`) are off by default. Each is charged only when it produces data: `contacts` when a phone or website is found, `ai_lead_score` when the AI returns a usable score. Both are disabled on free Apify plans.
- **No charge on failure.** If a run errors or matches nothing, the actor writes a single item with a populated `error` field and does not charge `result` or any add-on. Empty runs cost nothing.
- **Spend cap respected.** Set `maxTotalChargeUsd` on the run; once reached, the actor stops emitting and charging further billable results.
- **Free Apify plans** are capped at 10 businesses per run and cannot use the paid add-ons. Upgrade for higher `maxBusinesses`.
- **Tiered pricing.** Per-event prices step down across Apify plan tiers. See the [pricing tab](https://apify.com/scrapers_lat/yelp-scraper/pricing) for the current rates.

### FAQ and troubleshooting

**A run returned 0 businesses. Why?**
The term and location combination matched nothing, or the location was not recognized. Try a broader term, a nearby larger city, or a `City, ST` format. Zero-result runs are not charged.

**Why is `phone` or `website` empty on some records?**
Yelp does not always list a phone in search results, and `website` is only filled when contact enrichment is enabled and the business has one. Businesses without a public phone or website return `null` for those fields.

**Why does `rating` show `0` on some businesses?**
A few sponsored listings return a `0` rating in the search feed even though they have reviews. `reviewCount` is still accurate. Enable contact enrichment for the fuller profile.

**How do I get emails and full contact details?**
Enable `withContacts`. It adds phone, website, opening hours, license, photo count, description and review highlights from each business page. It is charged only when a phone or website is found.

**How is the AI lead score calculated?**
When `withLeadScore` is on, the actor sends the business profile (categories, rating, review volume, reachability) to an AI model that returns a 0 to 100 score, a tier and a one-line rationale. It is charged only when a usable score comes back.

**Do I need a proxy or a Yelp login?**
No. Anti-bot handling is fully internal. You never configure a proxy or supply any cookies or credentials.

**Is this an official Yelp tool?**
No. This actor is independent and not affiliated with Yelp. It reads only data that is publicly visible on Yelp business and search pages.

### Related scrapers

- [Website Contacts Scraper](https://apify.com/scrapers_lat/website-contacts-scraper): emails, phones and socials from any website.
- [Google Maps and business scrapers at scrapers.lat](https://scrapers.lat): local business leads across platforms.

### More scrapers at scrapers.lat

Built and maintained by [scrapers.lat](https://scrapers.lat), where we publish scrapers for US and Latin American public platforms: company registries, government data, finance, e-commerce and more. Browse the catalog or request a custom scraper at [scrapers.lat](https://scrapers.lat).

***

> Independent tool, not affiliated with Yelp. Accesses only publicly available Yelp data. Use in accordance with Yelp's terms of service.

# Actor input Schema

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

One or more things to search on Yelp, for example a category or business type (plumbers, coffee, dentists, law firms). Each term is searched in each location.

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

One or more places to search, for example a city and state or a ZIP code (Austin, TX / San Francisco, CA / 10001). Each location is searched with every term.

## `maxBusinesses` (type: `integer`):

Maximum number of businesses to collect across the whole run (all terms and locations combined). Free Apify plans are capped at 10 per run.

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

Result order returned by Yelp.

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

Filter to specific price levels: 1 = $, 2 = $$, 3 = $$$, 4 = $$$$. Leave empty for all price levels.

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

Only return businesses that are open at the time of the run.

## `minRating` (type: `integer`):

Only keep businesses with at least this star rating (1 to 5). Leave at 0 for no rating filter.

## `withContacts` (type: `boolean`):

Fetch each business detail page to add phone, website, opening hours, review highlights, photo count, verified license and description. Charged only when a phone or website is found. Disabled on free plans.

## `withLeadScore` (type: `boolean`):

Use AI to score each business as a sales lead (0 to 100), assign a tier and give a one-line rationale. Charged only when a usable score is returned. Disabled on free plans.

## Actor input object example

```json
{
  "searchTerms": [
    "plumbers"
  ],
  "locations": [
    "Austin, TX"
  ],
  "maxBusinesses": 10,
  "sortBy": "Recommended",
  "priceLevels": [],
  "openNow": false,
  "minRating": 0,
  "withContacts": false,
  "withLeadScore": false
}
```

# Actor output Schema

## `results` (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": [
        "plumbers"
    ],
    "locations": [
        "Austin, TX"
    ],
    "maxBusinesses": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapers_lat/yelp-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": ["plumbers"],
    "locations": ["Austin, TX"],
    "maxBusinesses": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("scrapers_lat/yelp-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": [
    "plumbers"
  ],
  "locations": [
    "Austin, TX"
  ],
  "maxBusinesses": 10
}' |
apify call scrapers_lat/yelp-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapers_lat/yelp-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/8qQlb5CU2y3Eoof8D/builds/pnYqQdF0Bc7fZA5Ji/openapi.json