# Yelp Search API (`johnvc/yelp-search-api`) Actor Scrape Yelp search results - ranked local business listings with rating, reviews, price, categories, phone, and neighborhood. Filter by category, sort by rating or review count, paginate, and get the place IDs to pull full details and reviews. - **URL**: https://apify.com/johnvc/yelp-search-api.md - **Developed by:** [John](https://apify.com/johnvc) (community) - **Categories:** Lead generation, SEO tools, Developer tools - **Stats:** 5 total users, 4 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 Search API | Local Business Listings, Ratings & Reviews (MCP-ready) > **Scrape Yelp search results and get clean JSON back. Ranked local business listings with rating, reviews, price, categories, phone, neighborhood, and place IDs, plus ads and the available refinement filters. Pay per page. MCP-ready for Claude, ChatGPT, Cursor, and other AI agents.** Pass a search term and a location and the Actor returns the same ranked business listings Yelp shows on its search results page: business names, ratings, review counts, price tiers, categories, neighborhoods, open state, snippets, service options (delivery, takeout, outdoor dining), thumbnails, and the Yelp `place_ids` you need to pull full details or reviews. Sponsored placements (ads and inline ad carousels) and the full set of Yelp refinement filters (distance, neighborhoods, price, categories, features) come back too. This is a **Yelp search results API**: predictable per-page pricing, structured JSON, and no browser automation or captchas. It is the entry point of a 3-actor Yelp suite - feed the `place_ids` it returns into the **Yelp Business Details API** and the **Yelp Reviews API**. --- ### What this Actor returns - **Ranked business listings** (`organic_results`) - position, title, `place_ids`, link, categories, price (`$`-`$$$$`), rating, review count, neighborhoods, open state, snippet, highlights, service options, thumbnail. - **Ad placements** (`ads_results`, `inline_ads`) - sponsored businesses with block position and call-to-action buttons. - **Available filters** (`filters`) - the valid distance, neighborhood, price, category, and feature values you can pass back in as `radius_filter`, `category_filter`, or `attrs` to refine the next search. - **Run metadata** - echoed search parameters, page number, pagination state, and a per-page timestamp. Each page of results is one dataset item and one billable event. --- ### 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: *"Find the highest-rated coffee shops in Williamsburg, Brooklyn."* > > Agent calls `search-actors("yelp search")` on the Apify MCP server, picks this Actor, calls it with `{"search_term": "coffee", "location": "Brooklyn, NY", "sort_by": "rating", "max_pages": 2}`, gets the ranked listings back, and returns a short list with ratings and review counts. 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 *"Find vegan restaurants in Austin with 4.5+ stars."* Claude discovers this Actor, asks permission to call it, and returns structured results. #### 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. Same result, just no session-level tool registration. *** ### Use cases - **Local lead generation** - "Pull every plumber in {city} with under 50 reviews so I can pitch them." - **Local SEO & rank tracking** - "Where does {business} rank on Yelp for 'best tacos' across these 20 cities?" - **Market & competitor research** - rating, review count, and price distribution for a category in a market. - **Lead lists for sales** - build a list of businesses by category and location with phone numbers and neighborhoods. - **Feeding the Yelp suite** - harvest `place_ids` to pull full business profiles and reviews with the companion Actors. *** ### Input parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `location` | string | **Yes** | - | City + state, full address, or ZIP (e.g. `New York, NY`). | | `search_term` | string | No | - | What to search for (e.g. `coffee`, `plumbers`). Blank = browse all in the location. | | `category_filter` | string | No | - | Yelp category alias (e.g. `restaurants`, `coffee`). | | `sort_by` | string (enum) | No | `recommended` | `recommended`, `rating`, or `review_count`. | | `attrs` | string | No | - | Price/feature filters (e.g. `RestaurantsPriceRange2.2`, `ActiveDeal`). | | `radius_filter` | string | No | - | Distance radius or neighborhood value (cannot combine both). | | `yelp_domain` | string | No | `yelp.com` | Regional Yelp domain. | | `max_pages` | integer | No | `1` | Pages to fetch (~10 businesses each). `0` = unlimited (cap 20). | Valid values for `category_filter`, `attrs`, and `radius_filter` are returned in the `filters` object of every result, so you can run a broad search first and then refine. *** ### Example output (one item per page) ```json { "page_number": 1, "search_timestamp": "2026-05-26T10:30:00.123456", "search_parameters": { "find_desc": "Coffee", "find_loc": "New York, NY", "sortby": "rating", "max_pages": 1 }, "search_metadata": { "pages_processed": 1, "max_pages_set": 1, "pagination_limit_reached": false, "total_results_estimate": null }, "organic_results": [ { "position": 1, "place_ids": ["K6fkejf2ZBUdlsVrm5RbrA", "kore-coffee-new-york-2"], "title": "Kore Coffee", "link": "https://www.yelp.com/biz/kore-coffee-new-york-2", "categories": [{ "title": "Coffee & Tea", "link": "https://www.yelp.com/search?cflt=coffee" }], "rating": 5, "reviews": 13, "neighborhoods": "Chinatown", "snippet": "Nice small cozy coffee place...", "thumbnail": "https://s3-media0.fl.yelpcdn.com/bphoto/.../348s.jpg" } ], "ads_results": [], "inline_ads": [], "filters": { "price": [{ "text": "$", "value": "RestaurantsPriceRange2.1" }], "category": [], "distance": [], "features": [] }, "pagination": { "start": 0 } } ``` The `place_ids` array (encoded ID and human-readable alias) is what you feed into the Yelp Business Details API and Yelp Reviews API. *** ### 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 results fetched (~10 businesses) | A typical 1-page search costs about **$0.04** total. A 5-page run costs about **$0.12**. You are billed per page regardless of how many businesses appear, so pricing is predictable. *** ### How to get started 1. Open the Actor on the [Apify Store](https://apify.com/johnvc/yelp-search-api). 2. Enter a `location` (and optionally a `search_term`), set `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). 4. Or call it from any MCP-compatible AI agent using the setup above. *** ### 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 - **No results?** Make sure `location` is a real place Yelp recognizes (city + state works best). Try a broader `search_term` or remove `category_filter`. - **How do I get more than ~10 results?** Increase `max_pages`. Each page adds about 10 businesses. - **Where do `place_ids` come from / what are they for?** Every listing includes a `place_ids` array. Use either value with the Yelp Business Details API or Yelp Reviews API. - **What values can I use for filters?** Run any search, then read the `filters` object - it lists the valid `category_filter`, `attrs`, and `radius_filter` values for that query. - **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 ## `search_term` (type: `string`): Set the Yelp search query (the 'find\_desc' box). Examples: 'coffee', 'plumbers', 'best pizza', 'dentists'. Optional - leave blank to browse all businesses in the location. Any term valid in Yelp search is accepted. ## `location` (type: `string`): Set the geographic location to search in (the Yelp 'find\_loc' box). Accepts a city and state, a full address, or a ZIP code (e.g. 'New York, NY', 'Austin, Texas', '94103'). Required. ## `category_filter` (type: `string`): Restrict results to a Yelp category alias (the 'cflt' value). Examples: 'restaurants', 'coffee', 'dentists', 'plumbers'. Optional. Valid aliases are surfaced in the 'filters.category' object of any result. ## `sort_by` (type: `string`): Order the results. 'recommended' is the Yelp default; 'rating' sorts by highest rated; 'review\_count' sorts by most reviewed. Optional. ## `attrs` (type: `string`): Refine results by price and feature attributes (the 'attrs' value). Examples: 'RestaurantsPriceRange2.2' for $$, 'ActiveDeal' for deals, 'BusinessParking.validated'. Comma-separate multiple values. Optional. Valid values are surfaced in the 'filters.price' and 'filters.features' objects of any result. ## `radius_filter` (type: `string`): Narrow results to a distance radius or a neighborhood (the 'l' value). Cannot combine both. Optional. Valid values are surfaced in the 'filters.distance' and 'filters.neighborhoods' objects of any result. ## `yelp_domain` (type: `string`): Choose which regional Yelp domain to query (e.g. 'yelp.com', 'yelp.co.uk', 'yelp.fr', 'yelp.de'). Defaults to 'yelp.com'. Optional. ## `max_pages` (type: `integer`): Set the maximum number of result pages to fetch (1-indexed). Each page holds about 10 businesses. 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 { "search_term": "coffee", "location": "New York, NY", "yelp_domain": "yelp.com", "max_pages": 1 } ``` # Actor output Schema ## `allResults` (type: `string`): Complete dataset with every page returned by the run. Each item is one page and contains organic\_results, ads\_results, inline\_ads, filters, and search metadata. ## `businessListings` (type: `string`): Filtered view focused on the organic\_results array - the ranked Yelp businesses for the query, with rating, reviews, price, categories, phone, neighborhood, and place\_ids. # 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 = { "search_term": "coffee", "location": "New York, NY", "yelp_domain": "yelp.com" }; // Run the Actor and wait for it to finish const run = await client.actor("johnvc/yelp-search-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 = { "search_term": "coffee", "location": "New York, NY", "yelp_domain": "yelp.com", } # Run the Actor and wait for it to finish run = client.actor("johnvc/yelp-search-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 '{ "search_term": "coffee", "location": "New York, NY", "yelp_domain": "yelp.com" }' | apify call johnvc/yelp-search-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=johnvc/yelp-search-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Yelp Search API", "description": "Scrape Yelp search results - ranked local business listings with rating, reviews, price, categories, phone, and neighborhood. Filter by category, sort by rating or review count, paginate, and get the place IDs to pull full details and reviews.", "version": "0.1", "x-build-id": "35yxTaeVwHT2e1PIK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/johnvc~yelp-search-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-johnvc-yelp-search-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-search-api/runs": { "post": { "operationId": "runs-sync-johnvc-yelp-search-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-search-api/run-sync": { "post": { "operationId": "run-sync-johnvc-yelp-search-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": [ "location" ], "properties": { "search_term": { "title": "Search Term", "type": "string", "description": "Set the Yelp search query (the 'find_desc' box). Examples: 'coffee', 'plumbers', 'best pizza', 'dentists'. Optional - leave blank to browse all businesses in the location. Any term valid in Yelp search is accepted." }, "location": { "title": "Location", "minLength": 1, "type": "string", "description": "Set the geographic location to search in (the Yelp 'find_loc' box). Accepts a city and state, a full address, or a ZIP code (e.g. 'New York, NY', 'Austin, Texas', '94103'). Required." }, "category_filter": { "title": "Category Filter", "type": "string", "description": "Restrict results to a Yelp category alias (the 'cflt' value). Examples: 'restaurants', 'coffee', 'dentists', 'plumbers'. Optional. Valid aliases are surfaced in the 'filters.category' object of any result." }, "sort_by": { "title": "Sort By", "enum": [ "recommended", "rating", "review_count" ], "type": "string", "description": "Order the results. 'recommended' is the Yelp default; 'rating' sorts by highest rated; 'review_count' sorts by most reviewed. Optional." }, "attrs": { "title": "Attribute Filters", "type": "string", "description": "Refine results by price and feature attributes (the 'attrs' value). Examples: 'RestaurantsPriceRange2.2' for $$, 'ActiveDeal' for deals, 'BusinessParking.validated'. Comma-separate multiple values. Optional. Valid values are surfaced in the 'filters.price' and 'filters.features' objects of any result." }, "radius_filter": { "title": "Area / Distance Filter", "type": "string", "description": "Narrow results to a distance radius or a neighborhood (the 'l' value). Cannot combine both. Optional. Valid values are surfaced in the 'filters.distance' and 'filters.neighborhoods' objects of any result." }, "yelp_domain": { "title": "Yelp Domain", "type": "string", "description": "Choose which regional Yelp domain to query (e.g. 'yelp.com', 'yelp.co.uk', 'yelp.fr', 'yelp.de'). Defaults to 'yelp.com'. Optional." }, "max_pages": { "title": "Maximum Pages", "minimum": 0, "maximum": 100, "type": "integer", "description": "Set the maximum number of result pages to fetch (1-indexed). Each page holds about 10 businesses. 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 } } } } } } } } } } ```