Yelp B2b Lead Extractor

What does Yelp B2B Lead Extractor do?

Yelp B2B Lead Extractor collects business information that a business has chosen to publish publicly on Yelp. It accepts Yelp search/listing pages and business-profile pages, reads public structured data and stable page links, and can make a bounded second request for selected public profiles. It also supports an explicit yelpFusionApi mode with a user-supplied secret Yelp Places/Fusion API key. It does not log in, solve CAPTCHA or DataDome challenges, infer email addresses, bypass throttling, or access private content.

The Actor is a public-page extractor, not an access-control workaround. If Yelp returns a challenge, throttle, redirect outside Yelp, or unusable page, the run fails closed with an optional diagnostic row and an OUTPUT_SUMMARY explanation. The Apify API, schedules, monitoring, and integrations can be used around the Actor; they do not change the source's access rules.

Why use Yelp B2B Lead Extractor?

Use it for small, auditable prospect lists, local-market research, public category monitoring, or downstream enrichment where the business has published the relevant field. Normal rows preserve Yelp identity and source provenance, and missing values are omitted rather than guessed. Businesses can be deduplicated across source pages and start URLs by public Yelp identity.

Tested capabilities

• Public JSON-LD, embedded JSON, and explicit /biz/ link extraction, plus official Yelp Fusion business search/detail requests when sourceMode is yelpFusionApi.
• Search and business-profile URLs, bounded pagination, global maxItems, and per-source maxPages.
• Case-insensitive keyword, minimum rating, minimum review-count, public website, public phone, and public email filters.
• Stable source-order output or global name, rating, and review-count sorting.
• Optional bounded profile enrichment, minimal diagnostics, summary counters, and direct or configured Apify Proxy transport.
• Deterministic repository fixtures for QA. Fixture mode never silently replaces a failed live request.

In yelpFusionApi mode, the key is used only in an Authorization: Bearer ... request header and is never logged or stored. Fusion business responses can provide business identity, phone, location, categories, ratings, review counts, prices, hours, and media when authorized; ordinary Fusion does not provide email addresses. Setting hasEmail: true therefore returns YELP_FUSION_EMAIL_UNSUPPORTED and requires a separately authorized email-bearing source. API mode never falls back to a challenged public page.

How to scrape Yelp business data

1. Open the Actor's Input tab in Apify Console.
2. Provide query and location, or enter one or more Yelp startUrls objects.
3. Start with maxPages: 1, a small maxItems, includeDetails: false, and a respectful delay.
4. Start the run and inspect the dataset, the OUTPUT_SUMMARY key-value item, and any diagnostic rows.
5. For automation, use the run/API links in Console, schedule the Actor, or connect its dataset to an approved downstream integration.

startUrls takes precedence over the generated query + location search URL. Filters, sorting, limits, detail settings, and developer settings still apply to custom URLs. The runtime also accepts legacy string entries for backward compatibility, although the Console schema uses objects with a required url property.

What data can it extract?

Group	Fields
Identity	recordId, businessId, name, businessUrl, canonicalUrl
Business	listingStatus, businessType, categories, description, priceRange
Public signals	rating, reviewCount, explicitly published phone, explicitly published email, websiteUrls
Location	address, city, state, postalCode, country, latitude, longitude, hours
Media	imageUrls, logoUrl when associated with the business by the public page
Provenance	source, sourceUrl, pageUrl, searchUrl, query, location, pageNumber, itemPosition, scrapedAt
Diagnostics	url, error, errorCode, scrapedAt on minimal diagnostic rows only

The Actor does not turn unknown ratings, review counts, addresses, contacts, or websites into fabricated values. Arrays are bounded by the runtime. A normal record is retained when optional detail enrichment fails; there is no invented fallback value and no separate detail-error field in the dataset contract. Operational detail failures remain in OUTPUT_SUMMARY.

Input

All limits below are enforced by runtime validation as well as represented in the input schema. maxItems is global across all start URLs and pages. maxPages is per start URL. Deduplication is global across sources when enabled. When a non-relevance sort is selected, the Actor collects the bounded candidate set, filters it, sorts it globally, and then applies maxItems.

