# 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:** 4 total users, 3 monthly users, 100.0% runs succeeded, 4 bookmarks - **User rating**: 5.00 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. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## 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 Reviews API | Extract Ratings, Review Text & Reviewer Data (MCP-ready) > **Scrape Yelp reviews by place ID 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.** Give the Actor a Yelp place ID 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, search reviews for a keyword, or pull Yelp's not-recommended (filtered) reviews. Pages return up to 49 reviews each. This is the **reviews stage** of a 3-actor Yelp suite. Get place IDs from 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 and the Claude desktop app (which runs Cowork) both come with a free trial: https://claude.ai/referral/uIlpa7nPLg #### 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. *** ### 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. *** ### Input parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `place_id` | string | **Yes** | - | Yelp **encoded** place ID (e.g. `ED7A7vDdg8yLNKJTSVHHmg`) - the first entry of the `place_ids` array from the Yelp Search API. | | `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. | | `max_pages` | integer | No | `1` | Pages to fetch (~49 reviews each). `0` = unlimited (cap 20). | *** ### 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.02 | Once per run | | Page processed | $0.02 | Per page of reviews fetched (~49 reviews) | Fetching 1 page (~49 reviews) costs about **$0.04**; 5 pages (~245 reviews) costs about **$0.12**. *** ### How to get started 1. Open the Actor on the [Apify Store](https://apify.com/johnvc/yelp-reviews-api). 2. Enter a `place_id`, 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. ### FAQ / Troubleshooting - **Where does the place ID come from?** From the Yelp Search API - every listing includes a `place_ids` array. Use the **encoded** ID (the first entry, e.g. `ED7A7vDdg8yLNKJTSVHHmg`), not the human-readable alias, for the reviews endpoint. - **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. - **Is this reliable?** Yes - it calls a structured data API, not a headless browser, so there are no captchas or layout breakages. Learn more about the [Apify MCP integration](https://docs.apify.com/platform/integrations/mcp). Last Updated: 2026.05.29 # Actor input Schema ## `place_id` (type: `string`): Set the Yelp place ID to fetch reviews for. Use the encoded ID (e.g. 'ED7A7vDdg8yLNKJTSVHHmg') - it is the FIRST entry of the place\_ids array on every Yelp Search API result. The human-readable alias (e.g. 'maman-new-york-22') is not reliably accepted by the reviews endpoint, so prefer the encoded ID. 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. ## `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, "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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "place_id": "ED7A7vDdg8yLNKJTSVHHmg" }; // 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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "place_id": "ED7A7vDdg8yLNKJTSVHHmg" } # 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" }' | 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 " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Yelp Reviews API and MCP", "description": "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.", "version": "0.0", "x-build-id": "N7Ptxca27xiDhg0WB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/johnvc~yelp-reviews-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-johnvc-yelp-reviews-api", "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/johnvc~yelp-reviews-api/runs": { "post": { "operationId": "runs-sync-johnvc-yelp-reviews-api", "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/johnvc~yelp-reviews-api/run-sync": { "post": { "operationId": "run-sync-johnvc-yelp-reviews-api", "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", "required": [ "place_id" ], "properties": { "place_id": { "title": "Place ID", "minLength": 1, "type": "string", "description": "Set the Yelp place ID to fetch reviews for. Use the encoded ID (e.g. 'ED7A7vDdg8yLNKJTSVHHmg') - it is the FIRST entry of the place_ids array on every Yelp Search API result. The human-readable alias (e.g. 'maman-new-york-22') is not reliably accepted by the reviews endpoint, so prefer the encoded ID. Required." }, "sort_by": { "title": "Sort By", "enum": [ "relevance_desc", "date_desc", "date_asc", "rating_desc", "rating_asc", "elites_desc" ], "type": "string", "description": "Order the reviews. Defaults to Yelp's relevance order. Choose newest/oldest by date, highest/lowest by rating, or elite reviewers first." }, "rating": { "title": "Rating Filter", "type": "string", "description": "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": { "title": "Search Within Reviews", "type": "string", "description": "Keep only reviews mentioning this keyword or phrase (e.g. 'cheesecake', 'service'). Optional." }, "hl": { "title": "Language Code", "pattern": "^[a-z]{2}$", "type": "string", "description": "Set the two-letter language code for the reviews interface (e.g. 'en', 'es', 'fr'). Defaults to English. Optional." }, "not_recommended": { "title": "Not Recommended Reviews", "type": "boolean", "description": "Set true to return Yelp's not-recommended (filtered) reviews instead of the recommended ones. Defaults to false.", "default": false }, "max_pages": { "title": "Maximum Pages", "minimum": 0, "maximum": 100, "type": "integer", "description": "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.", "default": 1 } } }, "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 } } } } } } } } } } ```