Yelp Search Scraper

The Actor runs a Yelp business search by search term and location and exports one row per result, in Yelp's own ranking order, with paid placements labelled separately from organic listings.

Accepted input

Field	Type	Default	Description
find_desc	string	— (required)	What to search for — a category such as "coffee" or "plumbers", or a business name.
find_loc	string	— (required)	Where to search, written any way Yelp accepts it: "San Francisco, CA", a zip code such as "94110", or a neighborhood such as "Mission District, San Francisco".
start	integer	0	The result offset to start at. Yelp pages in tens, so this must be a multiple of 10; it exists to resume a search past where an earlier run stopped, not to skip forward one result at a time.
maxItems	integer	100	Maximum rows to save. 0 removes the limit. Rows come roughly 10 to 12 per request, since a section of paid placements can ride alongside the ten organic slots.
enrichBusinessDetails	boolean	false	For every result Yelp did not hydrate, fetches that business's own page and attaches it under details. One extra request per unhydrated result, billed only when that request succeeds.

{
  "find_desc": "coffee",
  "find_loc": "San Francisco, CA",
  "maxItems": 50
}

Response fields

Field	Contents
business_id	Yelp's internal id for the business. Present on every row, hydrated or not.
alias	The business's Yelp slug — the input /v1/yelp/business (the Yelp Business Scraper) takes. Taken from the row itself when Yelp hydrated it, otherwise parsed out of the row's own link.
url	The row's link on Yelp.
is_ad	Whether the row is a paid placement.
rank	The row's position within the result set, as Yelp reports it.
snippet	The review excerpt Yelp shows under the row, when it ships one.
is_hydrated	Whether Yelp attached a business record to this row.
business	Business data — name, phone, rating, exact review count, categories, formatted address, price range, and more — present when is_hydrated is true, null otherwise.
details	This result's full business page, the same shape the Yelp Business Scraper returns. Present only when enrichBusinessDetails is enabled and the fetch for that row succeeded.

{
  "business_id": "kHFPKRnQPfBnBMr4XvQKcQ",
  "alias": "kissaten-hifi-san-francisco",
  "url": "https://www.yelp.com/biz/kissaten-hifi-san-francisco?osq=coffee",
  "is_ad": false,
  "rank": 3,
  "is_hydrated": false,
  "business": null
}

Behaviour of is_hydrated and business

Yelp fills in a full business record for a search row only for paid placements. Organic results — the large majority of any search — carry business_id and alias and nothing else; searchResultBusiness is null in Yelp's own response, to both a browser and a plain request equally. This is not a gap in a particular run; it is how Yelp serves search results to a logged-out client. is_hydrated states which case a given row is before business is read, and enrichBusinessDetails exists specifically to close that gap by fetching each unhydrated row's own page.

Behaviour of pagination

start moves in steps of 10, matching Yelp's own page size, and a run continues automatically: it stops when Yelp's reported total_results has been reached, when a request returns no rows, or when maxItems is reached, whichever comes first. start set on the input is only the starting point for a fresh run; an interrupted run resumes at the exact row it stopped on rather than restarting from start.

Frequently asked questions

Why is business null on almost every row? Because Yelp withholds it from organic results at the server level, as explained above. Set enrichBusinessDetails to fetch each such row's full page instead, or pass the row's alias to the Yelp Business Scraper directly.

Why did a page return more than 10 rows? start advances by Yelp's own page size of 10, but a response can carry more rows than that when a paid placement is inserted alongside the ten organic ones rather than replacing one of them. The offset still advances by 10 regardless of how many rows a given page held.

Does enrichBusinessDetails re-fetch rows that already have a business record? No. It is skipped for any row where is_hydrated is already true, since those rows already carry a business record for free; only unhydrated rows are fetched and billed.

What happens to a row whose enrichment request fails? The row is kept exactly as it was, without a details field, and nothing is charged for it; a failure on one row does not interrupt the rest of the run.

Related

Yelp Business Scraper fetches a business's full profile directly by its alias, for when the alias is already known and a search is not needed.