# Yelp Reviews API and MCP (`johnvc/yelp-reviews-api`) Actor

Scrape Yelp reviews by place ID - rating, full review text, date, reviewer name and stats, photos, owner replies, and helpful votes. Sort by date or rating, filter by stars, search within reviews, and paginate.

- **URL**: https://apify.com/johnvc/yelp-reviews-api.md
- **Developed by:** [John](https://apify.com/johnvc) (community)
- **Categories:** Developer tools, Lead generation, Integrations
- **Stats:** 12 total users, 10 monthly users, 100.0% runs succeeded, 6 bookmarks
- **User rating**: 4.06 out of 5 stars

## Pricing

from $0.01 / 1,000 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 Reviews API | Extract Ratings, Review Text & Reviewer Data (MCP-ready)

> **Paste a Yelp business URL and get clean JSON back. Star rating, full review text, date, reviewer name, location and stats, photos, owner replies, and helpful votes. Sort by date or rating, filter by stars, search within reviews, and paginate. MCP-ready for Claude, ChatGPT, Cursor, and other AI agents.**

The **Yelp Reviews API** turns any business's Yelp page into structured review data: paste the business URL straight from your browser and get back a clean JSON feed of ratings, review text, reviewer profiles, owner replies, and vote counts, with no browser automation and no captchas to solve.

Point the Actor at a business - a **Yelp business URL** (`https://www.yelp.com/biz/maman-new-york-22`), a **place ID**, or a **business alias** - and it returns that business's reviews as structured JSON: the star rating, full review text, the date, the reviewer's name, location and activity stats, attached photos, the business owner's replies, and useful/funny/cool vote counts. Sort newest-first or by rating, keep only certain star ratings, or search reviews for a keyword. Pages return up to 49 reviews each.

This is the **reviews stage** of a 3-actor Yelp suite. Find businesses with the **Yelp Search API**, fetch full profiles with the **Yelp Business Details API**, and pull reviews here. Predictable per-page pricing, structured JSON, no browsers or captchas.

***

### What this Actor returns

Each page is one dataset item containing a `reviews` array. Each review includes:

- **Rating & text** - star rating, the full review comment, and its detected language.
- **Date** - when the review was posted.
- **Reviewer** - name, location, and activity stats (friends, photos, review count).
- **Photos** - any images attached to the review.
- **Owner replies** - the business's responses to the review.
- **Feedback** - useful / funny / cool vote counts, plus tags.

***

### Use with Claude, ChatGPT, Cursor & other AI agents (MCP)

This Actor is a first-class tool on the [Apify MCP Server](https://docs.apify.com/platform/integrations/mcp). Any MCP-compatible AI agent - Claude (Desktop, Web, Code), ChatGPT, Cursor, VS Code, Cline, Windsurf, Kilo Code, Opencode, Glama - can discover and call it in natural language.

**What an AI agent does with this:**

> User: *"Summarize the 1-star reviews for this restaurant on Yelp."*
>
> Agent resolves the business to a place ID via the Yelp Search API, calls this Actor with `{"place_id": "ED7A7vDdg8yLNKJTSVHHmg", "rating": "1", "sort_by": "date_desc", "max_pages": 2}`, and summarizes the complaints.

New to Claude? [Claude Code](https://claude.ai/referral/uIlpa7nPLg) (free trial) and [Claude Cowork](https://claude.ai/referral/uIlpa7nPLg) (free trial), which runs in the Claude desktop app, both come with a free trial.

#### Quick setup - Claude Desktop

Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server"],
      "env": {
        "APIFY_TOKEN": "YOUR_APIFY_API_TOKEN"
      }
    }
  }
}
```

Restart Claude Desktop, then ask something like *"What do recent Yelp reviewers say about the service here?"*

#### Quick setup - Cursor / VS Code / Cline / Windsurf

These editors support **dynamic tool discovery**, so after the first call this Actor is registered as a named tool for the rest of the session. Point your MCP client at:

```
https://mcp.apify.com
```

…with header `Authorization: Bearer YOUR_APIFY_API_TOKEN`. Full setup: [Apify MCP integration docs](https://docs.apify.com/platform/integrations/mcp).

#### Quick setup - ChatGPT (and other static MCP clients)

ChatGPT, Gemini CLI, and Amazon Q connect through the same `https://mcp.apify.com` endpoint and call this Actor via the generic `call-actor` tool.

