Yelp Businesses & Reviews Scraper

Yelp's Fusion API gives out three review excerpts per business and then stops. That ceiling is Yelp's, not this actor's, and there is no way around it, which is why this uses Yelp's own Fusion API rather than fighting the website. You bring a free Yelp API key; the actor does the searching, pagination, de-duplication and shaping.

$3.00 per 1,000 businesses ($0.003 each), plus $0.00001 each time a run starts. Flat rate — no volume tiers, no plan gates — and you are charged only for businesses actually returned. Reviews are included in the business row at no extra charge: there is no separate per-review event.

Why the API and not a browser

Yelp's public pages sit behind DataDome, which returns a 403 and a captcha to automated requests from datacenter, ISP and clean residential addresses alike. There is no keyless route that works reliably, and a browser attempt burns residential bandwidth to arrive at a guaranteed block.

So this actor doesn't pretend. Supply a yelpApiKey and you get real data; supply nothing and you get a clearly labelled, free sample row telling you where to get a key — no browser launched, no proxy traffic, no charge. A key is free from https://www.yelp.com/developers/v3/manage_app and takes about a minute to create.

Input modes

• Search / listings — set searchQueries (e.g. ["coffee in San Francisco"]), or the single query + location fields. Returns one row per business in the results list.
• Detail — set businessUrls (https://www.yelp.com/biz/...) and/or businessSlugs (the part after /biz/). Returns the full business record for each.

You can combine both modes in one run. maxItems caps the total across all inputs.

Example input

{
  "yelpApiKey": "your-free-fusion-key",
  "searchQueries": ["coffee in San Francisco"],
  "businessUrls": ["https://www.yelp.com/biz/blue-bottle-coffee-san-francisco-7"],
  "maxItems": 50,
  "maxReviews": 3,
  "countryCode": "US"
}

Field	Default	Notes
yelpApiKey	—	Your free Fusion API key. Paste the API Key, not the Client ID. Can also be set as the YELP_API_KEY environment variable.
searchQueries	—	"{term} in {location}" per entry.
query + location	—	Single-search alternative. Ignored if searchQueries is set.
businessUrls / businessSlugs	—	Direct business targets.
maxItems	50	Total businesses across all inputs. Search paginates in pages of 50.
maxReviews	0	Reviews to attach per business. Yelp's Fusion API returns at most 3 reviews per business, so values above 3 return 3.
countryCode	US	Yelp region, two-letter ISO.
slackConnector / slackChannel	—	Optional. Post a run summary (count, top 5 businesses, dataset link) to Slack.
notionConnector / notionParentId	—	Optional. Write each business as a page into your Notion workspace.

Output

One dataset item per business:

{
  "ok": true,
  "name": "Blue Bottle Coffee",
  "yelpUrl": "https://www.yelp.com/biz/blue-bottle-coffee-san-francisco-7",
  "slug": "blue-bottle-coffee-san-francisco-7",
  "category": "Coffee & Tea",
  "rating": 4.1,
  "reviewCount": 2543,
  "price": "$$",
  "phone": "(510) 653-3394",
  "address": "66 Mint St, San Francisco, CA 94103",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94103",
  "lat": 37.782, "lng": -122.407,
  "isAd": false,
  "businessId": "…",
  "source": "yelp-fusion-api",
  "reviews": [
    { "author": "Jane D.", "rating": 5, "text": "Great espresso…", "date": "2025-12-01", "url": "https://www.yelp.com/biz/…" }
  ]
}

reviews is populated when maxReviews > 0 and is an empty array otherwise. Businesses are de-duplicated by businessId across every search and direct target in the run. Any field Yelp does not publish for a business comes back null rather than guessed.

Pagination and depth

Fusion caps a single call at 50 results and an offset at 1000, so the actor paginates in pages of 50 and stops at Yelp's own ceiling. maxItems caps the total.

Pricing

Event	When	Price
Actor start	Once per run, per GB of run memory	$0.00001
Business returned	Each business row written to the dataset	$0.003 ($3.00 / 1,000)

The row is written before the charge fires. Blocked, empty and bad-input runs emit a diagnostic row (ok: false with an errorCode such as NO_RESULTS, BAD_INPUT or NETWORK) and are never charged. A run with no API key returns the labelled sample and is not charged either.

Because reviews ride along free, a 50-business run with three reviews each returns 150 reviews and costs $0.15001.

Yelp's Fusion API has its own free daily call quota on your key; that is between you and Yelp and costs nothing here.

Troubleshooting

• A _sample row with getKeyAt — no yelpApiKey was supplied. Add one; the run was free.
• BAD_INPUT with a key-rejected hint — Yelp refused the key. Make sure you pasted the API Key from the Fusion app page and not the Client ID.
• NO_RESULTS — the term or location returned nothing. Try a broader term or a larger area.
• Fewer reviews than requested — Fusion returns a maximum of 3 reviews per business. That is Yelp's limit, not a throttle added here.