Field	Type and default	Range or values	Behavior
query	string, restaurants	max 300 characters	Used with location only when startUrls is empty.
location	string, New York, NY	max 300 characters	Used with query only when startUrls is empty.
sourceMode	string, public	public, yelpFusionApi	Selects public-page extraction or the official Yelp Fusion API. API mode never falls back to public pages.
yelpApiKey	secret string, omitted	max 512 characters	Required for yelpFusionApi; sent only as a Bearer header and never written to output or logs.
startUrls	array, omitted	1–20 objects with required url	HTTPS yelp.com search, city/location, or business URLs; takes precedence over generated search. Legacy strings are accepted by runtime compatibility.
keyword	string, ""	max 300 characters	Case-insensitive filter over name, description, categories, and address.
minRating	number, 0	0–5	Missing ratings do not pass a positive minimum.
minReviewCount	integer, 0	0–1,000,000,000	Keeps records with an observed count at or above the value.
hasWebsite	boolean, false	true or false	Requires an explicitly published non-Yelp website.
hasPhone	boolean, false	true or false	Requires an explicitly published phone number.
hasEmail	boolean, false	true or false	Requires an explicitly published email; the Actor never guesses one.
sortBy	string, relevance	relevance, name_asc, rating_desc, reviews_desc	Global bounded sort; ties retain source order.
maxItems	integer, 20	1–100	Global maximum normal business records.
maxPages	integer, 1	1–20 per source	Uses a public next link when available, otherwise a bounded Yelp search offset.
deduplicate	boolean, true	true or false	Deduplicates by business ID, alias, canonical business URL, or record ID.
includeDetails	boolean, true	true or false	Requests selected public business profiles after the source set is collected.
maxDetailItems	integer, 5	0–20	Maximum detail requests; 0 disables detail requests. It also cannot exceed the normal record count.
includeDiagnostics	boolean, true	true or false	Emits minimal diagnostic dataset rows for blocks and request failures when true.
requestDelayMs	integer, 250	0–5,000	Delay before each public request; zero is intended for bounded QA.
maxRequestRetries	integer, 1	0–3	Retries network failures only; a clear access block is not retried indefinitely.
timeoutMs	integer, 30,000	5,000–120,000	Per-request timeout in milliseconds.
proxyConfiguration	object, { "useApifyProxy": false }	Apify Proxy object	When enabled, passed to got-scraping; it does not bypass access controls. Direct access is the default.
fixturePath	string, ""	max 500 characters, Actor-relative	Reads an explicit local HTML fixture for deterministic QA; it makes no network request and is not a live fallback.

Official Yelp Fusion API mode

Use the API mode only with a Yelp API key authorized for the official business search and detail endpoints. The key is a secret input and is not included in OUTPUT_SUMMARY, dataset rows, or logs. Start with a small bounded request:

{
  "sourceMode": "yelpFusionApi",
  "yelpApiKey": "PASTE_IN_THE_SECRET_INPUT_FIELD",
  "query": "coffee",
  "location": "New York, NY",
  "maxItems": 5,
  "maxPages": 1,
  "includeDetails": true,
  "maxDetailItems": 2
}

Do not use a Fusion key to claim email coverage: ordinary Fusion does not return business emails. If the key is omitted, the Actor emits YELP_API_KEY_REQUIRED without making a public-page request; if Yelp denies the endpoint, inspect the API diagnostic and obtain the required authorization rather than switching to a bypass.

Quick smoke test

{
  "query": "coffee",
  "location": "New York, NY",
  "maxItems": 5,
  "maxPages": 1,
  "includeDetails": false,
  "maxDetailItems": 0,
  "requestDelayMs": 250
}

Filters and global sorting

{
  "startUrls": [
    { "url": "https://www.yelp.com/search?find_desc=coffee&find_loc=New%20York%2C%20NY" },
    { "url": "https://www.yelp.com/search?find_desc=bakery&find_loc=Boston%2C%20MA" }
  ],
  "keyword": "roaster",
  "minRating": 4,
  "minReviewCount": 10,
  "hasWebsite": true,
  "sortBy": "rating_desc",
  "maxItems": 20,
  "maxPages": 2,
  "deduplicate": true,
  "includeDetails": false
}

Detail opt-out and diagnostics opt-out

{
  "query": "restaurants",
  "location": "Chicago, IL",
  "maxItems": 10,
  "maxPages": 1,
  "includeDetails": false,
  "maxDetailItems": 0,
  "includeDiagnostics": false
}

Developer and fixture QA

{
  "startUrls": [
    { "url": "https://www.yelp.com/search?find_desc=coffee&find_loc=New%20York%2C%20NY" }
  ],
  "maxItems": 3,
  "maxPages": 1,
  "requestDelayMs": 0,
  "maxRequestRetries": 0,
  "timeoutMs": 30000,
  "proxyConfiguration": { "useApifyProxy": false },
  "fixturePath": "test/fixtures/sample.html"
}

Output

Rich normal record