***

### 💸 Pay per run with crypto (x402)

The Yelp Reviews API and MCP Actor supports agentic payments via the [x402 protocol](https://docs.apify.com/platform/integrations/x402).
AI agents and MCP clients can pay for runs in USDC (on Base) with no Apify account or API token needed:
point your agent at the [Apify MCP server](https://mcp.apify.com/?tools=actors,docs,johnvc/Yelp-Reviews-API) and it can
discover, pay for, and run this Actor autonomously. Read the
[Apify x402 announcement](https://apify.com/change-log/pay-for-apify-actors-with-x402?fpr=9n7kx3) for details.

### Use cases

- **Reputation monitoring** - track new reviews and ratings for your business or competitors.
- **Sentiment analysis** - feed review text into an LLM to surface themes and complaints.
- **Service quality tracking** - filter to 1-2 star reviews to find recurring issues.
- **Owner-response audits** - see which reviews got a reply and how fast.

***

### 🔌 Integrations: Automate Yelp Review Monitoring with the Yelp Reviews API

A single run answers one question ("what are people saying about this restaurant right now?"). The real value comes from running the Yelp Reviews API on a schedule so fresh reviews land in your stack the moment they post. See the full list of [Apify platform integrations](https://docs.apify.com/platform/integrations).

**Tasks and Schedules (the core recipe).** Save one [task](https://docs.apify.com/platform/actors/running/tasks) per business you watch (a `place_id` plus your sort and filter settings), then attach a [schedule](https://docs.apify.com/platform/schedules) from the Actor's Actions, then Schedule menu. Each run appends the latest reviews so a history builds up over time. Useful cron strings: `0 7 * * *` (daily at 7 AM), `0 */6 * * *` (every six hours), `0 9 * * 1` (Mondays). One schedule can trigger many tasks at once, so a whole portfolio of locations refreshes on the same cadence. This is the backbone of reputation monitoring: see the [Check a restaurant's Yelp reviews by API](https://apify.com/johnvc/Yelp-Reviews-API/examples/check-a-restaurants-yelp-reviews?fpr=9n7kx3) task for a ready-to-run starting point.

**n8n.** This API ships an n8n community node (see the n8n integration section below). A four-step monitor: Schedule Trigger, then the Yelp node set to Get Reviews, then a Filter on `rating` for 1 and 2 star reviews, then Slack or email.

**Make and Zapier.** The same pattern works no-code with [Make](https://docs.apify.com/platform/integrations/make) and [Zapier](https://docs.apify.com/platform/integrations/zapier): trigger on a schedule, run the Actor, route the new reviews wherever your team already works.

**Store the history (Supabase).** Send each run's reviews into a table so a review history accumulates per business. No-code: the n8n Actor node, then a Supabase node. Or in Python, flatten each page's `reviews` array and bulk-insert the rows:

```python
from apify_client import ApifyClient
from supabase import create_client

apify = ApifyClient("YOUR_APIFY_TOKEN")
supabase = create_client("YOUR_SUPABASE_URL", "YOUR_SUPABASE_KEY")

run = apify.actor("johnvc/Yelp-Reviews-API").call(run_input={
    "place_id": "ED7A7vDdg8yLNKJTSVHHmg",
    "sort_by": "date_desc",
    "max_pages": 3,
})

rows = []
for page in apify.dataset(run["defaultDatasetId"]).iterate_items():
    for r in page.get("reviews", []):
        rows.append({
            "place_id": page["search_parameters"]["place_id"],
            "rating": r["rating"],
            "date": r["date"],
            "reviewer": r["user"]["name"],
            "text": r["comment"]["text"],
            "useful": r["feedback"]["useful"],
            "has_owner_reply": len(r["owner_replies"]) > 0,
        })

supabase.table("yelp_reviews").upsert(rows).execute()
```

**MCP and AI agents.** Add the Yelp Reviews API as a tool in Claude or Cursor through the Apify MCP server so an agent can pull and summarize live reviews (see the Use with Claude, ChatGPT, Cursor section above for setup).

**Webhooks.** For anything custom, fire an [Apify webhook](https://docs.apify.com/platform/integrations/webhooks) on `ACTOR.RUN.SUCCEEDED` to push each run's dataset into your own service.

***

### Input parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `place_id` | string | **Yes** | - | The business, in whichever form you have: a full **Yelp business URL** (`https://www.yelp.com/biz/maman-new-york-22`, query strings fine), the **encoded place ID** (`ED7A7vDdg8yLNKJTSVHHmg` - the first entry of the `place_ids` array from the Yelp Search API), or the **business alias** (`maman-new-york-22`). A URL or alias is resolved automatically for one extra `place_resolved` event; an encoded ID skips that fee. |
| `sort_by` | string (enum) | No | relevance | `relevance_desc`, `date_desc`, `date_asc`, `rating_desc`, `rating_asc`, `elites_desc`. |
| `rating` | string | No | - | Filter by stars: `5` or a list like `4,5`. |
| `q` | string | No | - | Keep only reviews mentioning this keyword. |
| `hl` | string | No | `en` | Two-letter language code. |
| `not_recommended` | boolean | No | `false` | Return Yelp's not-recommended (filtered) reviews instead. Currently unavailable upstream and ignores every other filter. See [What are not-recommended reviews?](#what-are-not-recommended-reviews) |
| `yelp_domain` | string | No | `www.yelp.com` | Regional Yelp domain the business is on - e.g. `www.yelp.co.uk`, `www.yelp.fr`, `fr.yelp.ca`. Only needed for a bare alias or encoded ID; a regional business URL sets it automatically and overrides this. See [Regional Yelp domains](#regional-yelp-domains). |
| `max_pages` | integer | No | `1` | Pages to fetch (~49 reviews each). `0` = unlimited (cap 20). |

***

### Regional Yelp domains

Set `yelp_domain` when the business is on a Yelp site outside the US. 41 domains are supported. A pasted regional business URL sets it for you, so this field is only needed for a bare alias or encoded ID.

Use the full host, including the `www.` or language prefix - `www.yelp.co.uk`, not `yelp.co.uk`. A short form is accepted and expanded for you, so `yelp.co.uk` works too, but the expanded value is what gets sent. Multilingual countries have no `www` host at all: Switzerland, Belgium, Malaysia, Hong Kong, the Philippines, and Finland use a language prefix instead. An unrecognized value is ignored with a warning and the run falls back to `www.yelp.com` rather than failing.

A business alias only exists on its own regional domain, so a UK alias needs `www.yelp.co.uk` to resolve. Encoded place IDs are global and work on any domain.

| Country | `yelp_domain` values |
|---------|----------------------|
| Argentina | `www.yelp.com.ar` |
| Australia | `www.yelp.com.au` |
| Austria | `www.yelp.at` |
| Belgium | `en.yelp.be` (English), `fr.yelp.be` (French), `nl.yelp.be` (Dutch) |
| Brazil | `www.yelp.com.br` |
| Canada | `www.yelp.ca` (English), `fr.yelp.ca` (French) |
| Chile | `www.yelp.cl` |
| Czechia | `www.yelp.cz` |
| Denmark | `www.yelp.dk` |
| Finland | `fi.yelp.fi` (Finnish), `sv.yelp.fi` (Swedish) |
| France | `www.yelp.fr` |
| Germany | `www.yelp.de` |
| Hong Kong | `en.yelp.com.hk` (English), `zh.yelp.com.hk` (Chinese) |
| Ireland | `www.yelp.ie` |
| Italy | `www.yelp.it` |
| Japan | `www.yelp.co.jp` |
| Malaysia | `ms.yelp.my` (Malay), `en.yelp.my` (English) |
| Mexico | `www.yelp.com.mx` |
| Netherlands | `www.yelp.nl` |
| New Zealand | `www.yelp.co.nz` |
| Norway | `www.yelp.no` |
| Philippines | `en.yelp.com.ph` (English), `fil.yelp.com.ph` (Filipino) |
| Poland | `www.yelp.pl` |
| Portugal | `www.yelp.pt` |
| Singapore | `www.yelp.com.sg` |
| Spain | `www.yelp.es` |
| Switzerland | `de.yelp.ch` (German), `en.yelp.ch` (English), `fr.yelp.ch` (French), `it.yelp.ch` (Italian) |
| Taiwan | `www.yelp.com.tw` |
| Turkey | `www.yelp.com.tr` |
| United Kingdom | `www.yelp.co.uk` |
| United States | `www.yelp.com` |

***

### Example output (one item per page)

```json
{
  "page_number": 1,
  "result_timestamp": "2026-05-26T10:30:00.123456",
  "search_parameters": { "place_id": "ED7A7vDdg8yLNKJTSVHHmg", "sortby": "date_desc", "max_pages": 1 },
  "search_metadata": { "pages_processed": 1, "max_pages_set": 1, "pagination_limit_reached": false, "total_reviews_estimate": 847 },
  "reviews": [
    {
      "position": 1,
      "rating": 5,
      "date": "2026-05-20",
      "user": { "name": "Jane D.", "location": "New York, NY", "stats": { "friends": 120, "photos": 45, "reviews": 88 } },
      "comment": { "text": "The almond croissant was incredible...", "language": "en" },
      "photos": [],
      "feedback": { "useful": 3, "funny": 0, "cool": 1 },
      "owner_replies": [],
      "tags": []
    }
  ]
}
```

***

### Pricing

This Actor uses transparent **pay-per-event** pricing:

| Event | Price | When |
|-------|-------|------|
| Setup | $0.01 | Once per run |
| Page processed | $0.01 | Per page of reviews fetched (~49 reviews) |
| Place resolved | $0.01 | Once per run, only when you supply a business URL or alias instead of an encoded place ID |

Fetching 1 page (~49 reviews) by encoded place ID costs about **$0.02**; the same run from a pasted business URL costs about **$0.03**. 5 pages (~245 reviews) by place ID costs about **$0.06**. Paid plans get a small per-event discount.

***

### How to get started

1. Open the Actor on the [Apify Store](https://apify.com/johnvc/yelp-reviews-api?fpr=9n7kx3).
2. Paste a Yelp business URL into `place_id` (or use an encoded place ID / alias), set sort/filter options and `max_pages`, and click **Start**.
3. Read results from the dataset (JSON, CSV, Excel) or via the [Apify API](https://docs.apify.com/api/v2).

***

### Code example (Python + MCP)

Want a runnable quick-start? The public example repo has a Python (uv) script plus MCP install guides for Claude (Desktop, Code, Web) and Cursor:

**[github.com/johnisanerd/Apify-Yelp-API](https://github.com/johnisanerd/Apify-Yelp-API)**

It shows how the Yelp Search, Business Details, and Reviews APIs chain together - a search returns the `place_ids` that feed the other two.

### 🔗 Related Tools

Building a review and reputation pipeline for local businesses? These tools from the same catalog pair well with the Yelp Reviews API:

- [Yelp Search API](https://apify.com/johnvc/yelp-search-api?fpr=9n7kx3): find businesses by keyword and location and get the `place_ids` that feed this reviews Actor. This is the upstream step.
- [Yelp Business Details API](https://apify.com/johnvc/Yelp-Place-API?fpr=9n7kx3): pull the full business profile (categories, hours, phone, rating summary) for the same place ID.
- [OpenTable Reviews API](https://apify.com/johnvc/opentable-reviews-api?fpr=9n7kx3): restaurant review intelligence from another platform, so you can watch reputation across sources, not just Yelp.
- [Google Maps Places Scraper](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3): discover local businesses in bulk and cross-reference them with their Yelp listings.

Older alternatives such as [tri\_angle/yelp-review-scraper](https://apify.com/tri_angle/yelp-review-scraper?fpr=9n7kx3) exist, but that one carries a low average rating (about 2.2 out of 5) and a single-line description with sparse field documentation. This API is actively maintained and returns clean, structured JSON with reviewer stats, owner replies, feedback vote counts, and every field documented.

***

### FAQ / Troubleshooting

#### Can I use a Yelp URL instead of a place ID?

Yes. Paste the business page URL straight from your browser, for example `https://www.yelp.com/biz/maman-new-york-22`, into `place_id`. Query strings such as `?osq=...` and review permalinks are fine, and the plain alias (`maman-new-york-22`) works too. The Actor resolves it to the encoded place ID for you, which costs one `place_resolved` event. If you already have the encoded ID, pass that instead and skip the resolution fee.

Two things it will not take: a Yelp **search results** URL (that belongs in the [Yelp Search API](https://apify.com/johnvc/yelp-search-api?fpr=9n7kx3)) and a non-Yelp URL. Both come back as a clear `ValidationError` in the dataset rather than a failed run.

#### Where does the place ID come from?

From the [Yelp Search API](https://apify.com/johnvc/yelp-search-api?fpr=9n7kx3): every listing includes a `place_ids` array whose first entry is the encoded ID (e.g. `ED7A7vDdg8yLNKJTSVHHmg`). That is the cheapest thing to pass here, because it needs no resolution step. You can also just paste the business URL and skip this entirely.

#### How many reviews per page?

Up to 49. Increase `max_pages` to fetch more.

#### Can I get only 5-star (or 1-star) reviews?

Yes: set `rating` to `5` or `1`, or a list like `4,5`.

#### What are not-recommended reviews?

Yelp hides some reviews behind a "not recommended" filter. Set `not_recommended: true` to fetch those instead.

**Known limitation (verified 2026.08.03):** the upstream data source currently returns no filtered reviews for any business, so a run with `not_recommended: true` ends with a clear error explaining this rather than returning rows. Recommended reviews are unaffected. This mode also accepts no other options, so `sort_by`, `rating`, `q` and `hl` are ignored whenever it is set.

#### Is this reliable?

Yes: it calls a structured data API, not a headless browser, so there are no captchas or layout breakages.

#### Can I schedule this Yelp reviews scraper?

Yes, and scheduling is where the tool earns its keep. Create a [saved task](https://docs.apify.com/platform/actors/running/tasks) with your `place_id` and filters, then attach a [schedule](https://docs.apify.com/platform/schedules) from the Actor's Actions, then Schedule menu. Use cron strings like `0 7 * * *` for a daily 7 AM pull, `0 */6 * * *` for every six hours, or `0 9 * * 1` for a Monday check-in, and one schedule can trigger many tasks so a whole list of businesses refreshes together. See the Integrations section above for the full monitoring recipe.

#### Should I use an API or a web scraper for Yelp reviews?

Both, and this Actor is both. An official [API](https://en.wikipedia.org/wiki/API) is usually rate limited, quota bound, and often missing fields like reviewer stats or owner replies, while writing your own [web scraper](https://en.wikipedia.org/wiki/Web_scraping) means fighting captchas and layout changes. This Yelp reviews scraper gives you the same reviews you would read on [Yelp](https://www.yelp.com/) as clean JSON you call yourself, with predictable per-page pricing and no quotas.

#### Can I integrate this Yelp Reviews API with other apps?

Yes. It connects to almost any cloud service through [Apify integrations](https://docs.apify.com/platform/integrations): [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier), [Slack](https://docs.apify.com/platform/integrations/slack), the n8n community node, and [webhooks](https://docs.apify.com/platform/integrations/webhooks) on `ACTOR.RUN.SUCCEEDED` for custom actions. See the Integrations section above for full recipes.

#### Can I use the Yelp Reviews API with the Apify API?

Yes. The Apify API runs the Actor, schedules it, and fetches datasets, and the `apify-client` package exists for both Node.js and Python. See the Actor's [API tab](https://apify.com/johnvc/Yelp-Reviews-API/api?fpr=9n7kx3) for ready-made snippets.

#### Can I use the Yelp Reviews API through an MCP server?

Yes. Add it as a tool in any MCP client (Claude, Cursor, and others) through the hosted [Apify MCP server](https://mcp.apify.com/) with the Actor-specific URL `https://mcp.apify.com/?tools=actors,docs,johnvc/Yelp-Reviews-API`. In [Claude Code](https://claude.ai/referral/uIlpa7nPLg) (free trial) or [Claude Cowork](https://claude.ai/referral/uIlpa7nPLg) (free trial) your agent can then answer questions like "summarize the 1-star reviews for this restaurant" with live data. See the [Apify MCP docs](https://docs.apify.com/platform/integrations/mcp).

#### How can I track reviews on other platforms?

Pair this with related tools in the same catalog: the [Yelp Search API](https://apify.com/johnvc/yelp-search-api?fpr=9n7kx3) to find the businesses first, the [Yelp Business Details API](https://apify.com/johnvc/Yelp-Place-API?fpr=9n7kx3) for the full profile, the [OpenTable Reviews API](https://apify.com/johnvc/opentable-reviews-api?fpr=9n7kx3) for restaurant reviews on another site, and the [Google Maps Places Scraper](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3) to match a business to its map listing.

#### How do I monitor competitors' online reputation on Yelp?

Save one task per competitor location with `sort_by` set to `date_desc`, put them all on a shared schedule, and route new low-star reviews to Slack or email. Because each run appends to the same dataset, you build a reputation timeline you can chart or diff week over week. The Integrations section above shows the Tasks-and-Schedules and Supabase storage patterns.

#### What is sentiment analysis, and can I run it on Yelp reviews?

[Sentiment analysis](https://en.wikipedia.org/wiki/Sentiment_analysis) scores text as positive, negative, or neutral. This Actor returns the full `comment.text` of every review, so you can feed those strings into an LLM or a sentiment model to surface recurring themes and complaints across a business or a whole competitor set.

Learn more about the [Apify MCP integration](https://docs.apify.com/platform/integrations/mcp).

### n8n integration

Available as an n8n community node, **[n8n-nodes-yelp-api](https://www.npmjs.com/package/n8n-nodes-yelp-api)** (Search Businesses, Get Business Details, and Get Reviews). In n8n: Settings, Community Nodes, install `n8n-nodes-yelp-api`, then use it in any workflow (it also works as an AI Agent tool).

***

### Featured Tasks

Ready-to-run examples that show this API solving a specific problem. Each opens its own setup so you can run it on your account in one click.

- [Check a restaurant's Yelp reviews by API](https://apify.com/johnvc/Yelp-Reviews-API/examples/check-a-restaurants-yelp-reviews?fpr=9n7kx3) - Pull every review for one restaurant: text, rating, date, reviewer, photos, owner replies, and votes.
- [Find 1-star Yelp reviews to fix service issues](https://apify.com/johnvc/Yelp-Reviews-API/examples/find-1-star-yelp-reviews-to-fix-service-issues?fpr=9n7kx3) - Surface a business's newest 1-star reviews to spot recurring service problems.
- [Search Yelp reviews by keyword for menu insights](https://apify.com/johnvc/Yelp-Reviews-API/examples/search-yelp-reviews-by-keyword-for-menu-insights?fpr=9n7kx3) - Keep only reviews mentioning a dish or topic for menu and product research.
- [Export Yelp Reviews to CSV](https://apify.com/johnvc/yelp-reviews-api/examples/export-yelp-reviews-to-csv?fpr=9n7kx3)
- [Get Yelp Reviews by API from a Place ID](https://apify.com/johnvc/Yelp-Reviews-API/examples/get-yelp-reviews-by-api?fpr=9n7kx3)

***

### 🌐 About Alpha OSINT

This Actor is part of [Alpha OSINT](https://www.alphaosint.com), toolset of financial and operations data sources and APIs.
See the [Yelp Reviews API and MCP source page](https://www.alphaosint.com/sources/yelp-reviews-api-and-mcp/) for related tools and use cases.
For support or requests for this actor, please start a ticket [directly on our support page](https://apify.com/johnvc/Yelp-Reviews-API/issues/open?fpr=9n7kx3).

Last Updated: 2026.08.04

# Actor input Schema

## `place_id` (type: `string`):

Set the Yelp business to fetch reviews for. Accepts any of: the full Yelp business URL copied from your browser (e.g. 'https://www.yelp.com/biz/maman-new-york-22'), the encoded place ID (e.g. 'ED7A7vDdg8yLNKJTSVHHmg' - the FIRST entry of the place\_ids array on every Yelp Search API result), or the business alias (e.g. 'maman-new-york-22'). A URL or alias is resolved to the encoded ID automatically, which costs one extra place\_resolved event; supplying the encoded ID skips that fee. A regional business URL (e.g. 'https://www.yelp.co.uk/biz/...') is handled automatically - it sets the Yelp Domain for you. Required.

## `sort_by` (type: `string`):

Order the reviews. Defaults to Yelp's relevance order. Choose newest/oldest by date, highest/lowest by rating, or elite reviewers first.

## `rating` (type: `string`):

Restrict to specific star ratings, 1 to 5. Use a single value (e.g. '5') or a comma-separated list (e.g. '4,5'). Optional.

## `q` (type: `string`):

Keep only reviews mentioning this keyword or phrase (e.g. 'cheesecake', 'service'). Optional.

## `hl` (type: `string`):

Set the two-letter language code for the reviews interface (e.g. 'en', 'es', 'fr'). Defaults to English. Optional.

## `not_recommended` (type: `boolean`):

Set true to return Yelp's not-recommended (filtered) reviews instead of the recommended ones. Defaults to false. Known limitation (verified 2026.08.03): the upstream data source returns no filtered reviews for any business right now, so a run with this enabled ends with an explanatory error instead of rows. This mode also accepts no other options, so Sort By, Rating Filter, Search Within Reviews and Language Code are ignored when it is set.

## `yelp_domain` (type: `string`):

Choose which regional Yelp domain the business is on. Only needed when you supply a bare alias or encoded ID for a non-US business - a pasted regional business URL sets this for you and overrides this field. 41 domains are supported, e.g. 'www.yelp.com' (US), 'www.yelp.ca' (Canada), 'www.yelp.co.uk' (UK), 'www.yelp.fr' (France), 'www.yelp.de' (Germany). Multilingual countries use a language prefix instead of 'www', e.g. 'fr.yelp.ca' or 'zh.yelp.com.hk'. A short form like 'yelp.co.uk' is accepted and expanded for you. Optional - defaults to www.yelp.com. The full list is in the README.

## `max_pages` (type: `integer`):

Set the maximum number of review pages to fetch (about 49 reviews per page). Set 0 for unlimited, bounded by a safety cap of 20 pages. Default: 1. Each fetched page is billed separately under pay-per-event.

## Actor input object example

```json
{
  "place_id": "ED7A7vDdg8yLNKJTSVHHmg",
  "not_recommended": false,
  "yelp_domain": "www.yelp.com",
  "max_pages": 1
}
```

# Actor output Schema

## `allResults` (type: `string`):

Complete dataset with every page of reviews returned by the run. Each item is one page and contains the reviews array plus run metadata.

## `reviews` (type: `string`):

Filtered view focused on the reviews array - the Yelp reviews for the business with rating, text, date, reviewer details, photos, and feedback counts.

# 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 = {
    "place_id": "ED7A7vDdg8yLNKJTSVHHmg",
    "yelp_domain": "www.yelp.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("johnvc/yelp-reviews-api").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 = {
    "place_id": "ED7A7vDdg8yLNKJTSVHHmg",
    "yelp_domain": "www.yelp.com",
}

# Run the Actor and wait for it to finish
run = client.actor("johnvc/yelp-reviews-api").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 '{
  "place_id": "ED7A7vDdg8yLNKJTSVHHmg",
  "yelp_domain": "www.yelp.com"
}' |
apify call johnvc/yelp-reviews-api --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/iTiaAgy1XorGxqnqD/builds/IcDDgPKpuDH82le5b/openapi.json