Yelp Scraper

Scrape Yelp search results: business name, star rating, review count, price band, categories, street address and neighbourhood. Search by term and location, or paste a Yelp search URL with your own filters already applied.

Yelp was on our "closed" list, and it is not

Measured recently: six of six consecutive fetches returned about 1.07 MB of real results.

The referer is part of it. Reaching a search page from a search engine is the most ordinary way a person gets there, and it is in the profile that measured clean.

Where the data is, and three reasons the obvious parse fails

Not in the JSON-LD. The page publishes exactly two structured blocks, BreadcrumbList and FAQPage, and not one business appears in either. A scraper that reaches for JSON-LD here comes back empty and concludes the page is a shell.

The businesses live in the page's Apollo GraphQL cache, which is shipped inside three wrappers, each of which defeats a different parser:

1. inside a <script type="application/json"> tag,
2. wrapped in an HTML comment, <!-- ... -->,
3. HTML-escaped, so every quote arrives as ".

Strip all three and it is clean JSON.

And the cache is normalised. A Business entry holds the name, rating and review count — but its address is a __ref pointer to a separate BusinessLocation entry, and its categories are pointers to BusinessCategory entries. Read only the Business entries and every row comes back with a null address and no categories, which reads as missing data rather than an unfollowed pointer. This Actor resolves the references, so addresses and categories are populated.

Fields

Field	What it is
alias	Yelp's own slug, e.g. queen-anne-coffee-seattle. Stable, join on it
name	Business name
rating	Stars out of 5
review_count	Number of reviews
price_range	$ to $$$$
categories	Resolved category names, e.g. ["Coffee & Tea", "Bakeries"]
address, city	Street address and city
neighborhoods	Neighbourhoods Yelp assigns
timezone	Business timezone
yelp_guaranteed	Whether enrolled in Yelp Guaranteed
url	Yelp business page

price_range is returned as the dollar signs, not as the raw GraphQL object. Yelp leaves it unset on many businesses, and those come back null rather than being guessed from the category.

Some entries in the cache are landmarks and places rather than businesses, and they legitimately carry no rating or address. Those fields come back null rather than zero. On a test run of 40 results, 30 carried a rating and 31 an address, and the run summary reports both counts so you can see the shape of what you got.

Input reference

Field	Type	Default
term	what to search for	coffee
location	where	Seattle
search_url	full Yelp URL, overrides the two above	—
limit	1-1000	50
retries	1-8	4

Pagination uses Yelp's own start offset in steps of 10.

Passing a search_url is the way to use Yelp's own filters. Set price, rating, open-now, distance or any other facet in your browser, copy the address, and the Actor paginates through that filtered result set. Filtering on Yelp is cheaper than filtering the output, because the facet applies before pagination.

Typical uses

• Lead generation. Businesses in a category and city, with address, rating and review count. review_count is a decent proxy for how established a business is.
• Competitive research. Rating and review distribution for a category in one market, or the same category compared across cities.
• Market gap analysis. Categories with high ratings and low review counts are usually young businesses; low ratings with high counts are the opposite.
• Location scouting. neighborhoods groups results the way Yelp's own users think about a city.

Notes on behaviour

Pages are paced with a short randomised gap. A page that loads but whose cache holds no businesses is reported as no_businesses rather than returned as an empty result.

Yelp returns about 10 businesses per page, so a limit of 50 costs roughly five requests. Results include sponsored placements, exactly as Yelp shows them; they are not marked separately in the cache and this Actor does not invent a flag it cannot verify.

This is the US site. Yelp operates elsewhere with a different result structure, so treat the Actor as yelp.com until measured on another domain.