{
  "recordId": "yelp:acme-coffee-roasters",
  "businessId": "acme-coffee-roasters",
  "name": "Acme Coffee Roasters",
  "businessUrl": "https://www.yelp.com/biz/acme-coffee-roasters",
  "canonicalUrl": "https://www.yelp.com/biz/acme-coffee-roasters",
  "categories": ["Coffee", "Bakery"],
  "rating": 4.5,
  "reviewCount": 120,
  "phone": "+1 212 555 0100",
  "websiteUrls": ["https://example.test/"],
  "address": "10 Main Street, New York, NY, 10001",
  "sourceUrl": "https://www.yelp.com/search?find_desc=coffee&find_loc=New%20York",
  "pageUrl": "https://www.yelp.com/biz/acme-coffee-roasters",
  "pageNumber": 1,
  "itemPosition": 1,
  "scrapedAt": "2026-09-08T00:00:00.000Z"
}

Detail fallback

When a selected profile request is blocked or fails, the previously collected base record is kept. Fields not present on that base record are omitted; no placeholder detail value is fabricated.

{
  "recordId": "yelp:acme-coffee-roasters",
  "businessId": "acme-coffee-roasters",
  "name": "Acme Coffee Roasters",
  "businessUrl": "https://www.yelp.com/biz/acme-coffee-roasters",
  "sourceUrl": "https://www.yelp.com/search?find_desc=coffee&find_loc=New%20York",
  "pageUrl": "https://www.yelp.com/search?find_desc=coffee&find_loc=New%20York",
  "pageNumber": 1,
  "itemPosition": 1,
  "scrapedAt": "2026-09-08T00:00:00.000Z"
}

Diagnostic record

{
  "url": "https://www.yelp.com/search?find_desc=coffee&find_loc=New%20York",
  "error": "Public Yelp page returned HTTP 403; no access-control bypass was attempted.",
  "errorCode": "BLOCKED_SOURCE_CHALLENGE",
  "scrapedAt": "2026-09-08T00:00:00.000Z"
}

OUTPUT_SUMMARY key-value item

{
  "actor": "b2b_leads/yelp-b2b-lead-extractor",
  "target": "yelp.com",
  "status": "BLOCKED_SOURCE_CHALLENGE",
  "normalRecordCount": 0,
  "diagnosticCount": 1,
  "dataAvailable": false,
  "sourceCount": 1,
  "pagesVisited": 1,
  "filteredOutCount": 0,
  "duplicateCount": 0,
  "detailRequestedCount": 0,
  "detailEnrichedCount": 0,
  "detailFailureCount": 0,
  "failedRequestCount": 0,
  "blockedReasons": ["BLOCKED_SOURCE_CHALLENGE"],
  "fixtureUsed": false,
  "sourceTransport": "got_scraping_direct",
  "sourceMode": "public",
  "apiCredentialConfigured": false,
  "apiRequestCount": 0,
  "unsupportedFields": [],
  "completedAt": "2026-09-08T00:00:00.000Z"
}

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

Tips and advanced options

Start with one source URL, one page, a small item limit, no detail enrichment, and the default delay. Increase maxPages, maxItems, and maxDetailItems only as needed; this Actor intentionally has no concurrency input and performs requests serially. A page with zero filter matches does not by itself stop allowed pagination, but the run stops on source exhaustion, repeated pages, the configured page limit, or an access block.

Use fixturePath and test/fixtures/sample.html for deterministic parser QA. Fixture records are not evidence that the live Yelp source is accessible. For public source requests, ordinary headers, finite retries, bounded timeouts, and delay are used. Proxy configuration is transparent and optional; it is not a promise of rotation success or a way around Yelp controls.

FAQ, support, and responsible use

Why did I receive only a diagnostic row?

Yelp may return HTTP 403/429, a DataDome or CAPTCHA challenge, an incomplete page, a redirect outside yelp.com, or a network timeout. The Actor reports that state instead of pretending it was an empty successful search. A fixture pass is separate from a live-source qualification.

Where do I report a problem or use the API?

Use the Actor's Issues tab and include the run ID, input shape, OUTPUT_SUMMARY, and error code; do not paste tokens, cookies, proxy credentials, or private page content. Use the Console API/API tab to retrieve the dataset and key-value summary, or schedule and monitor runs through Apify.

Legal, privacy, and affiliation

Use this Actor only for public pages and in accordance with Yelp's terms, robots guidance, rate limits, privacy obligations, and applicable law. Public pages can contain personal data; process results only for a legitimate, documented purpose and consult qualified counsel when unsure. This Actor is not affiliated with, endorsed by, or sponsored by Yelp. It does not extract private user data or bypass authentication, CAPTCHAs, paywalls, or other access controls.