# Yelp Business Scraper (`muhammadafzal/yelp-scraper`) Actor Scrape Yelp business listings and optional visible reviews from search queries or direct business URLs. Return structured names, ratings, review counts, categories, phone, website, address, coordinates, claimed status, and source metadata for local lead research and AI-agent workflows. - **URL**: https://apify.com/muhammadafzal/yelp-scraper.md - **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community) - **Categories:** Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 yelp business returneds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Yelp Business Scraper Scrape structured Yelp business listings for local-market research, lead generation, location intelligence, and AI-agent workflows. Provide search terms and locations, paste Yelp search URLs, or scrape direct business URLs. Results are written to the default dataset as one stable JSON record per unique business. ### What it extracts | Field | Description | | --- | --- | | `name`, `yelpUrl` | Business identity and canonical Yelp URL | | `rating`, `reviewCount`, `priceRange` | Public rating and review signals | | `categories` | Yelp business categories | | `phone`, `website`, `address` | Public contact and location details | | `latitude`, `longitude` | Coordinates when present in structured data | | `isClaimed` | Claimed-page signal when visible | | `reviews` | Optional visible reviews, capped by `maxReviewsPerBusiness` | ### Input Use `searchTerms` with `locations` for searches: ```json { "searchTerms": ["coffee shops", "coworking spaces"], "locations": ["Austin, TX"], "maxResults": 50, "includeReviews": false } ```` Use `startUrls` for a Yelp search or direct business page: ```json { "startUrls": [{ "url": "https://www.yelp.com/biz/example-business" }] } ``` Search pages are expanded up to `maxPagesPerSearch`. The actor deduplicates business URLs and stops at `maxResults`. The default input is intentionally small so an agent or Apify health check can finish quickly. ### Output Each business is one dataset item. Optional fields use `null` when Yelp does not expose a value. A final `_type: "SUMMARY"` item and `OUTPUT` key-value record report item counts, failed pages, and block/challenge warnings. When Yelp blocks the browser path, the actor can use ScrapeCreators' public Google Search endpoint as a fallback when `SCRAPECREATORS_API_KEY` is configured by the actor owner. Provider fallback rows include a warning and may contain fewer fields because they are based on public search snippets; no cookies are required and the API key is never an input field. ### Reliability and limits Yelp can vary content by region, session, and traffic level. The actor uses a low concurrency, persistent session pool and Apify Proxy by default. If Yelp presents a challenge, the run records a warning instead of pretending that a blocked page was an empty result. Use a lower page count and result cap for small one-off jobs. Reviews are the visible reviews loaded on the business page, not a promise of the full review history. Website links may be Yelp redirect URLs when that is the only public link available. ### Pricing The actor is designed for predictable pay-per-use pricing: one primary result event per emitted business, with no charge for duplicate URLs or results beyond `maxResults`. Configure the final PPE price in Apify Console after observing proxy and runtime costs for your account. ### Legal and responsible use Use this actor only where you have a lawful basis and comply with Yelp's terms, robots directives, privacy obligations, and applicable local law. Respect rate limits and do not use extracted contact information for unwanted or unlawful outreach. # Actor input Schema ## `searchTerms` (type: `array`): Use this when you want Yelp search results. Enter one or more business categories or keywords, for example \["coffee shops", "plumbers"]. Pair with locations; direct business URLs can be used instead. ## `locations` (type: `array`): Use this with search terms to localize results. Enter cities, regions, or postal codes, for example \["Austin, TX"]. This is not a business URL field. ## `startUrls` (type: `array`): Use this when you already have Yelp search or business URLs. Accepts full https://www.yelp.com URLs; for example \[{"url":"https://www.yelp.com/biz/example"}]. This supplements search terms. ## `maxResults` (type: `integer`): Use this to cap total unique businesses returned. Defaults to 25; this is a result cap, not a page count. ## `maxPagesPerSearch` (type: `integer`): Use this to control Yelp search pagination. Defaults to 3 pages; each page is requested sequentially with a short delay. ## `includeReviews` (type: `boolean`): Use this when you need the first visible Yelp reviews from each business page. Defaults to false because reviews increase runtime and target-site load. ## `maxReviewsPerBusiness` (type: `integer`): Use this with Include reviews to cap reviews per business. Defaults to 5 and maximum 20. ## `proxyConfiguration` (type: `object`): Use this when Yelp needs an Apify Proxy or your own proxy setup. Defaults to Apify residential proxy with a US country preference. ## Actor input object example ```json { "searchTerms": [ "coffee shops" ], "locations": [ "Austin, TX" ], "startUrls": [], "maxResults": 25, "maxPagesPerSearch": 3, "includeReviews": false, "maxReviewsPerBusiness": 5, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "BUYPROXIES94952" ], "apifyProxyCountry": "US" } } ``` # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("muhammadafzal/yelp-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("muhammadafzal/yelp-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call muhammadafzal/yelp-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=muhammadafzal/yelp-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Yelp Business Scraper", "description": "Scrape Yelp business listings and optional visible reviews from search queries or direct business URLs. Return structured names, ratings, review counts, categories, phone, website, address, coordinates, claimed status, and source metadata for local lead research and AI-agent workflows.", "version": "0.1", "x-build-id": "0GR6hXJaNKePvTI81" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/muhammadafzal~yelp-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-muhammadafzal-yelp-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/muhammadafzal~yelp-scraper/runs": { "post": { "operationId": "runs-sync-muhammadafzal-yelp-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/muhammadafzal~yelp-scraper/run-sync": { "post": { "operationId": "run-sync-muhammadafzal-yelp-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchTerms": { "title": "Search terms", "type": "array", "description": "Use this when you want Yelp search results. Enter one or more business categories or keywords, for example [\"coffee shops\", \"plumbers\"]. Pair with locations; direct business URLs can be used instead.", "default": [ "coffee shops" ], "items": { "type": "string" } }, "locations": { "title": "Locations", "type": "array", "description": "Use this with search terms to localize results. Enter cities, regions, or postal codes, for example [\"Austin, TX\"]. This is not a business URL field.", "default": [ "Austin, TX" ], "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Use this when you already have Yelp search or business URLs. Accepts full https://www.yelp.com URLs; for example [{\"url\":\"https://www.yelp.com/biz/example\"}]. This supplements search terms.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 500, "type": "integer", "description": "Use this to cap total unique businesses returned. Defaults to 25; this is a result cap, not a page count.", "default": 25 }, "maxPagesPerSearch": { "title": "Pages per search", "minimum": 1, "maximum": 20, "type": "integer", "description": "Use this to control Yelp search pagination. Defaults to 3 pages; each page is requested sequentially with a short delay.", "default": 3 }, "includeReviews": { "title": "Include reviews", "type": "boolean", "description": "Use this when you need the first visible Yelp reviews from each business page. Defaults to false because reviews increase runtime and target-site load.", "default": false }, "maxReviewsPerBusiness": { "title": "Reviews per business", "minimum": 1, "maximum": 20, "type": "integer", "description": "Use this with Include reviews to cap reviews per business. Defaults to 5 and maximum 20.", "default": 5 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Use this when Yelp needs an Apify Proxy or your own proxy setup. Defaults to Apify residential proxy with a US country preference.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "BUYPROXIES94952" ], "apifyProxyCountry": "US" } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```