Yelp Business Scraper — Ratings, Reviews & Local Business Data API for AI Agents & Lead-Gen

Real Yelp business data for AI agents and lead-generation pipelines. Search Yelp by term and location and get back typed JSON rows — one per business — with name, star rating, review count, categories, street address, city, phone, price range, Yelp page URL, and photo. Where most Yelp scrapers hit a DataDome 403 wall, this actor's tiered fallback (official Fusion API → locale-domain pages → direct) keeps returning real data. Built for lead lists, local market research, competitive intelligence, and reputation monitoring.

Why agents use this actor

• Structured business records — name, rating, review count, categories, address, phone, price range, canonical Yelp URL, and photo per business, parsed from Yelp's server-rendered data.
• Deterministic typed output — every row matches the published dataset schema (nullable fields explicitly marked), so downstream parsing never guesses.
• Cost-predictable — a run fetches at most maxRequestsPerCrawl pages (default 20), so autonomous agents can budget before they run.
• No auth, no cookies — public pages only; nothing to configure or expire.
• Clear error semantics — invalid input and total failure exit non-zero with a status message; per-URL failures carry an error field; a SUMMARY key-value record aggregates outcomes. Never a silent success with zero data.
• Tiered access with automatic fallback — three independent retrieval paths (official Yelp Fusion API, Yelp locale-domain business pages, direct Yelp search) are tried in order until one returns data. Every row carries sourceTier so agents know its provenance.
• Blocking resilience built in — requests run through Apify proxy with browser-grade headers, automatic retry with backoff, per-attempt IP rotation on 403/429/5xx, and rotation across retrieval hosts.

An optional free Yelp API key (yelp.com/developers, 500 calls/day) unlocks the fastest tier.

Input schema

Field	Type	Required	Default	Description
searchTerms	array of strings	Yes	—	Business search terms (e.g. "coffee shops", "plumbers"). Each term becomes one Yelp search-results page fetch, combined with location.
location	string	Yes	—	Geographic location to search in (e.g. "San Francisco, CA"). Combined with each search term.
url	string	No	—	A single URL to fetch directly (e.g. a Yelp search URL). Alias for urls/startUrls.
urls	array of strings	No	—	List of URLs to fetch directly, in addition to search-term URLs.
startUrls	array	No	—	Request list of URLs to fetch directly ({ "url": "..." } objects or plain strings).
maxRequestsPerCrawl	integer	No	20	Maximum businesses fetched per search term (and maximum direct URLs fetched) per run.
yelpApiKey	string (secret)	No	—	Yelp Fusion API key. Free at yelp.com/developers (500 calls/day); enables the fusion-api tier — up to 50 businesses per call.
tierOrder	array of strings	No	["fusion-api","locale-page","direct"]	Order of access strategies tried per search term; the first one that returns data wins.
proxyConfiguration	object	No	Apify residential proxy	Proxy for the requests. Residential groups give the most reliable results (billed to your account).

Yelp Business Output Schema

One row per business found on a search page. Business fields plus the request context that produced them:

Field	Type	Nullable	Description
name	string	yes	Business name as listed on Yelp.
rating	number	yes	Yelp star rating, 1–5.
reviewCount	integer	yes	Number of Yelp reviews.
categories	string[]	yes	Category names (e.g. "Coffee & Tea").
address	string	yes	Street address line (e.g. "370 4th St").
city	string	yes	City of the business address.
phone	string	yes	Phone number when Yelp exposes it on the results page.
priceRange	string	yes	$ to $$$$; null when not set.
yelpUrl	string	yes	Canonical Yelp business-page URL.
imageUrl	string	yes	Primary business photo (Yelp CDN).
isAd	boolean	yes	true when the row came from a sponsored slot.
sourceTier	string	yes	Which tier produced the row: "fusion-api", "locale-page", or "direct".
url	string	no	The URL actually fetched for this row (Fusion API request, Yelp locale-domain business page, or Yelp search page). Canonical business links are in yelpUrl.
statusCode	integer	yes	HTTP status of the fetched page; null only on network-level failure.
ok	boolean	no	true when the page fetch returned 200–299.
title	string	yes	The fetched page's <title>.
searchTerm	string	yes	The search term that produced this row; null for directly supplied URLs.
location	string	yes	The location combined with the search term; null for directly supplied URLs.
error	string	yes	Network-level error message; present only on failed-request rows.

A page that yields no business data (a failed fetch or a non-search URL) produces a single page-level row with the request-context fields only — the same shape earlier versions emitted, so existing integrations keep working.

Example row:

