# Yelp Business Scraper (`cirkit/yelp-business-scraper`) Actor

Fast Yelp business scraper. Search by location and keyword or scrape direct Yelp business URLs. Extracts name, address, phone, website, hours, photos, ratings, review count, price tier, categories, and claimed status. Direct read of Yelp's server-rendered Apollo data, no headless browser.

- **URL**: https://apify.com/cirkit/yelp-business-scraper.md
- **Developed by:** [Crikit](https://apify.com/cirkit) (community)
- **Categories:** Lead generation, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 Scraper

Fast Yelp business scraper. Search by location and keyword, or paste direct Yelp URLs. Returns clean, structured records with name, address, phone, website, hours, photos, ratings, review count, price tier, categories, and claimed status. No headless browser, no Yelp API key, no login required.

### What does Yelp Business Scraper do?

Yelp Business Scraper is an Apify actor that extracts business listings from Yelp.com programmatically. It reads Yelp's server-rendered Apollo data directly, so you get the same data Yelp's own pages show - but as clean JSON.

Use it to:

- Build lead lists for local-marketing agencies.
- Pull restaurant or hospitality datasets for analytics or AI training.
- Run real-estate site selection (which categories cluster where).
- Monitor competitors' Yelp ratings, review counts, and claimed status.
- Backfill phone numbers, websites, and hours into a CRM.

### How to use Yelp Business Scraper

There are two input modes; you can combine them in one run.

#### Search mode

Provide `searchTerms` (e.g. `["pizza", "tacos"]`) and `locations` (e.g. `["San Francisco, CA", "Brooklyn, NY"]`). The scraper runs one search per (term, location) pair and paginates through results up to `maxResults` (default 50, Yelp's hard ceiling is 240).

Optional filters:

- `categoryAlias` - Yelp category slug like `pizza`, `restaurants`, `autorepair`. Stricter than the free-text term.
- `priceFilter` - array of `1`, `2`, `3`, `4` (mapping to `$`, `$$`, `$$$`, `$$$$`).
- `sortBy` - `recommended` (default), `rating`, or `review_count`.

#### Direct URL mode

Provide `directUrls` with Yelp business URLs like `https://www.yelp.com/biz/pink-onion-san-francisco`. Each is scraped as a detail page. Useful when you already have a list of businesses to enrich.

#### Detail enrichment

Set `enrichWithDetails: true` (default) to fetch each business's full detail page. Without enrichment you get name, alias, rating, review count, price tier, categories, and a thumbnail photo. With enrichment you also get phone, website, hours, lat/lng, address components, photos, properties (delivery, reservations, etc.), and claimed status.

### How many businesses can Yelp Business Scraper return?

Yelp itself caps a single search at **240 results**. To pull a bigger market, split into smaller `locations` (neighborhoods or ZIP codes) and re-run.

### Output

One record per business. Example shape:

```json
{
  "encid": "IxDRIBkKtP-f24sr5zHAhQ",
  "alias": "pink-onion-san-francisco",
  "url": "https://www.yelp.com/biz/pink-onion-san-francisco",
  "name": "Pink Onion",
  "rating": 4.5,
  "reviewCount": 1383,
  "priceRange": "$$",
  "phoneNumber": "+14155292635",
  "website": "http://www.pinkonionpizza.com",
  "address": {
    "addressLine1": "64 14th St",
    "city": "San Francisco",
    "regionCode": "CA",
    "postalCode": "94103",
    "country": "US",
    "formatted": "64 14th St\nSan Francisco, CA 94103"
  },
  "latitude": 37.7687698,
  "longitude": -122.414829,
  "timezone": "America/Los_Angeles",
  "categories": [
    {"alias": "pizza", "title": "Pizza"},
    {"alias": "italian", "title": "Italian"}
  ],
  "photos": [
    {"encid": "...", "url": "https://...", "caption": "..."}
  ],
  "hours": [
    {"dayOfWeek": "Monday", "regularHours": ["4:00 PM - 10:00 PM"]}
  ],
  "properties": [
    {"alias": "RestaurantsReservations", "displayText": "Takes reservations", "isActive": true}
  ],
  "isClaimed": true,
  "isClosed": false,
  "isYelpAdvertiser": true,
  "isWomenOwned": false,
  "isBlackOwned": false,
  "byAppointmentOnly": false,
  "hasStorefrontAddress": true
}
````

Records can be downloaded from the run's dataset in JSON, JSONL, CSV, XLSX, or HTML.

### How much does Yelp Business Scraper cost?

Flat fee of $0.004 per business record (`$4 per 1,000`). No actor-start fee. Pay only for what you keep.

That undercuts the $5 to $15 per 1,000 charged by incumbent Yelp scrapers while shipping full detail enrichment by default.

### Tips for scraping Yelp

- Split big markets into smaller `locations`. Yelp caps a single search at 240. Three smaller searches return more total businesses than one big one.
- Run with `enrichWithDetails: false` to scout a market quickly, then re-run on the alias list with `enrichWithDetails: true` only on the ones worth full enrichment.
- Use `categoryAlias` when you know exactly the Yelp category you want - search-term matching is fuzzy and includes adjacent categories.
- The actor uses Apify residential proxies by default; that's the right setting for sustained scraping. Datacenter works for tiny runs but trips DataDome quickly.

### Is it legal to scrape Yelp?

Personal data is protected by GDPR in the European Union and similar regulations elsewhere. This actor extracts business directory data (commercial entities, not individuals). Yelp's Terms of Service prohibit scraping; operators should verify their own compliance posture. See Apify's blog on [whether web scraping is legal](https://blog.apify.com/is-web-scraping-legal/) for general guidance.

### Feedback

Found a bug? Open an issue from the actor's Issues tab in Apify Console. Pull requests welcome on the source repository.

# Actor input Schema

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

Search query strings (e.g. 'pizza', 'plumber', 'dentist'). One business search per term, per location.

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

Free-text Yelp locations (city + state, ZIP, neighborhood). Yelp resolves to a geo center.

## `categoryAlias` (type: `string`):

Optional Yelp category alias to filter by (e.g. 'pizza', 'restaurants', 'autorepair'). When set, scraper uses the strict category endpoint instead of the free-text search.

## `directUrls` (type: `array`):

List of Yelp business URLs to scrape directly (e.g. https://www.yelp.com/biz/pink-onion-san-francisco). Bypasses search.

## `maxResults` (type: `integer`):

Cap on total businesses per (searchTerm, location) pair. Yelp itself caps results at 240.

## `enrichWithDetails` (type: `boolean`):

When true, the scraper hits each business's detail page to pull website, hours, photos, properties, and full address. Adds time + transfer.

## `maxImagesPerBusiness` (type: `integer`):

Upper bound on photo URLs returned per business. Only applies when enrichWithDetails=true.

## `priceFilter` (type: `array`):

Filter to Yelp price tiers. Empty means all tiers.

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

How Yelp orders results before scraping.

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

US Residential proxies are required for sustained scraping. Datacenter works for small runs.

## Actor input object example

```json
{
  "searchTerms": [
    "pizza"
  ],
  "locations": [
    "San Francisco, CA"
  ],
  "categoryAlias": "",
  "directUrls": [],
  "maxResults": 20,
  "enrichWithDetails": true,
  "maxImagesPerBusiness": 10,
  "priceFilter": [],
  "sortBy": "recommended",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset of Yelp business records.

## `datasetCsv` (type: `string`):

Same dataset rendered as CSV.

# 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": [
        "pizza"
    ],
    "locations": [
        "San Francisco, CA"
    ],
    "maxResults": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("cirkit/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": ["pizza"],
    "locations": ["San Francisco, CA"],
    "maxResults": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

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

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": [
    "pizza"
  ],
  "locations": [
    "San Francisco, CA"
  ],
  "maxResults": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call cirkit/yelp-business-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=cirkit/yelp-business-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Yelp Business Scraper",
        "description": "Fast Yelp business scraper. Search by location and keyword or scrape direct Yelp business URLs. Extracts name, address, phone, website, hours, photos, ratings, review count, price tier, categories, and claimed status. Direct read of Yelp's server-rendered Apollo data, no headless browser.",
        "version": "0.1",
        "x-build-id": "nGAaVP6xTpxE5HRwG"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/cirkit~yelp-business-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-cirkit-yelp-business-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/cirkit~yelp-business-scraper/runs": {
            "post": {
                "operationId": "runs-sync-cirkit-yelp-business-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/cirkit~yelp-business-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-cirkit-yelp-business-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "searchTerms": {
                        "title": "Search Terms",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Search query strings (e.g. 'pizza', 'plumber', 'dentist'). One business search per term, per location.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "locations": {
                        "title": "Locations",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Free-text Yelp locations (city + state, ZIP, neighborhood). Yelp resolves to a geo center.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "categoryAlias": {
                        "title": "Category Alias Filter",
                        "type": "string",
                        "description": "Optional Yelp category alias to filter by (e.g. 'pizza', 'restaurants', 'autorepair'). When set, scraper uses the strict category endpoint instead of the free-text search.",
                        "default": ""
                    },
                    "directUrls": {
                        "title": "Direct Yelp URLs",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "List of Yelp business URLs to scrape directly (e.g. https://www.yelp.com/biz/pink-onion-san-francisco). Bypasses search.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "Max Results Per Search",
                        "minimum": 1,
                        "maximum": 240,
                        "type": "integer",
                        "description": "Cap on total businesses per (searchTerm, location) pair. Yelp itself caps results at 240.",
                        "default": 50
                    },
                    "enrichWithDetails": {
                        "title": "Fetch Full Details Per Business",
                        "type": "boolean",
                        "description": "When true, the scraper hits each business's detail page to pull website, hours, photos, properties, and full address. Adds time + transfer.",
                        "default": true
                    },
                    "maxImagesPerBusiness": {
                        "title": "Max Images Per Business",
                        "minimum": 0,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Upper bound on photo URLs returned per business. Only applies when enrichWithDetails=true.",
                        "default": 10
                    },
                    "priceFilter": {
                        "title": "Price Tier Filter",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter to Yelp price tiers. Empty means all tiers.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "1",
                                "2",
                                "3",
                                "4"
                            ],
                            "enumTitles": [
                                "$",
                                "$$",
                                "$$$",
                                "$$$$"
                            ]
                        },
                        "default": []
                    },
                    "sortBy": {
                        "title": "Sort Order",
                        "enum": [
                            "recommended",
                            "rating",
                            "review_count"
                        ],
                        "type": "string",
                        "description": "How Yelp orders results before scraping.",
                        "default": "recommended"
                    },
                    "proxyConfiguration": {
                        "title": "Proxy Configuration",
                        "type": "object",
                        "description": "US Residential proxies are required for sustained scraping. Datacenter works for small runs.",
                        "default": {
                            "useApifyProxy": true,
                            "apifyProxyGroups": [
                                "RESIDENTIAL"
                            ],
                            "apifyProxyCountry": "US"
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```