# Yelp Scraper | Business Details & Reviews (`danthedataman/yelp-business-review-ledger`) Actor

Export Yelp business URLs as contact details and customer reviews. Filter reviews by rating, language, dates or text; include available media and owner replies.

- **URL**: https://apify.com/danthedataman/yelp-business-review-ledger.md
- **Developed by:** [Eli J](https://apify.com/danthedataman) (community)
- **Categories:** Lead generation, Automation, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.24 / 1,000 reviews

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/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

### What you can export

Use this **Yelp business and reviews scraper** for known-business research and feedback analysis. Supply public Yelp business URLs to export contact details and customer reviews, with available media, reactions and owner replies.

Choose details, reviews or both, then apply review filters. Business discovery by keyword or location is outside this product; an export is not an archive of deleted or non-recommended reviews.

### Try the example input

```json
{
  "businessUrls": [
    {
      "url": "https://www.yelp.com/biz/prince-street-pizza-new-york-2"
    }
  ],
  "maxReviewsPerBusiness": 10
}
```

The schema prefill is exactly this example. API callers must supply their own business URLs: `{}` exits successfully with guidance and produces no rows. Mobile and regional URLs are accepted, including query strings; identity is resolved from the URL path. Query filters on an input URL are ignored: set the explicit review filters below. Strings such as `"https://www.yelp.ca/biz/a-business-toronto"` are also accepted in the array.

### Input

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `businessUrls` | array | empty | Yelp `/biz/<slug>` URLs, either strings or objects with `url`. No automatic business list. |
| `mode` | string | `detailsAndReviews` | `detailsAndReviews`, `details`, or `reviews`. |
| `maxReviewsPerBusiness` | integer | 100 | Maximum matching unique review rows per business. `-1` means all available; `0` means no reviews. Prefill is 10. Business rows do not count toward this cap. |
| `sortBy` | string | `recommended` | `recommended`, `newest`, `oldest`, `highest`, `lowest`, or `elites`. |
| `language` | string | `en` | Review language code, such as `en` or `fr`. Empty string reads every language reported by Yelp. |
| `ratings` | array | empty | Integers from 1 to 5. Empty array includes all star ratings. |
| `keywords` | array | empty | Up to five words or phrases, matched as case-insensitive literal substrings of original full text; at least one must match. |
| `dateFrom` | string | unset | Inclusive business-local creation date, `YYYY-MM-DD` or a relative period such as `30 days`, `2 months`, `1 year`. |
| `dateTo` | string | unset | Inclusive business-local creation date, with the same date syntax. |
| `translateTo` | string | empty | Target language code for source translation, such as `en` or `fr`. Original text is always retained. |
| `includeAuthor` | boolean | false | Include source-supplied public reviewer/profile and owner identity fields. |

Relative periods use the run's UTC date. Months and years subtract calendar months and clamp to the month's last day. Dates apply to the review creation timestamp, not the user-specified experience time. Zero, empty arrays, empty language and false are preserved. Duplicate business URL paths are read only once, even when hosts or query strings differ.

For example, to export recent low-star reviews in every language:

```json
{
  "businessUrls": ["https://www.yelp.com/biz/prince-street-pizza-new-york-2"],
  "mode": "reviews",
  "maxReviewsPerBusiness": 100,
  "sortBy": "newest",
  "language": "",
  "ratings": [1, 2],
  "dateFrom": "30 days"
}
```

### Output

The default dataset contains one `business` row per successfully read business in details modes, followed by `review` rows in review modes. Reviews include the same business metadata in `business`, so review-only exports keep contact details and rating distributions. JSON retains nested fields. The dataset view shows identity, text, rating, date and contacts. Download JSON/CSV/Excel from the dataset or use the `results` output link.

Illustrative values below show the row shape; they are not a claim about a live business's current rating or reviews.

```json
[
  {
    "recordType": "business",
    "businessId": "abcdefghijklmnopqrstuv",
    "alias": "example-cafe-city",
    "name": "Example Café",
    "businessUrl": "https://www.yelp.com/biz/example-cafe-city",
    "sourceUrl": "https://www.yelp.com/biz/example-cafe-city",
    "scrapedAt": "2026-10-06T00:00:00Z",
    "phone": "+1 555 0100",
    "website": "https://example.com",
    "address": "Example Street, Example City",
    "location": null,
    "categories": [],
    "price": "$$",
    "rating": 4.2,
    "reviewCount": 15,
    "ratingDistribution": {"1": 1, "2": 1, "3": 2, "4": 3, "5": 8},
    "reviewLanguages": [],
    "hours": null,
    "isClosed": false,
    "claimability": null,
    "serviceArea": null,
    "primaryPhoto": null,
    "attributes": [],
    "alternateNames": [],
    "summary": null,
    "closedUntil": null,
    "aboutTheBusiness": {"specialties": null, "history": null},
    "properties": [],
    "healthInspections": [],
    "advertiser": null,
    "verifiedLicenses": null,
    "verified": null,
    "scrapeStartedAt": "2026-10-05T23:59:55Z",
    "scrapeFinishedAt": "2026-10-06T00:00:00Z"
  },
  {
    "recordType": "review",
    "businessId": "abcdefghijklmnopqrstuv",
    "businessName": "Example Café",
    "business": {},
    "businessUrl": "https://www.yelp.com/biz/example-cafe-city",
    "sourceUrl": "https://www.yelp.com/biz/example-cafe-city",
    "scrapedAt": "2026-10-06T00:00:00Z",
    "reviewId": "example-review-id",
    "reviewUrl": "https://www.yelp.com/biz/example-cafe-city?hrid=example-review-id",
    "text": "An illustrative full review.",
    "translatedText": null,
    "language": "en",
    "rating": 4,
    "date": "2026-10-05T12:00:00-04:00",
    "timeOfExperience": null,
    "author": null,
    "photos": [],
    "videos": [],
    "ownerResponse": null,
    "reactions": {},
    "feedback": [],
    "tags": null,
    "previousReviews": [],
    "latestReviewUpdate": null,
    "appreciation": null,
    "earnedExpertRecognition": null
  }
]
```

Business metadata includes source address/country/coordinates, categories, price, phone, direct website, current and special opening hours, closure/claim status, service areas, primary photo, selected source attributes, visible alternate names, summary, specialties/history/year established, organized amenities/properties and health inspections. `ratingDistribution` maps star labels `1` through `5` to source totals. `reviewLanguages` reports source language/count pairs. These totals describe Yelp's business, not the filtered export.

`advertiser` is Yelp's `isYelpAdvertiser` flag, including false; null means it was absent. `verifiedLicenses` retains the source's verified license-number records; an empty array means Yelp returned none, and null means the field was absent. `verified` is true when that source list is non-empty, false when empty and null when absent; it describes verified licenses, separately from claimed ownership. These values also appear inside each review's `business`.

`scrapeStartedAt` and `scrapeFinishedAt` are UTC timestamps measured by this Actor immediately before URL resolution and after the initial business data read. They measure the business read, including retries, and exclude review pagination and dataset delivery. `scrapedAt` equals the finish time. Reviews retain the same business read timestamps inside `business`; review `date` remains the source's creation time. Business highlights are not supplied by the measured source documents and are not inferred.

Review `date` is the exact source business-local creation timestamp with its offset. `timeOfExperience` retains the separate source value, including integer timestamps. `tags` retains source metadata such as first-review and check-in flags. Photo/video objects retain source URLs, captions and dimensions when present. `ownerResponse` contains reply ID, full text, date and optional owner data. `reactions` maps source reaction names to counts; `feedback` retains each reaction's type, count and source displayText label. `previousReviews`, updates, appreciation and recognition retain source-provided metadata. Missing source values are null or empty collections; they are not invented. Public author statistics/profile/photo fields are included only when `includeAuthor` is true. When false, author/owner/uploader/user objects are removed recursively, while review text and reply text remain.

### Pagination, reliability and limits

The Actor reads 20 reviews per source cursor page. With `language: ""`, it explicitly paginates each language Yelp reports. Date and rating sorts merge the language feeds. Recommended and elite sorts preserve Yelp order within each language, visiting the default returned language first; Yelp supplies no cross-language relevance/elite rank. A finite cap can therefore end before every language is visited in those two sorts. “All available” means the source's available feeds, excluding deleted, removed or non-recommended reviews; it is not an archive or a guarantee that source totals stay constant during a run.

Repeated cursors, empty continuations and continuation pages with no new review IDs are reported as incomplete history in `ERRORS`.

Regional/mobile URL syntax is supported. Live URL resolution was measured on 30 businesses across the US, UK, Canada and Czech Republic; other regions are accepted but not separately proven. Menus, dishes and full business galleries are outside the details/reviews scope. This Actor fetches live source data; Yelp may change or block its delivered interfaces.

Requests try Apify datacenter egress first, then up to ten fresh residential sessions for blocked, rate-limited, invalid or failed responses. Successful sessions expire after 50 seconds or 24 requests. Residential proxy use is automatic when needed and adds platform cost. There is no customer proxy setup, login or browser requirement.

Errors never enter the dataset. Handled errors appear in the key-value store's `ERRORS` record and the `errors` output link. A later page failure can leave valid delivered rows with incomplete history; check `ERRORS` before treating an export as complete. All inputs failing with no rows fails the run; clean empty results and empty input succeed. Date/text filtering may require reading extra source pages and can cost more than an unfiltered export. Only matching unique review rows are delivered.

Invalid input options, including impossible dates or a reversed date range, exit successfully with `ERRORS` and guidance before source requests. Check that record even when the run status is successful. Businesses with no reviews retain a null rating and zero rating-distribution counts.

### Billing

Business rows use the `business` pay-per-event unit; review rows use `review`. Rows are delivered individually. This Actor runs at up to 1 GB of memory and charges one `apify-actor-start` event at $0.00005 per run. At the launch FREE-tier prices, event charges for ten review rows with no business row total $0.00250: ten `review` events at $0.000245 plus one start event. One business row with ten review rows adds one `business` event at $0.00010, for $0.00260 in event charges. Reaching the maximum charge stops further delivery, pages and businesses immediately. Failed requests and error records are not result events. Platform compute, transfer and any residential proxy usage remain visible in the run's usage. The Store pricing tab is the authority for the final unit prices.

# Changelog

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

# Actor input Schema

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

Public Yelp /biz/<slug> URLs. Strings or objects with url are accepted. Query strings are ignored for identity.

## `mode` (type: `string`):

Business details and reviews, details only, or reviews only.

## `maxReviewsPerBusiness` (type: `integer`):

-1 reads all available matching reviews; 0 emits no reviews. Positive values cap matching review rows per business.

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

Yelp source order. With all languages, date/rating sorts merge language feeds; recommended/elites group feeds by language.

## `language` (type: `string`):

Language code, such as en or fr. Empty string reads every language reported by Yelp.

## `ratings` (type: `array`):

Selected star ratings. Empty array means all ratings.

## `keywords` (type: `array`):

Up to five case-insensitive literal words or phrases; OR matching on original full text. Empty array disables this filter.

## `dateFrom` (type: `string`):

Inclusive business-local date: YYYY-MM-DD or relative period, such as 30 days, 2 months, 1 year.

## `dateTo` (type: `string`):

Inclusive business-local date: YYYY-MM-DD or relative period. Relative periods are anchored to the run UTC date.

## `translateTo` (type: `string`):

Target language code, such as en or fr; empty string preserves original text without requesting translation.

## `includeAuthor` (type: `boolean`):

Include source-supplied public author/profile fields and owner identity. Disabled by default; full review text and reply text remain.

## Actor input object example

```json
{
  "businessUrls": [
    {
      "url": "https://www.yelp.com/biz/prince-street-pizza-new-york-2"
    }
  ],
  "mode": "detailsAndReviews",
  "maxReviewsPerBusiness": 10,
  "sortBy": "recommended",
  "language": "en",
  "ratings": [],
  "keywords": [],
  "translateTo": "",
  "includeAuthor": false
}
```

# Actor output Schema

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

No description

## `errors` (type: `string`):

Handled request failures, when present; never result rows.

# 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 = {
    "businessUrls": [
        {
            "url": "https://www.yelp.com/biz/prince-street-pizza-new-york-2"
        }
    ],
    "maxReviewsPerBusiness": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("danthedataman/yelp-business-review-ledger").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 = {
    "businessUrls": [{ "url": "https://www.yelp.com/biz/prince-street-pizza-new-york-2" }],
    "maxReviewsPerBusiness": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("danthedataman/yelp-business-review-ledger").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 '{
  "businessUrls": [
    {
      "url": "https://www.yelp.com/biz/prince-street-pizza-new-york-2"
    }
  ],
  "maxReviewsPerBusiness": 10
}' |
apify call danthedataman/yelp-business-review-ledger --silent --output-dataset

```

## MCP server setup

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

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/IJrogGaCsmBOa6DwQ/builds/0gKwUm2xLcchHowdt/openapi.json