{
  "name": "Delah Coffee",
  "rating": 4.6,
  "reviewCount": 639,
  "categories": ["Coffee & Tea"],
  "address": "370 4th St",
  "city": "San Francisco",
  "phone": null,
  "priceRange": "$$",
  "yelpUrl": "https://www.yelp.com/biz/delah-coffee-san-francisco",
  "imageUrl": "https://s3-media0.fl.yelpcdn.com/bphoto/J-48dZf3Le-rEmGQU9mbMg/ls.jpg",
  "isAd": false,
  "sourceTier": "locale-page",
  "url": "https://www.yelp.com.au/biz/delah-coffee-san-francisco",
  "statusCode": 200,
  "ok": true,
  "title": "DELAH COFFEE - Updated August 2026 - 370 4th St, San Francisco, California, United States - Coffee & Tea - Phone Number - Yelp",
  "searchTerm": "coffee shops",
  "location": "San Francisco, CA"
}

Error semantics

• Bad input (no searchTerms and no URLs): the run fails fast with exit code 1 and status message Invalid input: provide searchTerms (with optional location) or url/urls/startUrls. Nothing is billed to the dataset.
• Partial failure: a search term that a tier cannot serve automatically falls through to the next tier; only when every tier fails for that term is it skipped. Other terms are unaffected, and the per-tier reason is recorded in SUMMARY.failures.
• Total failure (no search term or URL produced data on any tier): exit code 1 with a status message naming the tiers tried and the first error — never a silent SUCCEEDED with zero usable items.
• Run summary: the SUMMARY record in the run's key-value store contains { requestedSearches, requestedUrls, tiers, succeeded, businesses, failed, failures[] } for retry logic. Failures live here, not in the dataset, so you are never billed for error rows.

Use from AI agents (MCP)

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=apricot_blackberry/yelp-business-scraper",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}

Works in Claude, Cursor, ChatGPT deep research connectors, and any MCP client; the input schema above is the tool's parameter schema.

Use from code

curl:

curl -X POST "https://api.apify.com/v2/acts/apricot_blackberry~yelp-business-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["coffee shops"], "location": "San Francisco, CA"}'

JavaScript (apify-client):

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('apricot_blackberry/yelp-business-scraper').call({
    searchTerms: ['coffee shops'],
    location: 'San Francisco, CA',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();

Python (apify_client):

from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("apricot_blackberry/yelp-business-scraper").call(run_input={
    "searchTerms": ["coffee shops"],
    "location": "San Francisco, CA",
})
items = client.dataset(run["defaultDatasetId"]).list_items().items

Use from automation platforms

• n8n / Make / Zapier: use the native Apify integration and choose apricot_blackberry/yelp-business-scraper by name.
• LangChain / LlamaIndex: use the Apify actor tool wrappers with the same actor ID and input.
• Webhooks: configure an Apify webhook to fire on run completion (ACTOR.RUN.SUCCEEDED/FAILED) to push new business rows into your CRM or lead pipeline without polling.

Pricing

$0.05 start + $0.01 per business result delivered (PAY_PER_EVENT). A 10-business search costs about $0.15; residential proxy usage (the default) is billed to your Apify account on top of this.

FAQ

Q: How many businesses do I get per search? A: One search page typically yields 10–15 businesses (organic results plus any sponsored slots, flagged with isAd).

Q: Is the phone number always present? A: Yelp exposes phone numbers on the results page for some listings; where it doesn't, phone is null and the yelpUrl links to the full listing.

Q: Does Yelp's terms allow this? A: This actor reads public pages only. Check Yelp's current terms of service for your use case.

Q: Which proxy should I use? A: The default residential proxy configuration is recommended; residential IPs pass most reliably (proxy usage is billed to your account).

Q: Do I need a Yelp API key? A: No — the actor returns full business records without one. Supplying an optional free key from yelp.com/developers (500 calls/day) simply routes the run through Yelp's official API, which is the fastest tier.

Q: Are category names always in English? A: The locale-page tier prefers English-language Yelp domains, so category names come back in English for the large majority of rows; occasionally a row is served by a non-English locale and its categories reflect that. All other fields — name, rating, review count, address, phone, price — are locale-independent.

Changelog

• 2026-08-15 — Added a tiered access engine with automatic fallback: the official Yelp Fusion API (yelpApiKey, optional and free), Yelp locale-domain business pages with host rotation, and direct Yelp search. New yelpApiKey and tierOrder inputs, new sourceTier output field, richer phone and photo extraction, failures moved entirely to the SUMMARY record.
• 2026-08-15 — Rebuilt extraction engine: rows are now full business records (name, rating, review count, categories, address, city, phone, price range, Yelp URL, photo) parsed from Yelp's server-rendered data. Added Apify proxy support with per-attempt IP rotation and 403 retry. Dataset schema extended accordingly.
• 2026-08-14 — Added strict dataset output schema and agent/MCP integration docs. searchTerms + location now drive Yelp search-page fetches. Fail-loud error handling, retry with backoff, SUMMARY run record.

---

📧 Support · 📚 Documentation · ⚠️ Legal · 📡 REST API

Built for lead-gen agents, business owners, and reputation managers doing local business research, competitive intelligence, and market analysis on Yelp ratings and reviews.